Aller au contenu

Diagnostic technique

Repérez le symptôme, puis reprenez la procédure correspondante après correction de la cause.

Symptôme Point à vérifier Procédure
PostgreSQL inaccessible Service démarré, adresse et port, règle de pg_hba.conf ; si PostgreSQL est chiffré, règle hostssl, CA et nom du certificat PostgreSQL, PostgreSQL SSL
vector ou unaccent introuvable Extension installée pour PostgreSQL 18, puis activée dans la bonne base Bases
Échec de init Même YAML et environnement que le futur service, connexion base, stockage disponible Platform
init ou API refusés par S3, « Le stockage des fichiers est injoignable » Message de refus ou journal de l'API : bucket, droit, région, réseau, certificat Configurer S3
Service Linux inactif Chemins, droits du compte applicatif, message dans journalctl -u <unité> Exploitation
Worker arrêté au démarrage API démarrée et schéma de la base installé : schema-wait attend 300 secondes au plus Exploitation
Service Windows arrêté État par Get-Service, environnement du service, journaux dans C:\app\logs\<composant> dont <service>-console.log après un arrêt en erreur, journal d’événements Application Exploitation
Erreur TLS ou certificat inconnu SAN correspondant à l’URL, chaîne complète, CA reconnue par le client, heure système. Certificat généré par SmartAGT : racine exportée par pki export-ca Installer vos certificats
Frontend service accessible localement seulement Adresse d’écoute, DNS de la VM, filtrage réseau client et port 9000 Installer le Frontend
Frontend service actif mais connexion impossible État du lien interne, puis origine CORS exacte. Le journal du Frontend service écrit chaque refus qu'il décide : Refus (...) : 403, origin_refused ou 429, rate_limit_exceeded. Celui de l'API écrit le motif d'un refus d'identifiants : Connexion refusée (... motif=invalid_password), unknown_user, account_locked Lien interne, CORS, Exploitation
Clients API externes sans réponse Adresse de l’écoute Public smartagt.http.public.host, certificat Backend, filtrage du port 8000 Installer le Backend
502 derrière le proxy Résolution du nom amont, port, certificat amont vérifié et service joignable Reverse proxy
Réponse affichée en une fois Buffering et délai de lecture du proxy, puis streaming du fournisseur Reverse proxy
Licence refusée Fichier reçu, période de validité, horloge et message de validation Activation
Modèle absent ou accès refusé Type fournisseur, clé, référence exacte du modèle et capacité activée Prise en main
Document sans résultat rag-ingestor et rag-embed actifs, embedding par défaut défini, stockage et fournisseur accessibles Prise en main
Gateway répond address_not_allowed Adresse cliente observée, proxy de confiance et liste réseau Gateway Activer AI Gateway

Les noms de services et les chemins des journaux sont dans Configuration. Corrigez une erreur de certificat dans la chaîne de confiance ou le nom utilisé. Conservez la vérification TLS ; ne remplacez pas le compte applicatif par un administrateur pour contourner un refus de fichier.

Lien interne

Le Frontend service reste en service quand son lien vers l’API est indisponible : il répond 503 avec le motif internal_link_unavailable et la cause, puis retente seul, avec un intervalle croissant d’une seconde à une minute. L’API ne s’arrête pas non plus et son écoute Public reste servie. La cause se lit sans authentification sur /api/v1/platform/internal-link du Frontend service. Côté Backend, run.bin pki status --config suivi du YAML Backend affiche les autorités internes, l’URL interne, l’état des ports 8010 et 8011, les répliques avec leur cause et les empreintes.

Cause Signification Action
backend_unreachable L’écoute Interne ne répond pas à l’URL interne Démarrer l’API ; vérifier le port 8010, le pare-feu entre serveurs et le load balancer. Le lien reprend seul.
enrollment_required Frontend service pas encore rattaché, ou identité refusée Sur le serveur d’une API : vérifier dans pki status que le guichet local répond. Sans API sur le serveur : configurer le secret de déploiement des deux côtés.
jwt_key_missing Clé publique de session du Backend absente Relancer init du Frontend service une fois l’API démarrée, puis le redémarrer.
backend_key_changed Le Backend présente une autre clé de session ou une autre installation Backend réinitialisé ou restauré volontairement : relancer init du Frontend service, avec --adopt-backend-key si la clé est lue au guichet local, puis le redémarrer. Sinon, vérifier la cible de l’URL interne.
component_retired Frontend service retiré par pki revoke --component bff Réadmettre : run.bin pki revoke --component bff --reopen-local sur le serveur de l’API, puis redémarrer le Frontend service dans les 10 minutes ; ou nouveau secret produit par pki generate-join-secret, des deux côtés.
backend_outdated Backend plus ancien que le Frontend service Mettre à jour le Backend avec la même livraison.
intermediary_terminates_tls Un intermédiaire termine le TLS entre Frontend service et API Remplacer par une connexion directe ou un load balancer en simple passage TCP (L4).
internal_name_mismatch Le certificat présenté ne porte pas le nom de l’URL interne Vérifier que l’URL interne mène à l’écoute Interne, sans intermédiaire qui termine le TLS.
internal_url_mismatch Le YAML d’un nœud API porte une autre URL interne que celle de l’installation Reporter l’URL affichée par pki status dans smartagt.http.internal.url de ce nœud, puis le redémarrer.
port_occupied Le port 8010 ou 8011 est pris par un autre programme Libérer le port ; l’API retente seule.
database_unavailable Base du Backend ou du Frontend service indisponible Rétablir PostgreSQL ; les certificats chargés restent servis et le lien reprend seul.

Pour transmettre un blocage, relevez l’étape, la version du package, le message exact et un extrait de journal horodaté, sans secrets. Contacter Nervial Labs.