Problemas comunes
Los problemas de implementación en Kanera suelen ser de configuración más que de código: un dominio apunta al servicio incorrecto, una configuración de cookie que no coincide con la URL pública o un secreto que cambia entre implementaciones.
Trabaje en una nueva implementación en orden
Para una implementación que nunca funcionó, verifique estos en secuencia en lugar de saltar al síntoma:
- Confirme que las variables de entorno requeridas estén presentes. Ver Configurar el archivo de entorno.
- Compruebe que PostgreSQL y Valkey estén en buen estado.
- Verifique la API y los registros de trabajadores.
- Confirme que los puntos finales de salud pública respondan. Ver Verifique el despliegue.
- Verifique el enrutamiento de proxy inverso y las URL públicas confiables. Ver Servicios y enrutamiento.
- Pruebe la configuración de SMTP, almacenamiento y copia de seguridad por separado.
Cada paso depende de los anteriores, por lo que rara vez vale la pena depurar una falla en el paso 4 antes de pasar el paso 2.
Síntomas y controles.
| problema | Que comprobar |
|---|---|
| Los usuarios cierran sesión después de iniciar sesión. | Confirmar COOKIE_SECURE=true, COOKIE_DOMAIN, y WEB_ORIGIN coincidir con el dominio HTTPS público. |
| Todos cerraron sesión después de una implementación. | JWT_SECRET cambiado. Restaurar el valor anterior. |
| Los códigos de autenticación dejaron de funcionar para todos los usuarios registrados. | MFA_ENCRYPTION_KEY cambiado. Restaurar el valor anterior. |
/api/health falla en el dominio web. | Confirme las rutas del dominio al web servicio en puerto 80, no directamente a api. |
| La API pública no responde. | Confirme las rutas del dominio a public-api en el puerto 3001. |
| MCP no responde. | Confirme las rutas del dominio a mcp en el puerto 3002, MCP_SERVER_PUBLIC_URL apunta al publico /mcp URL y KANERA_PUBLIC_API_URL es http://public-api:3001 dentro componer. |
| MCP está en buen estado pero todas las solicitudes de OAuth fallan. | Confirmar MCP_PUBLIC_URL es el publico exacto /mcp recurso y MCP_INTERNAL_SECRET es el mismo valor no JWT en public-api y mcp. La reconexión solo es necesaria después de la migración de token independiente anterior, no después de la actualización de la política de lectura/escritura. |
| Los límites de tarifas afectan a todos a la vez. | Confirmar API_TRUST_PROXY=true y PUBLIC_API_TRUST_PROXY=true cuando está detrás de un proxy confiable. |
| La verificación de correo electrónico bloquea a los usuarios. | salir EMAIL_VERIFICATION_ENABLED=false hasta que SMTP esté funcionando. |
| No llega ningún correo electrónico. | Verifique los valores SMTP y los registros de los trabajadores. El correo electrónico es enviado por el worker servicio, no la API. |
| Las cargas desaparecen después de la redistribución. | Confirmar kanera_uploads es persistente o configurar el almacenamiento compatible con S3. |
| Los archivos adjuntos ya no se abren. | MEDIA_SIGNING_SECRET modificado, invalidando las URL firmadas existentes. |
| Un destino de chat o un webhook personal dejó de funcionar después de una implementación. | SECRETS_ENCRYPTION_KEY cambiado, por lo que las credenciales almacenadas ya no se pueden descifrar. Restaurar el valor anterior. |
| La inserción del navegador no se puede habilitar. | Confirme HTTPS y luego que un administrador de la organización haya habilitado el envío de la organización. Ver Correo electrónico y notificaciones. |
| Un usuario no puede guardar una dirección ntfy o Gotify en la red interna. | Se rechazan los receptores privados a menos que KANERA_ALLOW_PRIVATE_NOTIFICATION_DESTINATIONS=true. |
Referencia de implementación
La referencia de implementación respaldada por la implementación es DESPLIEGUE.md.
Para problemas dentro de la aplicación en lugar de la implementación (inicio de sesión, permisos, notificaciones, integraciones, cargas), comience desde Solución de problemas.
pide ayuda
Al informar un problema de implementación, incluya:
- Lo que estaba intentando hacer y la página o control que utilizó.
- Lo que esperabas y lo que pasó en su lugar.
- Registros de servicios relevantes con secretos eliminados.
- Si la implementación es nueva o ya estaba funcionando.
- Versiones del navegador y del sistema operativo cuando sea relevante.
Correo electrónico [email protected] para apoyo o abrir un problema de GitHub para un problema de documentación o software reproducible. Nunca incluya contraseñas, claves API, tokens, datos de clientes ni archivos adjuntos privados.