Problemas comuns
Os problemas de implantação no Kanera geralmente são de configuração e não de código: um domínio apontado para o serviço errado, uma configuração de cookie que não corresponde à URL pública ou um segredo que mudou entre as implantações.
Trabalhe em uma nova implantação para
Para uma implantação que nunca funcionou, verifique-os em sequência, em vez de pular para o sintoma:
- Confirme se as variáveis de ambiente necessárias estão presentes. Veja Configurar o arquivo de ambiente.
- Verifique se o PostgreSQL e o Valkey estão íntegros.
- Verifique a API e os logs do trabalhador.
- Confirme se os endpoints de saúde pública respondem. Veja Verifique a implantação.
- Verifique o roteamento de proxy reverso e URLs públicos confiáveis. Veja Serviços e roteamento.
- Teste a configuração de SMTP, armazenamento e backup separadamente.
Cada etapa depende das etapas acima dela, portanto, raramente vale a pena depurar uma falha na etapa 4 antes da etapa 2 passar.
Sintomas e verificações
| Problema | O que verificar |
|---|---|
| Os usuários são desconectados após o login. | Confirmar COOKIE_SECURE=true, COOKIE_DOMAINe WEB_ORIGIN corresponder ao domínio HTTPS público. |
| Todos foram desconectados após uma implantação. | JWT_SECRET mudou. Restaure o valor anterior. |
| Os códigos autenticadores pararam de funcionar para todos os usuários inscritos. | MFA_ENCRYPTION_KEY mudou. Restaure o valor anterior. |
/api/health falha no domínio da web. | Confirme as rotas do domínio para o web serviço no porto 80, não diretamente para api. |
| A API pública não responde. | Confirme as rotas do domínio para public-api no porto 3001. |
| O MCP não responde. | Confirme as rotas do domínio para mcp no porto 3002, MCP_SERVER_PUBLIC_URL aponta para o público /mcp URL e KANERA_PUBLIC_API_URL é http://public-api:3001 dentro compor. |
| O MCP está íntegro, mas todas as solicitações OAuth falham. | Confirmar MCP_PUBLIC_URL é o público exato /mcp recurso e MCP_INTERNAL_SECRET é o mesmo valor não JWT em public-api e mcp. A reconexão é necessária somente após a migração do token não vinculado mais antigo, e não após a atualização da política de leitura/gravação. |
| Os limites de taxa afetam todos ao mesmo tempo. | Confirmar API_TRUST_PROXY=true e PUBLIC_API_TRUST_PROXY=true quando atrás de um proxy confiável. |
| A verificação de e-mail bloqueia usuários. | Sair EMAIL_VERIFICATION_ENABLED=false até que o SMTP esteja funcionando. |
| Nenhum e-mail chega. | Verifique os valores SMTP e os logs do trabalhador. O e-mail é enviado pelo worker serviço, não a API. |
| Os uploads desaparecem após a reimplantação. | Confirmar kanera_uploads é persistente ou configure o armazenamento compatível com S3. |
| Os anexos não abrem mais. | MEDIA_SIGNING_SECRET alterado, invalidando URLs assinados existentes. |
| Um destino de chat ou webhook pessoal parou de funcionar após uma implantação. | SECRETS_ENCRYPTION_KEY alterado, então as credenciais armazenadas não podem mais ser descriptografadas. Restaure o valor anterior. |
| O push do navegador não pode ser ativado. | Confirme o HTTPS e se um administrador da organização ativou o push da organização. Veja E-mail e notificações. |
| Um usuário não pode salvar um endereço ntfy ou Gotify na rede interna. | Os destinatários privados são recusados, a menos que KANERA_ALLOW_PRIVATE_NOTIFICATION_DESTINATIONS=true. |
Referência de implantação
A referência de implantação apoiada pela implementação é IMPLEMENTAR.md.
Para problemas dentro do aplicativo, e não na implantação – login, permissões, notificações, integrações, uploads – comece em Solução de problemas.
Peça ajuda
Ao relatar um problema de implantação, inclua:
- O que você estava tentando fazer e a página ou controle usado.
- O que você esperava e o que aconteceu em vez disso.
- Logs de serviço relevantes com segredos removidos.
- Se a implantação é nova ou está funcionando anteriormente.
- Versões do navegador e do sistema operacional, quando relevante.
E-mail [email protected] para suporte ou abra um problema do GitHub para um problema reproduzível de software ou documentação. Nunca inclua senhas, chaves de API, tokens, dados de clientes ou anexos privados.