nas-runbooks/common/bifrost-update-procedure.md

Procédure de Mise à Jour de Bifrost (Gateway LLM)

Contexte et Emplacement

• Emplacement : /volume1/docker/bifrost/
• Compose : /volume1/docker/bifrost/docker-compose.yml
• Port : 3085 (interne n8n, non exposé WAN direct)
• Réseau : n8n

---

Précautions Critiques et Pièges Connus

1. Pin Explicite de Version Obligatoire : Ne jamais laisser image: maximhq/bifrost sans tag (ce qui équivaut à un :latest implicite et provoque des dérives silencieuses). Toujours épingler la version cible exacte, ex. : image: maximhq/bifrost:v1.6.11.

2. Sauvegarde Double Préalable : Dans /volume1/docker/bifrost/data/, il existe deux fichiers de configuration essentiels :

   • config.db (base SQLite contenant la gouvernance, les virtual keys, les budgets et le mapping providers)
   • config.json (configuration des providers et clés API amont) Toujours sauvegarder les deux fichiers avec horodatage avant toute intervention :

   cd /volume1/docker/bifrost/data
   cp config.db "config.db.bak-$(date +%Y%m%d-%H%M%S)"
   cp config.json "config.json.bak-$(date +%Y%m%d-%H%M%S)"
   

3. Mécanisme de Rechargement des Clés Provider (Governance) : Au redémarrage d'un conteneur recréé, les virtual keys utilisent les autorisations enregistrées dans la table governance_virtual_key_provider_configs (allow_all_keys = 1). Si après un restart un appel renvoie provider not found, vérifier et réactiver allow_all_keys dans config.db :

   UPDATE governance_virtual_key_provider_configs SET allow_all_keys = 1;
   

4. Taille de logs.db : Le fichier /volume1/docker/bifrost/data/logs.db enregistre l'historique complet des requêtes et tokens. Il peut atteindre plusieurs dizaines de Go (~98 Go relevés en août 2026). Ne pas tronquer sans validation explicite.

---

Procédure Standard de Mise à Jour

# 1. Sauvegardes
cd /volume1/docker/bifrost/data
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
cp config.db "config.db.bak-$TIMESTAMP"
cp config.json "config.json.bak-$TIMESTAMP"

# 2. Modifier le tag dans docker-compose.yml
# image: maximhq/bifrost:vX.Y.Z

# 3. Pull et Recréation
cd /volume1/docker/bifrost
docker compose pull
docker compose up -d --force-recreate

# 4. Vérifications
curl -s http://192.168.100.33:3085/health        # doit renvoyer {"components":{"db_pings":"ok"},"status":"ok"}
curl -s http://192.168.100.33:3085/api/version   # doit renvoyer la nouvelle version

# 5. Test réel de complétion avec une Virtual Key valide
curl -s http://192.168.100.33:3085/v1/chat/completions   -H "Authorization: Bearer $BIFROST_VK"   -H "Content-Type: application/json"   -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "ping"}],
    "max_tokens": 5
  }'