spb/trouve-ka

1# Trouve-KA — Runbook d'exploitation23Author: Simon-Pierre Boucher — Contact: contact@spboucher.ai45Architecture : voir `docs/architecture.md`. Résumé : **M2M32** (hub : Postgres+Redis6docker, API/web/workers/scheduler/enrichment natifs pm2, ngrok), **M2M32b**7(OpenSearch docker, heap 8 G), **m4mc** (embeddings+reranker), satellites de8crawl (M2M32c, M4BP48, M1M32, m4ma). Tout le trafic inter-nodes passe par des9**tunnels ssh système sur 127.0.0.1** (contournement du blocage « réseau10local » macOS, qui filtre par binaire : python non signé bloqué, ssh/curl11Apple exempts).1213## Auto-guérison (rien à faire dans la plupart des cas)1415| Mécanisme | Où | Cadence |16|---|---|---|17| `io.trouveka.boot` (boot.sh) | tous les nodes | au démarrage du node |18| `io.trouveka.watchdog` (watchdog.sh) | M2M32 | toutes les 2 min |19| Passe de flotte (heal tous les satellites) | M2M32 | ~30 min |20| `io.trouveka.backup-pg` / `backup-os` / `pull` | M2M32 / M2M32b | quotidien 03:30–04:40 |21| Rétention PG (crawl_attempts 30 j, search_queries 180 j) | scheduler tk-scheduler | quotidien |2223Prouvé en conditions réelles : API tuée → ressuscitée en 40 s; reboot complet24de m4ma → tunnels+worker revenus sans intervention.2526Journaux : `~/trouveka-watchdog.log`, `~/trouveka-boot.log`,27`~/trouveka-backups/backup.log`, `~/trouveka-launchd.log` sur chaque node.2829## Clés SSH dédiées (jamais de clé à accès complet sur un node)3031| Clé | Détenue par | Autorisée sur | Pouvoir exact |32|---|---|---|---|33| `trouveka_tunnel` (par node) | chaque node | M2M32, M2M32b | port-forwarding seulement |34| `trouveka_heal` | M2M32 | tous les satellites | exécuter `boot.sh` uniquement |35| `trouveka_pull` | M2M32 ↔ M2M32b | l'autre node | `tar` du dossier de backups uniquement |3637⚠️ Toute invocation ssh opérationnelle utilise `ControlMaster=no`,38`IdentitiesOnly=yes`, `IdentityAgent=none` — sans quoi le multiplexage/agent39d'une session humaine court-circuite les restrictions.4041## Pannes et remèdes4243- **Recherche en panne / site public muet** : attendre 2-4 min (watchdog).44  Sinon : `ssh M2M32 'sh ~/trouve-ka/scripts/ops/boot.sh'` puis45  `tail ~/trouveka-watchdog.log`.46- **Un node ne crawle plus** : `ssh M2M32` puis47  `/usr/bin/ssh -i ~/.ssh/trouveka_heal -o IdentitiesOnly=yes -o IdentityAgent=none -o ControlMaster=no -o ControlPath=none simon-pierreboucher@<IP> heal`48  (IP dans `~/.trouveka-fleet`).49- **Après reboot d'un node : Tailscale absent** (app GUI, exige une session).50  Le moteur n'en dépend PAS (tout passe par le LAN). Pour retrouver l'accès51  distant direct : ouvrir une session (écran/VNC) une fois, ou passer par52  `ssh -J M2M32 simon-pierreboucher@<IP LAN>`.53- **Transactions Postgres zombies** (verrous, autovacuum bloqué) :54  `SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE usename='trouveka' AND now()-xact_start > interval '5 minutes';`55  (les timeouts serveur limitent déjà ça à ≤5 min).5657## Restauration après sinistre5859- **Postgres perdu** (dumps : `~/trouveka-backups/pg/` sur M2M32, miroir sur60  M2M32b `~/trouveka-backups/pg-mirror/`) :61  `docker exec -i trouve-ka-postgres-1 pg_restore -U trouveka -d trouveka --clean --if-exists < trouveka-YYYYMMDD.dump`62- **OpenSearch perdu** (snapshots : `~/trouveka-os-snapshots/` sur M2M32b,63  miroir sur M2M32 `~/trouveka-backups/os-mirror/`) : recréer le container64  avec `path.repo=/mnt/snapshots` + le volume, puis65  `PUT _snapshot/trouveka-fs` (même corps que backup-os.sh) et66  `POST _snapshot/trouveka-fs/daily-YYYYMMDD/_restore`.67  Si les deux copies sont perdues : le moteur se reconstruit par recrawl68  (Postgres garde URLs/domaines/priorités — c'est lui le capital).69- **Un node de crawl perdu** : rien à restaurer — réinstaller le rôle :70  `SUDO_PW=... sh ~/trouve-ka/scripts/ops/install-node.sh crawler` + clé71  tunnel (voir mémoire projet).7273## Déploiement de code7475```76rsync -az --delete --exclude .env --exclude .venv --exclude .venv-embed \77  --exclude node_modules --exclude .next --exclude __pycache__ --exclude .git \78  /Users/simon-pierreboucher/Desktop/trouve-ka/  <node>:trouve-ka/   # CHEMIN ABSOLU !79ssh M2M32 'pm2 restart tk-api tk-crawler-1 tk-crawler-2 tk-enrichment tk-scheduler'80# web : cd ~/trouve-ka/apps/web && pnpm build && pm2 restart tk-web81# satellites : heal (boot.sh relance le worker avec le nouveau code après pkill)82```83