常見問題
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 金鑰、令牌、客戶資料或私人附件,也不要在您的投訴中包含任何其他資訊。