# Trouve-KA — Runbook d'exploitation

Author: Simon-Pierre Boucher — Contact: contact@spboucher.ai

Architecture : voir docs/architecture.md. Résumé : M2M32 (hub : Postgres+Redis docker, API/web/workers/scheduler/enrichment natifs pm2, ngrok), M2M32b (OpenSearch docker, heap 8 G), m4mc (embeddings+reranker), satellites de crawl (M2M32c, M4BP48, M1M32, m4ma). Tout le trafic inter-nodes passe par des tunnels ssh système sur 127.0.0.1 (contournement du blocage « réseau local » macOS, qui filtre par binaire : python non signé bloqué, ssh/curl Apple exempts).

# Auto-guérison (rien à faire dans la plupart des cas)

Mécanisme	Où	Cadence
`io.trouveka.boot` (boot.sh)	tous les nodes	au démarrage du node
`io.trouveka.watchdog` (watchdog.sh)	M2M32	toutes les 2 min
Passe de flotte (heal tous les satellites)	M2M32	~30 min
`io.trouveka.backup-pg` / `backup-os` / `pull`	M2M32 / M2M32b	quotidien 03:30–04:40
Rétention PG (crawl_attempts 30 j, search_queries 180 j)	scheduler tk-scheduler	quotidien

Prouvé en conditions réelles : API tuée → ressuscitée en 40 s; reboot complet de m4ma → tunnels+worker revenus sans intervention.

Journaux : ~/trouveka-watchdog.log, ~/trouveka-boot.log, ~/trouveka-backups/backup.log, ~/trouveka-launchd.log sur chaque node.

# Clés SSH dédiées (jamais de clé à accès complet sur un node)

Clé	Détenue par	Autorisée sur	Pouvoir exact
`trouveka_tunnel` (par node)	chaque node	M2M32, M2M32b	port-forwarding seulement
`trouveka_heal`	M2M32	tous les satellites	exécuter `boot.sh` uniquement
`trouveka_pull`	M2M32 ↔ M2M32b	l'autre node	`tar` du dossier de backups uniquement

⚠️ Toute invocation ssh opérationnelle utilise ControlMaster=no, IdentitiesOnly=yes, IdentityAgent=none — sans quoi le multiplexage/agent d'une session humaine court-circuite les restrictions.

# Pannes et remèdes

Recherche en panne / site public muet : attendre 2-4 min (watchdog). Sinon : ssh M2M32 'sh ~/trouve-ka/scripts/ops/boot.sh' puis tail ~/trouveka-watchdog.log.
Un node ne crawle plus : ssh M2M32 puis /usr/bin/ssh -i ~/.ssh/trouveka_heal -o IdentitiesOnly=yes -o IdentityAgent=none -o ControlMaster=no -o ControlPath=none simon-pierreboucher@<IP> heal (IP dans ~/.trouveka-fleet).
Après reboot d'un node : Tailscale absent (app GUI, exige une session). Le moteur n'en dépend PAS (tout passe par le LAN). Pour retrouver l'accès distant direct : ouvrir une session (écran/VNC) une fois, ou passer par ssh -J M2M32 simon-pierreboucher@<IP LAN>.
Transactions Postgres zombies (verrous, autovacuum bloqué) : SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE usename='trouveka' AND now()-xact_start > interval '5 minutes'; (les timeouts serveur limitent déjà ça à ≤5 min).

# Restauration après sinistre

Postgres perdu (dumps : ~/trouveka-backups/pg/ sur M2M32, miroir sur M2M32b ~/trouveka-backups/pg-mirror/) : docker exec -i trouve-ka-postgres-1 pg_restore -U trouveka -d trouveka --clean --if-exists < trouveka-YYYYMMDD.dump
OpenSearch perdu (snapshots : ~/trouveka-os-snapshots/ sur M2M32b, miroir sur M2M32 ~/trouveka-backups/os-mirror/) : recréer le container avec path.repo=/mnt/snapshots + le volume, puis PUT _snapshot/trouveka-fs (même corps que backup-os.sh) et POST _snapshot/trouveka-fs/daily-YYYYMMDD/_restore. Si les deux copies sont perdues : le moteur se reconstruit par recrawl (Postgres garde URLs/domaines/priorités — c'est lui le capital).
Un node de crawl perdu : rien à restaurer — réinstaller le rôle : SUDO_PW=... sh ~/trouve-ka/scripts/ops/install-node.sh crawler + clé tunnel (voir mémoire projet).

# Déploiement de code

text

rsync -az --delete --exclude .env --exclude .venv --exclude .venv-embed \
  --exclude node_modules --exclude .next --exclude __pycache__ --exclude .git \
  /Users/simon-pierreboucher/Desktop/trouve-ka/  <node>:trouve-ka/   # CHEMIN ABSOLU !
ssh M2M32 'pm2 restart tk-api tk-crawler-1 tk-crawler-2 tk-enrichment tk-scheduler'
# web : cd ~/trouve-ka/apps/web && pnpm build && pm2 restart tk-web
# satellites : heal (boot.sh relance le worker avec le nouveau code après pkill)