937646cc45
**Motivations:** - Export Signet and mining wallet backups to git with only 2 versions kept - Document and add backup/restore scripts for signet and mining wallet **Correctifs:** - Backup-to-git uses SSH URL for passwordless cron; copy timestamped files only; prune to 2 versions; remove *-latest from backup repo **Evolutions:** - data/backup-to-git-cron.sh: daily export to git.4nkweb.com/4nk/backup - save-signet-datadir-backup.sh, restore-signet-from-backup.sh, export-mining-wallet.sh, import-mining-wallet.sh - features/backup-to-git-daily-cron.md, docs/MAINTENANCE.md backup section - .gitignore: data/backup-to-git.log **Pages affectées:** - .gitignore, data/backup-to-git-cron.sh, docs/MAINTENANCE.md, features/backup-to-git-daily-cron.md - save-signet-datadir-backup.sh, restore-signet-from-backup.sh, export-mining-wallet.sh, import-mining-wallet.sh - Plus autres fichiers modifiés ou non suivis déjà présents dans le working tree
83 lines
4.7 KiB
Markdown
83 lines
4.7 KiB
Markdown
# Correction: Health check anchor-api HTTP 503 – causes et remédiation
|
||
|
||
**Date:** 2026-01-28
|
||
**Auteur:** Équipe 4NK
|
||
|
||
## Problème
|
||
|
||
Le health check de l’API d’ancrage renvoie HTTP 503, avec des messages du type « Health check a échoué (HTTP 503) » ou « L’API d’ancrage n’est pas accessible », sans indiquer la cause précise.
|
||
|
||
**Machine concernée :** 192.168.1.105 (bitcoin)
|
||
**Domaine externe :** https://anchorage.certificator.4nkweb.com
|
||
**Service :** anchorage-api (port 3010)
|
||
|
||
### Impact
|
||
|
||
- Monitoring ou dashboard marquent l’API comme indisponible sans distinguer « processus arrêté » et « pas prêt » (Bitcoin déconnecté, UTXOs verrouillés).
|
||
- L’utilisateur ne voit pas la raison du 503 (Bitcoin, mutex, UTXOs stale) pour agir.
|
||
|
||
## Root cause
|
||
|
||
1. **Causes du 503 côté api-anchorage** (`src/routes/health.js`) :
|
||
- **GET /health** : 503 si Bitcoin RPC non connecté ou si `checkConnection()` lève.
|
||
- **GET /health/detailed** : 503 si Bitcoin non connecté, ou UTXOs verrouillés depuis > 10 min (`stale_locks > 0`), ou plus de 10 UTXOs verrouillés.
|
||
|
||
2. **Causes côté consommateur** :
|
||
- Le dashboard proxy renvoyait 200 avec un body réduit au lieu de transmettre le 503 et le body complet → le client ne voyait pas la raison.
|
||
- Aucun endpoint de liveness (processus vivant) → impossible de distinguer « service down » et « service up mais not ready ».
|
||
|
||
## Correctifs
|
||
|
||
### 1. api-anchorage : endpoint de liveness
|
||
|
||
- **GET /health/live** : retourne toujours 200 tant que le processus tourne (sans vérifier Bitcoin ni mutex).
|
||
- Usage : monitoring / load-balancer pour ne pas considérer le service comme mort quand il renvoie 503 (readiness).
|
||
- Exclusion de l’auth API Key pour `/health/live` dans `server.js`.
|
||
|
||
### 2. signet-dashboard : propagation du 503 et du body
|
||
|
||
- Option **preserveStatus** dans `makeHttpRequest` : retourne `{ statusCode, body }` pour préserver le code HTTP et le body JSON.
|
||
- Route **GET /api/anchor/health/detailed** : appelle l’API d’ancrage avec `preserveStatus: true`, puis répond avec `res.status(result.statusCode).json(result.body)`.
|
||
- Effet : en cas de 503, le client reçoit 503 et le détail (bitcoin.connected, mutex, utxos, stale_locks).
|
||
|
||
### 3. signet-dashboard (hash-list.html) : affichage de la raison
|
||
|
||
- Si la réponse est 503 et que le body n’a pas la structure health (mutex, utxos, bitcoin), affichage d’un message d’erreur incluant `health.error` ou `health.message` et le code 503.
|
||
- Si la réponse est 503 mais que le body contient le health complet, affichage du panneau health normal avec mention « 503 - voir détails ci-dessous » pour l’état général.
|
||
- En cas d’exception (réseau, parse), affichage de « L’API d’ancrage n’est pas accessible » avec le message d’erreur.
|
||
|
||
## Modifications
|
||
|
||
**Motivations :**
|
||
- Rendre le 503 explicable (Bitcoin, mutex, UTXOs) et permettre une remédiation ciblée.
|
||
- Séparer liveness (processus up) et readiness (prêt à ancrer).
|
||
|
||
**Root causes :**
|
||
- 503 défini par l’API sans toujours être propagé avec son body ; pas de liveness.
|
||
|
||
**Correctifs :**
|
||
- GET /health/live dans api-anchorage ; propagation 503 + body dans le dashboard ; affichage de la raison dans hash-list.
|
||
|
||
**Pages affectées :**
|
||
- `api-anchorage/src/routes/health.js` (GET /health/live)
|
||
- `api-anchorage/src/server.js` (exclusion auth /health/live)
|
||
- `signet-dashboard/src/server.js` (preserveStatus, route health/detailed)
|
||
- `signet-dashboard/public/hash-list.html` (affichage erreur 503 et raison)
|
||
|
||
## Modalités de remédiation en production
|
||
|
||
Quand le health check renvoie 503 :
|
||
|
||
1. **Vérifier liveness** : `curl -s https://anchorage.certificator.4nkweb.com/health/live` → 200 si le processus tourne.
|
||
2. **Lire la cause** : `curl -s https://anchorage.certificator.4nkweb.com/health/detailed` (ou via le dashboard) et regarder :
|
||
- `bitcoin.connected === false` → vérifier Bitcoin Core (RPC) sur 192.168.1.105.
|
||
- `utxos.stale_locks > 0` ou `utxos.locked > 10` → déverrouiller les UTXOs (voir ci-dessous).
|
||
3. **Service arrêté** : sur la machine 192.168.1.105, `systemctl status anchorage-api` puis `sudo systemctl restart anchorage-api` si besoin.
|
||
4. **UTXOs verrouillés** : sur la machine hébergeant api-anchorage, exécuter `node unlock-utxos.mjs` dans le répertoire api-anchorage, ou utiliser le bouton « Déverrouiller les UTXOs » depuis le dashboard (hash-list) si l’API est de nouveau joignable.
|
||
|
||
## Modalités d’analyse
|
||
|
||
- Consulter les logs du service : `journalctl -u anchorage-api -n 100`.
|
||
- Vérifier le RPC Bitcoin : `bitcoin-cli -rpcconnect=... getblockchaininfo`.
|
||
- Appeler GET /health/detailed et interpréter `ok`, `bitcoin.connected`, `utxos.locked`, `utxos.stale_locks`.
|