自託管環境參考
從釋出開始 env.example，您下載為 .env 在 快速入門。它是受支援的最小 Compose 配置。使用 env.full.example 當您需要可選設定時;此頁面解釋哪些設定屬於一起以及何時更改它們。
編輯後 .env，驗證插值而不列印解析的配置：
docker compose config --quiet
不要犯罪 .env，將其貼上到支援請求中，或公開以下輸出 docker compose config：解析的輸出包含秘密。
所需生產值
使用以下方法獨立生成每個秘密: openssl rand -hex 32。每次升級時保留舊值，並在伺服器外部儲存恢復副本。
| 變數 | 生產值 | 為什麼這很重要 |
|---|---|---|
POSTGRES_PASSWORD | 獨特的隨機密碼 | 保護捆綁的 PostgreSQL 資料庫。 |
WEB_ORIGIN | 公共 HTTPS 應用源,例如 https://kanera.example.com | 用於瀏覽器連結、CORS 和身份驗證流程。 不要包含字尾斜線。 |
COOKIE_DOMAIN | 應用程式主機名，例如 kanera.example.com | 重新整理cookie的範圍。 |
COOKIE_SECURE | true | 當應用透過 HTTPS 提供時,必須使用此項。 |
JWT_SECRET | 穩定的隨機密碼,至少16個字元 | 使用者會話簽名。 輪換會將所有人登出。 |
MCP_INTERNAL_SECRET | 穩定的隨機密碼,至少32個字元,不同於 JWT_SECRET | 允許 MCP 和公共 API 服務交換受眾約束 OAuth 憑據,而不會將 MCP 令牌轉發到 /api/v1。兩種服務必須始終使用相同的值。 |
MFA_ENCRYPTION_KEY | 穩定的隨機密碼,至少32個字元 | 保護身份驗證器的註冊和挑戰。 輪換會使已註冊的身份驗證器無效。 |
MEDIA_SIGNING_SECRET | 穩定的隨機密碼,至少32個字元 | 簽署私有媒體 URL。 輪換會使現有簽署的 URL 無效。 |
SECRETS_ENCRYPTION_KEY | 穩定的隨機密碼,至少32個字元,不同於 JWT_SECRET | 加密儲存在資料庫中的 SMTP、儲存、webhook 和整合憑據。 |
KANERA_DEPLOYMENT_MODE 未付款額 self_hosted。託管模式及其 Stripe、PostHog、計劃限制和許可變數適用於 Kanera 操作的部署，並且在自託管安裝上應保持未設定狀態。
編寫用品 NODE_ENV=production 以及 ANALYTICS_ENABLED=false。離開 ANALYTICS_PROVIDER, POSTHOG_PROJECT_KEY, POSTHOG_API_HOST, 每個 STRIPE_*, HOSTED_*，並且託管模式令牌未設定。這些設定不會將自託管安裝轉變為 Kanera 雲。
公共 URL 和服務
| 變數 | 預設 | 設定它時 |
|---|---|---|
KANERA_ENVIRONMENT | production 生產中 編寫 | 您需要不同的 API 金鑰字首來進行開發、測試或臨時安裝。 |
API_PUBLIC_URL | WEB_ORIGIN | 面向瀏覽器的應用 API 使用不同的公共源。 |
KANERA_PUBLIC_API_URL | http://public-api:3001 編寫 | MCP 或其他內部程序在其 Compose 服務地址以外的某個位置訪問公共 API,這是一個內部 URL,而不是面向瀏覽器的 API 源。 |
PUBLIC_API_OAUTH_ISSUER | http://localhost:3001 | 您遠端公開 OAuth 或公共 API;使用其可由瀏覽器訪問的 HTTPS 源。 |
MCP_SERVER_PUBLIC_URL | http://localhost:3002/mcp | 您公開遠端 MCP;使用完整的公共 /mcp URL . |
MCP_PUBLIC_URL | 來自 MCP_SERVER_PUBLIC_URL 按編寫方式分類 | 您在捆綁的 Compose 佈線之外執行 MCP 服務。 |
OAUTH_ISSUER_URL | 來自 PUBLIC_API_OAUTH_ISSUER 按編寫方式分類 | 您在捆綁的 Compose 佈線之外執行 MCP。 |
API_PORT, PUBLIC_API_PORT, WORKER_PORT, MCP_PORT | 3000, 3001, 3003, 3002 | 您在 Compose 之外執行服務,或者需要不同的內部偵聽埠。 |
API_TRUST_PROXY, PUBLIC_API_TRUST_PROXY, MCP_TRUST_PROXY | false, false, true | 受信任的反向代理提供真實的客戶端 IP。切勿信任來自任意客戶端的轉發標頭。 |
瀏覽器連線到 web;不釋出主要內容 api 服務。 服務與路由 在公開公共 API 或 MCP 之前。
帳戶和身份驗證
| 變數 | 預設 | 目 的 |
|---|---|---|
SIGNUPS_ENABLED | true | 集合 false 停止公開註冊和建立新組織。 現有組織邀請連結仍然有效。 |
EMAIL_VERIFICATION_ENABLED | false | 要求對註冊、邀請註冊和電子郵件更改進行六位數字的電子郵件驗證。 只有在 SMTP 工作後才啟用。 |
AUTH_RATE_LIMIT_ENABLED | true | 在未經身份驗證的 auth 路由上啟用每個 IP 的暴力控制。 |
AUTH_RATE_LIMIT_MAX / AUTH_RATE_LIMIT_WINDOW_MS | 10 / 60000 | 每個視窗允許的身份驗證嘗試。 |
JWT_ACCESS_TTL / JWT_REFRESH_TTL_DAYS | 5m / 10 | 訪問令牌和重新整理會話生命週期。 |
CLOUDFLARE_TURNSTILE_SITE_KEY / CLOUDFLARE_TURNSTILE_SECRET_KEY | 未設定 | 託管註冊保護。 對於正常的自託管,請不要設定。 |
使用者在下面配置自己的身份驗證器 設定 -> 您的帳戶 -> 安全。組織管理員可以在下面要求它 設定 -> 組織 -> 安全。參見 個人資料與安全.
公共 API 和 MCP 限制
| 變數 | 預設 | 目 的 |
|---|---|---|
PUBLIC_API_RATE_LIMIT_ENABLED | true | 啟用公共 API 和 MCP 請求限制。 |
PUBLIC_API_IP_RATE_LIMIT_PER_MINUTE | 60 | 限制未經身份驗證的發現和無效載體格式。 |
PUBLIC_API_FAILED_KEY_RATE_LIMIT_PER_MINUTE | 10 | 失敗的每個 IP 限制 kanera_* 關鍵的嘗試。 |
PUBLIC_API_KEY_RATE_LIMIT_PER_MINUTE | 400 | 成功身份驗證後的每個金鑰請求限制。 |
PUBLIC_API_UPLOAD_RATE_LIMIT_PER_MINUTE | 30 | 每個金鑰的附件上傳限制。 |
PUBLIC_API_RATE_LIMIT_WINDOW_MS | 60000 | 由公共 API 和 MCP 共享的速率限制視窗。 |
MCP_BODY_MAX_BYTES | 1048576 | 最大 MCP 請求正文。 |
MCP_REQUEST_TIMEOUT_MS | 30000 | MCP 請求的最大時間。 |
MCP_HEADERS_TIMEOUT_MS / MCP_KEEP_ALIVE_TIMEOUT_MS | 10000 / 5000 | MCP HTTP 連線超時。 |
KANERA_API_KEY | 未設定 | 僅本地 stdio MCP 橋需要,而不是 HTTP MCP 服務。 |
資料庫、快取和容量
編寫用品 DATABASE_URL 以及 REDIS_URL 為了孩子 PostgreSQL 以及 Valkey 只有在在該網路之外執行程序或使用託管服務時,才能自行設定它們。
| 變數 | 預設編寫 | 目 的 |
|---|---|---|
DATABASE_SSL | false | 僅當外部資料庫需要 SSL 時才啟用。 |
POSTGRES_BIND_PORT | 5433 | 捆綁的 PostgreSQL 的僅迴圈迴路主機埠。 |
API_REPLICAS / PUBLIC_API_REPLICAS / MCP_REPLICAS | 2 / 1 / 1 | 服務過程是重要的。 讓工作者保持在正確的位置。 |
PG_POOL_MAX / WORKER_PG_POOL_MAX | 20 / 5 | 每個應用程式程序和工作程式的最大資料庫連線數。 |
PG_IDLE_TIMEOUT_MS / PG_CONNECTION_TIMEOUT_MS | 30000 / 5000 | 池空閒和採集超時。 |
PG_STATEMENT_TIMEOUT_MS / SLOW_QUERY_LOG_MS | 30000 / 250 | 資料庫查詢超時和緩慢查詢日誌記錄閾值。 |
NODE_OPTIONS | 未設定 | 可選節點標誌,如堆限制。 |
UV_THREADPOOL_SIZE | 16 | 雜湊、加密和影象處理所使用的本機工作執行緒。 |
REALTIME_WEBSOCKET_COMPRESSION_ENABLED | true | 壓縮較大的 Socket.IO WebSocket 訊息。 |
REALTIME_WEBSOCKET_COMPRESSION_THRESHOLD_BYTES | 1024 | 要壓縮的最小實時幀大小。 |
REALTIME_OUTBOX_POLL_MS | 500 編寫 | 實時和 webhook 發件箱行的工作程式備用調查間隔。 |
USER_DISPLAY_CACHE_TTL_MS | 60000 | 顯示名稱查詢的程序中快取壽命。 |
只有在測量容量後才能將複製件和池一起提升。 更新與擴充套件.
檔案和物件儲存
| 變數 | 預設 | 目 的 |
|---|---|---|
UPLOADS_DIR | /data/uploads 編寫 | 本地上傳目錄。 Bundled Compose 修復此路徑並將其保留在 kanera_uploads;更改卷對映而不是 .env. |
ATTACHMENT_MAX_BYTES | 104857600 | 上傳的附件最大大小(位元組 ) 。 |
S3_REGION / S3_BUCKET | 未設定 | 提供憑據後,啟動全部署範圍內的 S3 相容儲存。 |
S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY | 未設定 | 上傳 bucket 的憑據。 基於環境的 S3 需要這兩個憑據。 |
S3_ENDPOINT | 未設定 | 適用於 MinIO、R2 或其他 S3 相容提供程式的自定義端點。 設定它後,啟用路徑式請求。 |
S3_PUBLIC_URL_PREFIX | 未設定 | 儲存物件的可選公共或 CDN 字首。 |
環境儲存優先於應用程式中配置的組織儲存。 參見 儲存與備份 在切換已有上傳的安裝之前。
電子郵件、通知和整合
| 變數 | 預設 | 目 的 |
|---|---|---|
SMTP_HOST, SMTP_USER, SMTP_PASSWORD, SMTP_FROM_EMAIL | 未設定 | 預設的出站 SMTP 連線和發件人。 |
SMTP_PORT / SMTP_SECURITY | 587 / starttls | SMTP 埠和傳輸: starttls, tls, 或 none. |
SMTP_FROM_NAME | Kanera | 發件人顯示名稱。 |
SMTP_IDENTITY_DOMAIN | 發件人電子郵件域 | EHLO 和訊息 ID 域。 |
INTERNAL_NOTIFICATION_EMAILS | 未設定 | 用逗號分隔的收件人用於純文字註冊和邀請提醒。 需要環境 SMTP。 |
KANERA_ALLOW_PRIVATE_NOTIFICATION_DESTINATIONS | false | 允許 HTTP 或專用網路上的個人 ntfy、Gotify 和 webhook 接收器。保留地址和後設資料地址仍然被阻止。 |
ALERT_WEBHOOK_URL | 未設定 | 與 Slack 相容的準備狀態、執行時和 Grafana 警報目標。 |
OPS_ALERTS_ENABLED / OPS_ALERT_THROTTLE_MS | true / 300000 | 啟用並去重操作警報。 沒有目標,就不會傳送任何資訊。 |
SLOW_REQUEST_LOG_MS | 2500 | 日誌中緩慢請求警告的閾值。 |
GITHUB_APP_ID, GITHUB_APP_SLUG, GITHUB_APP_PRIVATE_KEY | 未設定 | 可選部署定義的 GitHub 應用程式,用於私有連結預覽。 自託管管理員可以使用應用程式內清單流。 |
TRELLO_API_KEY | 未設定 | 讓 Trello 匯入驗證和複製附件。 |
Backups and retention
| 變數 | 預設 | 目 的 |
|---|---|---|
DB_BACKUPS_ENABLED | false | 啟用將 PostgreSQL 加密備份到 S3 相容儲存的計劃備份。 |
DB_BACKUP_ENCRYPTION_PASSPHRASE | 未設定 | 啟用備份時必需,並且還原備份時再次需要。 |
DB_BACKUP_TIMES_UTC | 00:15,12:15,16:45 | 用逗號分隔的每日 UTC 備份時間。 |
DB_BACKUP_RETENTION_DAYS | 14 | 成功的備份保留視窗。 |
DB_BACKUP_S3_PREFIX | backups/postgres | 資料庫轉儲的物件字首。 |
DB_BACKUP_S3_BUCKET, DB_BACKUP_S3_REGION, DB_BACKUP_S3_ENDPOINT | 上傳儲存值 | 可選單獨備份目標。 |
DB_BACKUP_S3_ACCESS_KEY_ID, DB_BACKUP_S3_SECRET_ACCESS_KEY | 上傳儲存值 | 可選單獨備份憑據。 |
ACTIVITY_EVENT_RETENTION_DAYS | 730 | 活動歷史保留。 |
ADMIN_AUDIT_LOG_RETENTION_DAYS | 1095 | 管理審計記錄保留。 |
NOTIFICATION_READ_RETENTION_DAYS / NOTIFICATION_MAX_RETENTION_DAYS | 90 / 365 | 讀取通知和絕對通知保留。 |
AUTH_TOKEN_RETENTION_DAYS | 30 | 過期或消耗的認證檔案被清除之前的寬限期。 |
REALTIME_OUTBOX_RETENTION_DAYS / OUTBOX_STUCK_RETENTION_DAYS | 30 / 30 | 處理和永久卡住的發件箱保留。 |
海 儲存與備份 備份要求和恢復規劃。
監測
| 變數 | 預設 | 目 的 |
|---|---|---|
METRICS_ENABLED | true | 註冊 Prometheus 指標端點。 404 沒有有效的令牌。 |
METRICS_TOKEN | 未設定 | 不記名令牌，至少 16 個字元，用於抓取。 |
COMPOSE_PROFILES | 未設定 | 包括 monitoring 開始Grafana,普羅米修斯,洛基,合金,和出口商;包括 admin 管理入口網站的管理 |
COMPOSE_PROJECT_NAME | kanera | Alloy 用於選擇此部署的日誌的編寫身份。 檢查 docker compose ls 在託管平臺上。 |
GRAFANA_ADMIN_PASSWORD | 未設定 | 啟用監控配置檔案時必需。 |
MONITORING_BIND_IP | 127.0.0.1 | 使用私有VPN地址,永遠不要使用私有VPN地址。 0.0.0.0 生產中。 |
GRAFANA_BIND_PORT / PROMETHEUS_BIND_PORT | 3000 / 9090 | 兩個監控 UI 的主機埠。 |
PROMETHEUS_RETENTION / PROMETHEUS_RETENTION_SIZE | 30d / 5GB | Prometheus 資料的時間和磁碟上限。 |
GRAFANA_ROOT_URL | 未設定 | 透過代理伺服器提供外部 Grafana URL。 |
POSTGRES_EXPORTER_DSN | 捆綁資料庫 | 覆蓋外部 PostgreSQL 伺服器。 |
REALTIME_EMIT_METRICS_ENABLED | false | 啟用取樣的實時有效載荷指標。 |
REALTIME_EMIT_METRICS_SAMPLE_RATE / REALTIME_EMIT_METRICS_MIN_BYTES | 0.01 / 0 | 實時指標取樣和最小有效載荷大小。 |
可選管理門戶
管理門戶與租戶設定分開,並且有自己的身份驗證邊界,只有在操作員需要跨組織管理或稽核支援會話時才能啟用。
| 變數 | 預設 | 目 的 |
|---|---|---|
ADMIN_WEB_ORIGIN | http://localhost:4300 | 管理控制檯的公共源和 CORS 邊界。 |
ADMIN_API_PORT | 3002 | 內部管理 API 偵聽埠在捆綁佈線之外執行時。 |
ADMIN_COOKIE_DOMAIN | 未設定 | 當管理員主機名在外面時,cookie-domain覆蓋 COOKIE_DOMAIN. |
ADMIN_JWT_SECRET | 未設定 | 管理 API 所需,必須與 JWT_SECRET. |
ADMIN_EMAIL / ADMIN_PASSWORD | 未設定 | 只有在 admin-user 表為空時才播種第一個 superadmin。 它們不會重置現有帳戶。 |
ADMIN_JWT_ACCESS_TTL / ADMIN_JWT_REFRESH_TTL_DAYS | 15m / 7 | 管理員訪問和重新整理生命週期。 |
ADMIN_LOGIN_RATE_LIMIT_MAX / ADMIN_LOGIN_RATE_LIMIT_WINDOW_MS | 5 / 300000 | 每個IP管理員登入節流閥。 |
ADMIN_TRUST_PROXY | true | 對於真實客戶端 IP,信任管理員反向代理。 |
SUPPORT_SESSION_TTL_MINUTES | 60 | 支援會話壽命短暫;最長八小時,無重新整理令牌。 |
保持管理門戶的隱私,使用單獨的主機名和金鑰,並檢視其稽核日誌。 DEPLOY.md 關於 Kanera 儲存庫的資訊
應用並驗證更改
大多數更改都需要重新建立受影響的服務:
docker compose config --quiet
docker compose up -d
docker compose ps
更改身份驗證、傳送、儲存、API、MCP 或管理設定後，檢查相關服務日誌。語法上有效的 .env 並不能證明外部憑據或 URL 是有效的。