常见问题
Kanera 中的部署问题通常是配置问题,而不是代码问题:域指向错误的服务、cookie 设置与公共 URL 不匹配,或者部署之间发生了变化的密钥。
按顺序完成新部署
对于从未工作过的部署,请按顺序检查以下内容,而不是直接跳到症状:
- 确认所需的环境变量存在。 参见 配置环境文件.
- 检查 PostgreSQL 和 Valkey 是否正常。
- 检查 API 和工作日志。
- 确认公共卫生终点的响应。 见 检查部署情况.
- 验证反向代理路由和受信任的公共 URL。 服务与路由.
- 分别测试 SMTP、存储和备份配置。
每个步骤都依赖于上面的步骤,因此步骤 4 中的错误很少值得在步骤 2 通过之前调试。
症状和检查
| 问题 | 要检查什么 |
|---|---|
| 用户登录后注销。 | 确认 COOKIE_SECURE=true, COOKIE_DOMAIN, 和 WEB_ORIGIN 匹配公共 HTTPS 域。 |
| 部署后,每个人都会注销。 | JWT_SECRET 恢复到以前的值。 |
| 身份验证器代码停止对每个注册用户起作用。 | MFA_ENCRYPTION_KEY 恢复到以前的值。 |
/api/health 网站上有很多的网站。 | 确认域路径到 web 港口服务 80，不直接到 api. |
| 公共 API 没有响应。 | 确认域路由到 public-api 港口 3001. |
| MCP 没有回应。 | 确认域路由到 mcp 港口 3002, MCP_SERVER_PUBLIC_URL 点在公共 /mcp 网址，以及 KANERA_PUBLIC_API_URL 是 http://public-api:3001 内部构成。 |
| MCP 状态良好,但每个 OAuth 请求都失败。 | 确认 MCP_PUBLIC_URL 是什么? /mcp 资源和 MCP_INTERNAL_SECRET 是相同的非JWT值在 public-api 以及 mcp。仅在旧的未绑定令牌迁移后才需要重新连接，而不是在读/写策略更新后。 |
| 速率限制会同时影响到每个人。 | 确认 API_TRUST_PROXY=true 以及 PUBLIC_API_TRUST_PROXY=true 当在可信代理后面时。 |
| 电子邮件验证会阻止用户。 | 休假 EMAIL_VERIFICATION_ENABLED=false 直到SMTP正常工作。 |
| 没有电子邮件到达。 | 检查 SMTP 值和工作日志。电子邮件由 worker 服务,而不是 API。 |
| 上传内容在重新部署后消失。 | 确认 kanera_uploads 是持久的,或配置 S3 兼容的存储。 |
| 附件不再打开。 | MEDIA_SIGNING_SECRET 更改,使现有签名 URL 无效。 |
| 聊天目标或个人 Webhook 在部署后停止工作。 | SECRETS_ENCRYPTION_KEY 已更改,因此存储的凭据无法再解密。 恢复以前的值。 |
| 无法启用浏览器推送。 | 确认 HTTPS,然后确认组织管理员已启用组织推送。 参见 电子邮件与通知. |
| 用户无法在内部网络上保存 ntfy 或 Gotify 地址。 | 私人接收人被拒绝，除非 KANERA_ALLOW_PRIVATE_NOTIFICATION_DESTINATIONS=true. |
部署参考
实施支持的部署参考是 DEPLOY.md.
对于应用程序内部而非部署中的问题 — 登录、权限、通知、集成、上传 — 从 故障排除.
寻求帮助
报告部署问题时,请包括:
- 您试图执行的操作以及您使用的页面或控件。
- 你期望的和实际发生的。
- 删除了相关服务日志的机密。
- 部署是新的还是以前已运行的。
- 相关的浏览器和操作系统版本。
电子邮件 联合国难民事务高级专员办事处 支助或 打开一个 GitHub 问题 请勿在您的投诉中包含密码、API 密钥、令牌、客户数据或私人附件,也不要在您的投诉中包含任何其他信息。