Veelvoorkomende problemen
Implementatieproblemen in Kanera zijn meestal eerder configuratie dan code: een domein dat naar de verkeerde service verwijst, een cookie-instelling die niet overeenkomt met de openbare URL, of een geheim dat tussen implementaties is gewijzigd.
Werk op volgorde door een nieuwe implementatie
Voor een implementatie die nog nooit heeft gewerkt, controleert u deze in volgorde in plaats van naar het symptoom te springen:
- Controleer of de vereiste omgevingsvariabelen aanwezig zijn. Zie Configureer het omgevingsbestand.
- Controleer of PostgreSQL en Valkey in orde zijn.
- Controleer de API- en werkerlogboeken.
- Bevestig dat de eindpunten voor de volksgezondheid reageren. Zie Controleer de implementatie.
- Controleer reverse-proxy-routering en vertrouwde openbare URL's. Zie Diensten en routering.
- Test de SMTP-, opslag- en back-upconfiguratie afzonderlijk.
Elke stap is afhankelijk van de stappen erboven, dus een fout bij stap 4 is zelden de moeite waard om te debuggen voordat stap 2 is voltooid.
Symptomen en controles
| Probleem | Wat te controleren |
|---|---|
| Gebruikers worden na het inloggen afgemeld. | Bevestig COOKIE_SECURE=true, COOKIE_DOMAIN, en WEB_ORIGIN overeenkomen met het openbare HTTPS-domein. |
| Iedereen werd afgemeld na een implementatie. | JWT_SECRET veranderd. Herstel de vorige waarde. |
| Authenticatorcodes werken niet meer voor elke ingeschreven gebruiker. | MFA_ENCRYPTION_KEY veranderd. Herstel de vorige waarde. |
/api/health mislukt op het webdomein. | Bevestig de domeinroutes naar de web dienst aan de haven 80, niet rechtstreeks naar api. |
| Openbare API reageert niet. | Bevestig de domeinroutes naar public-api op haven 3001. |
| MCP reageert niet. | Bevestig de domeinroutes naar mcp op haven 3002, MCP_SERVER_PUBLIC_URL wijst naar het publiek /mcp URL, en KANERA_PUBLIC_API_URL is http://public-api:3001 binnen componeren. |
| MCP is in orde, maar elk OAuth-verzoek mislukt. | Bevestig MCP_PUBLIC_URL is het exacte publiek /mcp bron en MCP_INTERNAL_SECRET is dezelfde niet-JWT-waarde in public-api en mcp. Opnieuw verbinding maken is alleen vereist na de oudere ongebonden tokenmigratie, niet na de update van het lees-/schrijfbeleid. |
| Tarieflimieten zijn voor iedereen tegelijk van toepassing. | Bevestig API_TRUST_PROXY=true en PUBLIC_API_TRUST_PROXY=true wanneer u zich achter een vertrouwde proxy bevindt. |
| E-mailverificatie blokkeert gebruikers. | Vertrekken EMAIL_VERIFICATION_ENABLED=false totdat SMTP werkt. |
| Er komt helemaal geen e-mail binnen. | Controleer de SMTP-waarden en de werklogboeken. E-mail wordt verzonden door de worker service, niet de API. |
| Uploads verdwijnen na opnieuw implementeren. | Bevestig kanera_uploads is persistent of configureer S3-compatibele opslag. |
| Bijlagen worden niet meer geopend. | MEDIA_SIGNING_SECRET gewijzigd, waardoor bestaande ondertekende URL's ongeldig worden gemaakt. |
| Een chatbestemming of persoonlijke webhook werkt niet meer na een implementatie. | SECRETS_ENCRYPTION_KEY gewijzigd, zodat opgeslagen inloggegevens niet langer kunnen worden gedecodeerd. Herstel de vorige waarde. |
| Browserpush kan niet worden ingeschakeld. | Bevestig HTTPS en vervolgens dat een organisatiebeheerder organisatie-push heeft ingeschakeld. Zie E-mail en meldingen. |
| Een gebruiker kan geen ntfy- of Gotify-adres opslaan op het interne netwerk. | Particuliere ontvangers worden geweigerd, tenzij KANERA_ALLOW_PRIVATE_NOTIFICATION_DESTINATIONS=true. |
Implementatiereferentie
De door de implementatie ondersteunde implementatiereferentie is IMPLEMENTEREN.md.
Voor problemen binnen de app in plaats van de implementatie (aanmelding, machtigingen, meldingen, integraties, uploads) begint u vanaf Problemen oplossen.
Vraag om hulp
Wanneer u een implementatieprobleem meldt, vermeld dan het volgende:
- Wat u probeerde te doen en de pagina of het besturingselement dat u gebruikte.
- Wat je had verwacht en wat er in plaats daarvan gebeurde.
- Relevante servicelogboeken waarvan de geheimen zijn verwijderd.
- Of de implementatie nieuw is of eerder werkte.
- Browser- en besturingssysteemversies indien relevant.
E-mail [email protected] voor ondersteuning of open een GitHub-probleem voor een reproduceerbaar software- of documentatieprobleem. Voeg nooit wachtwoorden, API-sleutels, tokens, klantgegevens of privébijlagen toe.