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.