自托管环境参考
从发布开始 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 是有效的。