Dépanner une instance auto-hébergée

Note l’heure, l’organisation, l’URL ou l’action concernée et le code d’erreur avant tout redémarrage. Détermine si le problème touche un élément, une organisation ou tout le déploiement. Cette distinction oriente l’enquête vers un fichier, une connexion d’organisation ou l’infrastructure partagée.

Pour un déploiement dans un workspace, commence par tale status et tale logs <service> --tail 200. Dans ton propre projet Compose, utilise docker compose ps et docker compose logs --tail=200 <service>. Les noms de services comme platform et backend-api diffèrent des noms de conteneurs générés.

Échec de l’URL publique, du certificat ou de la connexion

Une interface chargée mais vide oriente d’abord vers les requêtes applicatives, pas forcément le serveur web. Examine les requêtes échouées et les journaux backend-api. Proxy, session expirée, refus de permission et panne backend demandent des corrections différentes. TLS et domaines et Authentification décrivent leur configuration.

Distinguer le processus web de la disponibilité de l’application

/api/health vérifie le processus web. /api/health/ready atteint backend-api et effectue une requête vers la base de données ; une réponse saine est HTTP 200 avec {"ok":true,"service":"backend"}. Teste les deux routes par l’URL publique, en incluant son chemin de base. Une page d’erreur HTML, une redirection ou une ancienne réponse en cache ne prouve pas que l’application est prête.

Le navigateur vérifie la disponibilité toutes les 30 secondes en fonctionnement normal et réessaie cinq secondes après un échec, avec un délai maximal de huit secondes par requête. Après une panne, les lectures ayant échoué sont actualisées automatiquement. Les écritures demandent une nouvelle tentative explicite. Un Service Worker déjà installé affiche la page de connexion en cache lorsqu’une navigation échoue, dépasse le délai ou reçoit un 5xx du proxy, puis vérifie automatiquement le retour du service. Une première visite pendant une panne dépend de la page d’indisponibilité du proxy, car aucun Service Worker n’a encore été installé.

Si un ancien onglet ne charge plus un module après un déploiement, vérifie que chaque réplique web monte le même volume static-assets et a fini de publier ses fichiers avant d’être prête. Voir Mettre à niveau et récupérer un déploiement.

Échec d’envoi ou de téléchargement des fichiers

Compare la réponse du serveur à la requête du navigateur vers l’URL présignée. Une seule organisation peut avoir une connexion de stockage défaillante alors que le bucket par défaut reste accessible.

tale_backend_store_up couvre les valeurs par défaut et mesure l’accessibilité, pas un import complet. Un 403 du stockage objet peut malgré tout donner la valeur 1. Après correction, vérifie un envoi et un téléchargement contrôlés. Résidence des données explique les changements de connexion et la migration des fichiers.

Un document reste non indexé

Examine son statut et son motif d’échec, puis les journaux backend-worker. Confirme modèle et identifiants d’embedding de l’organisation, dimensions des vecteurs, connexion de connaissances et format du fichier. Un import réussi prouve seulement le stockage du fichier d’origine.

Si un worker ou une dépendance était indisponible, rétablis-le puis vérifie si le job reprend ou demande Indexer maintenant dans Connaissances. Pour une source endommagée, chiffrée ou non prise en charge, corrige le fichier avant de réessayer. Ne supprime pas un document comme première étape : son identité, son historique et ses références peuvent compter.

Un scan de site signale une erreur de certificat

L’erreur de crawl tls_error indique un échec de négociation TLS : certificat expiré, nom d’hôte différent ou chaîne non reconnue, par exemple. Corrige le certificat du site ou la configuration de confiance du processus de crawl, puis lance un nouveau scan. Répéter la même requête ne répare pas la confiance du certificat ; ne désactive pas sa vérification pour masquer l’échec.

network_error indique plutôt un échec de connexion. Lis sa cause et vérifie le DNS, le routage et la disponibilité du service. Explorer les sites web explique les erreurs par page et les résultats des scans.

Postgres de connaissances plante pendant l’ingestion

Des erreurs répétées PANIC: corrupted page pointers ou signal 6 peuvent signaler un index BM25 endommagé. Examine les journaux de la base et le résultat de la réparation automatique dans Architecture des conteneurs. Confirme la base exacte : dans le stack fourni, il s’agit de tale_knowledge dans db ; ailleurs, un service séparé ou un hôte externe peut la porter.

Depuis une session SQL autorisée sur cette base, cette requête vérifie seulement l’index indiqué :

