anchorage_layer_simple/fixKnowledge/api-anchorage-health-503-remediation.md

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.