Problèmes courants
Les problèmes de déploiement dans Kanera sont généralement de configuration plutôt que de code : un domaine pointé vers le mauvais service, un paramètre de cookie qui ne correspond pas à l'URL publique ou un secret qui a changé entre les déploiements.
Travailler sur un nouveau déploiement afin
Pour un déploiement qui n'a jamais fonctionné, vérifiez-les dans l'ordre plutôt que de passer directement au symptôme :
- Confirmez que les variables d'environnement requises sont présentes. Voir Configurer le fichier d'environnement.
- Vérifiez que PostgreSQL et Valkey sont sains.
- Vérifiez les journaux de l'API et des travailleurs.
- Confirmez que les paramètres de santé publique répondent. Voir Vérifier le déploiement.
- Vérifiez le routage du proxy inverse et les URL publiques fiables. Voir Services et routage.
- Testez la configuration SMTP, du stockage et de la sauvegarde séparément.
Chaque étape dépend de celles qui la précèdent, donc un échec à l'étape 4 vaut rarement la peine d'être débogué avant la réussite de l'étape 2.
Symptômes et contrôles
| Problème | Que vérifier |
|---|---|
| Les utilisateurs sont déconnectés après la connexion. | Confirmer COOKIE_SECURE=true, COOKIE_DOMAIN, et WEB_ORIGIN correspondre au domaine public HTTPS. |
| Tout le monde a été déconnecté après un déploiement. | JWT_SECRET changé. Restaurer la valeur précédente. |
| Les codes d'authentification ont cessé de fonctionner pour chaque utilisateur inscrit. | MFA_ENCRYPTION_KEY changé. Restaurer la valeur précédente. |
/api/health échoue sur le domaine Web. | Confirmez les routes de domaine vers le web service au port 80, pas directement à api. |
| L'API publique ne répond pas. | Confirmez les routes de domaine vers public-api au port 3001. |
| MCP ne répond pas. | Confirmez les routes de domaine vers mcp au port 3002, MCP_SERVER_PUBLIC_URL points au public /mcp URL, et KANERA_PUBLIC_API_URL est http://public-api:3001 à l'intérieur composer. |
| MCP est sain mais chaque requête OAuth échoue. | Confirmer MCP_PUBLIC_URL est le public exact /mcp ressource et MCP_INTERNAL_SECRET est la même valeur non-JWT dans public-api et mcp. La reconnexion n'est requise qu'après l'ancienne migration de jeton non lié, et non après la mise à jour de la stratégie de lecture/écriture. |
| Les limites de taux affectent tout le monde à la fois. | Confirmer API_TRUST_PROXY=true et PUBLIC_API_TRUST_PROXY=true lorsque vous êtes derrière un proxy de confiance. |
| La vérification des e-mails bloque les utilisateurs. | Partir EMAIL_VERIFICATION_ENABLED=false jusqu'à ce que SMTP fonctionne. |
| Aucun e-mail n'arrive du tout. | Vérifiez les valeurs SMTP et les journaux des travailleurs. Le courrier électronique est envoyé par le worker service, pas l'API. |
| Les téléchargements disparaissent après le redéploiement. | Confirmer kanera_uploads est persistant ou configurez le stockage compatible S3. |
| Les pièces jointes ne s'ouvrent plus. | MEDIA_SIGNING_SECRET modifié, invalidant les URL signées existantes. |
| Une destination de discussion ou un webhook personnel a cessé de fonctionner après un déploiement. | SECRETS_ENCRYPTION_KEY modifié, de sorte que les informations d'identification stockées ne peuvent plus être déchiffrées. Restaurer la valeur précédente. |
| Le push du navigateur ne peut pas être activé. | Confirmez HTTPS, puis qu'un administrateur de l'organisation a activé le push d'organisation. Voir E-mail et notifications. |
| Un utilisateur ne peut pas enregistrer une adresse ntfy ou Gotify sur le réseau interne. | Les séquestres privés sont refusés sauf si KANERA_ALLOW_PRIVATE_NOTIFICATION_DESTINATIONS=true. |
Référence de déploiement
La référence de déploiement basée sur l'implémentation est DÉPLOYER.md.
Pour les problèmes au sein de l'application plutôt que lors du déploiement (connexion, autorisations, notifications, intégrations, téléchargements), commencez à partir de Dépannage.
Demander de l'aide
Lorsque vous signalez un problème de déploiement, incluez :
- Ce que vous essayiez de faire et la page ou le contrôle que vous avez utilisé.
- Ce à quoi vous vous attendiez et ce qui s'est passé à la place.
- Journaux de service pertinents avec secrets supprimés.
- Que le déploiement soit nouveau ou fonctionnait déjà.
- Versions du navigateur et du système d’exploitation, le cas échéant.
Courriel [email protected] pour du soutien ou ouvrir un problème GitHub pour un problème reproductible de logiciel ou de documentation. N'incluez jamais de mots de passe, de clés API, de jetons, de données client ou de pièces jointes privées.