SELECT * FROM pdb.verify_index('private_knowledge.idx_pk_chunks_bm25');

Une fonction absente, un refus de permission ou un délai dépassé ne confirme pas une corruption. Si le dommage est établi et que la réparation automatique a échoué, préserve une sauvegarde et planifie une maintenance de base. Reconstruire un index dérivé diffère de supprimer les tables de documents :

REINDEX INDEX private_knowledge.idx_pk_chunks_bm25;

Cette commande non concurrente peut bloquer du travail. Coordonne-la avec l’exploitation de la base, vérifie de nouveau l’index puis la reprise de l’ingestion. Ne lance pas de réindexation ou d’installation d’extension spéculative sur la mauvaise base. Une corruption répétée demande d’examiner le disque et les arrêts forcés après le délai de grâce.

Un chat ou une automatisation s’arrête

Lis l’erreur du chat ou de l’exécution et les journaux API/worker correspondants. Un 429 fournisseur, un refus d’identifiants, un timeout, une attente d’approbation et une déconnexion du flux navigateur sont des états différents. Une approbation attend une décision, pas un redémarrage. Un flux coupé peut masquer une opération toujours active ; lis son résultat enregistré avant de relancer.

Pour un échec fournisseur, vérifie quota et permissions des identifiants choisis, ainsi que l’état du fournisseur. Ne change de modèle que si le remplacement est autorisé et adapté. Pour un échec d’environnement d’agent, examine sandbox, sandbox-llm-gateway, l’image d’exécution et les journaux de session.

L’accès réseau de la sandbox est refusé

Examine sandbox-egress et l’URL cible. Une SANDBOX_EGRESS_ALLOWLIST configurée doit contenir l’hôte nécessaire ; les destinations privées et de métadonnées cloud restent bloquées. Les tunnels HTTPS suivent la politique de ports prise en charge. Confirme la destination voulue avant d’élargir la liste, puis recrée le service de sortie après un changement d’environnement.

Un processus de sortie sain ne prouve pas la disponibilité de l’hôte distant, du DNS, du certificat ou du compte. Conserve l’erreur précise dans le rapport d’incident.

Quand de nombreuses sessions installent des paquets ou chargent des pages en même temps et que des connexions échouent sur des réinitialisations alors que le proxy reste sain, il a peut-être atteint SANDBOX_EGRESS_MAX_CLIENTS, les connexions qu’il sert en même temps pour toutes les sessions réunies. Son journal indique alors que le nombre maximal de connexions est atteint. Augmente la valeur, avec les limites de processus et de fichiers ouverts du conteneur de sortie, puis recrée le service de sortie.

Quand les connexions d’une seule session échouent sur des réinitialisations alors que d’autres sessions atteignent encore les mêmes hôtes, cette session détient peut-être déjà SANDBOX_EGRESS_MAX_CONNECTIONS_PER_SESSION connexions (256 par défaut), et le proxy refuse les suivantes jusqu’à ce que certaines se ferment. Augmente la valeur, ou mets 0 pour désactiver la limite, puis recrée le service de sortie.

Un service sandbox-egress recréé (après un déploiement ou un redémarrage de la pile) peut revenir à une autre adresse, alors que les sessions qui tournaient déjà continuent d’envoyer leur trafic à l’ancienne et perdent l’accès réseau. Le service sandbox recycle chacune de ces sessions dès qu’elle est libérée et inactive, et consigne recycling <session> ; la prochaine utilisation la redémarre avec son espace de travail intact. Une session encore utilisée continue d’échouer jusqu’à la fin de son travail, et une session épinglée continue de tourner jusqu’à ce que tu l’arrêtes ou ne l’épingles plus.

Les écritures échouent ou le stockage se remplit

Vérifie connexion à la base applicative, espace libre, usage des connexions et verrous. Arrête la croissance évitable et récupère de la capacité selon ta procédure de base. Ne supprime pas le contenu des volumes, ne remplace pas les clés de chiffrement et ne suppose pas que les écritures échouées seront rejouées après redémarrage. Vérifie si l’opération a persisté avant de la relancer.

Pour demander de l’aide, fournis versions, erreurs nettoyées, période, périmètre et étapes de reproduction. tale diagnostics rassemble un diagnostic ; examine l’archive avant de la partager, car des détails du déploiement peuvent rester sensibles. Signale les défauts reproductibles dans le suivi des problèmes du projet.