Häufige Probleme
Bereitstellungsprobleme in Kanera sind in der Regel eher auf die Konfiguration als auf Code zurückzuführen: eine Domäne, die auf den falschen Dienst verweist, eine Cookie-Einstellung, die nicht mit der öffentlichen URL übereinstimmt, oder ein Geheimnis, das sich zwischen den Bereitstellungen geändert hat.
Arbeiten Sie eine neue Bereitstellung der Reihe nach durch
Überprüfen Sie bei einer Bereitstellung, die noch nie funktioniert hat, diese der Reihe nach, anstatt direkt zum Symptom zu springen:
- Bestätigen Sie, dass die erforderlichen Umgebungsvariablen vorhanden sind. Siehe Konfigurieren Sie die Umgebungsdatei.
- Überprüfen Sie, ob PostgreSQL und Valkey fehlerfrei sind.
- Überprüfen Sie die API- und Worker-Protokolle.
- Bestätigen Sie, dass die Endpunkte für die öffentliche Gesundheit reagieren. Siehe Überprüfen Sie die Bereitstellung.
- Überprüfen Sie das Reverse-Proxy-Routing und vertrauenswürdige öffentliche URLs. Siehe Dienste und Routing.
- Testen Sie die SMTP-, Speicher- und Backup-Konfiguration separat.
Jeder Schritt hängt von den darüber liegenden Schritten ab, daher lohnt es sich selten, einen Fehler bei Schritt 4 zu beheben, bevor Schritt 2 abgeschlossen ist.
Symptome und Kontrollen
| Problem | Was zu überprüfen ist |
|---|---|
| Benutzer werden nach der Anmeldung abgemeldet. | Bestätigen COOKIE_SECURE=true, COOKIE_DOMAIN, und WEB_ORIGIN mit der öffentlichen HTTPS-Domäne übereinstimmen. |
| Nach einer Bereitstellung wurden alle abgemeldet. | JWT_SECRET geändert. Stellen Sie den vorherigen Wert wieder her. |
| Die Authentifizierungscodes funktionierten nicht mehr für alle registrierten Benutzer. | MFA_ENCRYPTION_KEY geändert. Stellen Sie den vorherigen Wert wieder her. |
/api/health schlägt in der Webdomäne fehl. | Bestätigen Sie die Domänenrouten zum web Service am Hafen 80, nicht direkt zu api. |
| Die öffentliche API antwortet nicht. | Bestätigen Sie die Domänenrouten zu public-api am Hafen 3001. |
| MCP antwortet nicht. | Bestätigen Sie die Domänenrouten zu mcp am Hafen 3002, MCP_SERVER_PUBLIC_URL weist auf die Öffentlichkeit hin /mcp URL und KANERA_PUBLIC_API_URL ist http://public-api:3001 drinnen komponieren. |
| MCP ist fehlerfrei, aber jede OAuth-Anfrage schlägt fehl. | Bestätigen MCP_PUBLIC_URL ist die genaue Öffentlichkeit /mcp Ressource und MCP_INTERNAL_SECRET ist derselbe Nicht-JWT-Wert in public-api und mcp. Eine erneute Verbindung ist nur nach der älteren ungebundenen Token-Migration erforderlich, nicht nach der Aktualisierung der Lese-/Schreibrichtlinie. |
| Tarifbegrenzungen wirken sich auf alle gleichzeitig aus. | Bestätigen API_TRUST_PROXY=true und PUBLIC_API_TRUST_PROXY=true wenn hinter einem vertrauenswürdigen Proxy. |
| Die E-Mail-Bestätigung blockiert Benutzer. | Geh EMAIL_VERIFICATION_ENABLED=false bis SMTP funktioniert. |
| Es kommt überhaupt keine E-Mail an. | Überprüfen Sie die SMTP-Werte und die Worker-Protokolle. E-Mail wird von gesendet worker Dienst, nicht die API. |
| Uploads verschwinden nach der erneuten Bereitstellung. | Bestätigen kanera_uploads ist persistent oder konfigurieren Sie S3-kompatiblen Speicher. |
| Anhänge lassen sich nicht mehr öffnen. | MEDIA_SIGNING_SECRET geändert, wodurch vorhandene signierte URLs ungültig werden. |
| Ein Chat-Ziel oder ein persönlicher Webhook funktionierte nach einer Bereitstellung nicht mehr. | SECRETS_ENCRYPTION_KEY geändert, so dass gespeicherte Zugangsdaten nicht mehr entschlüsselt werden können. Stellen Sie den vorherigen Wert wieder her. |
| Browser-Push kann nicht aktiviert werden. | Bestätigen Sie HTTPS und bestätigen Sie, dass ein Organisationsadministrator Organisations-Push aktiviert hat. Siehe E-Mail und Benachrichtigungen. |
| Ein Benutzer kann keine NTFY- oder Gotify-Adresse im internen Netzwerk speichern. | Privatverwalter werden abgelehnt, es sei denn KANERA_ALLOW_PRIVATE_NOTIFICATION_DESTINATIONS=true. |
Bereitstellungsreferenz
Die durch die Implementierung unterstützte Bereitstellungsreferenz lautet DEPLOY.md.
Bei Problemen innerhalb der App und nicht bei der Bereitstellung – Anmeldung, Berechtigungen, Benachrichtigungen, Integrationen, Uploads – beginnen Sie mit Fehlerbehebung.
Bitten Sie um Hilfe
Wenn Sie ein Bereitstellungsproblem melden, schließen Sie Folgendes ein:
- Was Sie versucht haben und welche Seite oder welches Steuerelement Sie verwendet haben.
- Was Sie erwartet haben und was stattdessen passiert ist.
- Relevante Dienstprotokolle mit entfernten Geheimnissen.
- Ob die Bereitstellung neu ist oder zuvor funktionierte.
- Browser- und Betriebssystemversionen, sofern relevant.
E-Mail [email protected] für Unterstützung bzw Öffnen Sie ein GitHub-Problem für ein reproduzierbares Software- oder Dokumentationsproblem. Geben Sie niemals Passwörter, API-Schlüssel, Token, Kundendaten oder private Anhänge an.