Dépannage
Pour toute panne, commencez par deux vérifications :
- l’état des conteneurs :
docker compose -f docker-compose.yml ps; - le journal du service en cause :
docker compose -f docker-compose.yml logs --tail=200 api(ouweb,postgres).
Si l’application s’ouvre, Paramètres > À propos / Système et sa section Santé de l’instance donnent souvent la réponse (voir Surveillance et santé).
La stack ne démarre pas
Section intitulée « La stack ne démarre pas »| Symptôme | Cause probable et solution |
|---|---|
POSTGRES_PASSWORD is required (ou une autre variable) |
Variable absente de .env ou des variables de la stack. Voir Variables d’environnement. |
pull access denied, unauthorized |
Le serveur n’est pas connecté à ghcr.io, ou le jeton n’a pas le droit read:packages. |
port is already allocated |
Un autre programme utilise le port 3000, 4000, 5432 ou 3080. Changez WEB_PORT, API_PORT, POSTGRES_PORT ou DOCS_PORT. |
web reste en attente |
Il attend que api soit en bonne santé : regardez le journal de api. |
L’API redémarre en boucle
Section intitulée « L’API redémarre en boucle »password authentication failed:POSTGRES_PASSWORDa changé après la création de la base. PostgreSQL garde le mot de passe d’origine : remettez l’ancien, ou changez-le dans la base (ALTER USER kiwidesk PASSWORD '...') avant de modifier.env.- Erreur pendant
Applying database migrations...: une migration a échoué (disque plein, base restaurée d’une version plus récente). Lisez le message, libérez de l’espace si besoin, ou restaurez la sauvegarde d’avant la mise à jour (Mises à jour et migrations). - Erreur sur
ENCRYPTION_KEY: la clé doit faire 32 octets encodés en base64. Une cléCHANGE-MEou tronquée est refusée. SEED_ADMIN_PASSWORD does not satisfy the password policy: mot de passe trop faible ; videz la variable pour qu’un mot de passe soit généré.
La connexion ne fonctionne pas
Section intitulée « La connexion ne fonctionne pas »- On revient sans cesse à la page de connexion :
COOKIE_SECURE=truealors que le site est en HTTP, ouAPP_PUBLIC_URLne correspond pas à l’adresse utilisée. - « Trop de tentatives » : la limite de connexions par adresse est atteinte. Patientez une
minute. Si toute l’équipe est bloquée en même temps, toutes les connexions semblent venir de la
même adresse : réglez
WEB_TRUSTED_PROXIES(Reverse proxy et HTTPS). - Compte verrouillé : trop de mots de passe faux sur ce compte. Il se déverrouille après la durée réglée dans Paramètres > Sécurité > Sessions & verrouillage, ou un administrateur le déverrouille depuis Paramètres > Utilisateurs.
- Mot de passe du super administrateur perdu : si un autre super administrateur existe, il
réinitialise le mot de passe depuis Paramètres > Utilisateurs. Sinon, vous pouvez créer un
nouveau super administrateur : arrêtez l’API, mettez une nouvelle adresse dans
SEED_ADMIN_EMAILet redémarrez ; les données de départ créent ce compte s’il n’existe pas.
Les données semblent fausses
Section intitulée « Les données semblent fausses »- Heures décalées d’une ou deux heures sur des enregistrements anciens : la base tournait dans un autre fuseau horaire avant une mise à jour. La ligne Fuseau horaire de la base de données de la santé de l’instance doit être verte ; ne corrigez jamais à la main les dates des factures ou clôtures, elles font partie de leur signature.
- Photos ou logos absents après une restauration ou un déplacement : le volume
uploadsn’a pas été restauré, ou ses fichiers n’appartiennent pas au bon utilisateur. Voir Sauvegarde et restauration. - Codes de déverrouillage illisibles :
ENCRYPTION_KEYn’est pas celle qui les a chiffrés. Remettez la bonne clé ; ne la remplacez que par la rotation de clé.
Les messages ne partent pas
Section intitulée « Les messages ne partent pas »- E-mails : voir E-mail : SMTP et IMAP.
- SMS : voir Passerelle SMS.
- Connexion Google ou Microsoft, boîte mail OAuth : voir Google et Microsoft (OAuth).
Le matériel de caisse ne répond pas
Section intitulée « Le matériel de caisse ne répond pas »Voir Dépannage du Bridge.
Le temps réel ne se met pas à jour
Section intitulée « Le temps réel ne se met pas à jour »Les notifications, la messagerie et l’écran client se mettent à jour sans recharger la page.
Dans Paramètres > À propos / Système, le bloc État des WebSockets & Temps réel doit
indiquer Connecté ; Tester le ping WebSocket mesure l’aller-retour. Si l’état reste
déconnecté derrière un reverse proxy, vérifiez que celui-ci ne coupe pas les requêtes longues
(proxy_read_timeout, proxy_buffering off avec nginx).
Demander de l’aide
Section intitulée « Demander de l’aide »Avant de signaler un problème, notez la version (Paramètres > À propos / Système), ce que vous faisiez, le message affiché et les lignes du journal de l’API au même moment. Retirez des journaux toute adresse e-mail, numéro de téléphone ou mot de passe.