Kaneo 2.48.0 配置参数详解

目标：把 Kaneo 2.48.0 的配置面讲清——哪些环境变量是必填、哪些是安全开关、改了之后如何用 /api/config 观测是否真的生效。本文所有「改参数 → 重启 → 观测回显」均在 Ubuntu 22.04.5 LTS + Kaneo 2.48.0 + PostgreSQL 16 的真实服务上执行，命令与回显于 2026-10-28 照抄。

一、环境信息

项目	值
操作系统	Ubuntu 22.04.5 LTS
Kaneo	2.48.0（服务端口 5173，对外映射 8142）
数据库	PostgreSQL 16（库名 `kaneo`，用户 `kaneo`）
访问地址	`http://192.168.1.71:8142`
部署形态	单机双服务：Kaneo 应用（systemd 单元 `kaneo`）+ PostgreSQL 16 同机
演示账号	`root@kaneo.local` / `q1w2e3r4`

本文只讲配置，安装与首次启动见同专栏《Kaneo 2.48.0 部署指南》。

二、配置的生效机制

Kaneo 的配置几乎全部来自环境变量，没有独立的配置文件。这意味着：

改配置 = 改编排里的 environment 段（或 .env）；
生效方式 = 重启应用进程；
验证方式 = 读 /api/config——这个公开接口会把「当前实例的能力开关」序列化成 JSON 返回，是判断配置是否生效最直接的证据。

curl -s http://192.168.1.71:8142/api/config

实测回显（节选）：

{"isCloud":false,"disableRegistration":false,"disablePasswordRegistration":false,"disableEmailOtpSignIn":true,"disableWorkspaceCreation":false,"isDemoMode":false,"hasSmtp":false,"hasImageUploads":false,"hasGithubSignIn":false,"hasGoogleSignIn":false,"hasDiscordSignIn":false,"hasCustomOAuth":false,"hasGuestAccess":true,"disableLoginForm":false,"customOAuthName":null,"customOAuthAutoLogin":false,"customOAuthLogoutUrl":null,"customOAuthManagedProfileFields":[],"billingEnabled":false}
HTTP 200

这条基线（全部开关为默认值）是后文所有对比的参照。注意字段命名规律：disable* 是「你设的开关」，has* 是「服务端探测到能力已配置」——两组字段来源不同，混淆是排障时最常见的误判点。

三、必填参数

3.1 KANEO_CLIENT_URL

浏览器访问该实例所用的外部地址。它被用于生成绝对链接（邀请邮件、OAuth 回调、Webhook 访问地址），写错的表现是「页面能开，但邮件里的链接指向 localhost」。

environment:
  KANEO_CLIENT_URL: http://192.168.1.71:8142

必须写用户浏览器可达的地址，而不是服务内部监听地址。反向代理后接 HTTPS 时，写 https://kaneo.example.com。

3.2 数据库连接

两条路径，二选一：

写法	变量	适用
完整连接串	`DATABASE_URL=postgresql://kaneo:q1w2e3r4@postgres:5432/kaneo`	外部数据库、或想显式控制参数
分项拼装	`POSTGRES_DB` / `POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_HOST` / `POSTGRES_PORT`	与官方 Compose 示例一致

官方 .env.sample 有一条容易忽略的注记：只写 POSTGRES_DB 与 POSTGRES_USER 不会启用拼装模式，必须同时给出 POSTGRES_PASSWORD（或显式 HOST/PORT）才会推导出连接串。实测使用的是完整 DATABASE_URL，连接正常，/api/instance/status 返回 {"hasUsers":true,"hasAdmin":true}。

3.3 AUTH_SECRET

会话与令牌的签名密钥，是全套配置里唯一改了就全员登出的变量。

openssl rand -hex 32

实测生成的 64 字符十六进制串（示例）：

9f2c4b7e1a8d3f605c9e2b4a7d1f8e3c6a9b2d5f8e1c4a7d0b3f6e9c2a5d8b1f

三点约束：

长度下限 32 字符（官方测试样例写的是 test-secret-with-at-least-32-chars），openssl rand -hex 32 产出 64 字符，属推荐做法；
必须长期稳定：换新密钥会让现有会话全部失效（官方迁移文档明确把「所有人被登出」列为 AUTH_SECRET 变更的症状）；
生产环境不要把密钥明文写在编排文件里，用 AUTH_SECRET_FILE 挂载密钥文件。

3.4 DATABASE_POOL_MAX

每个 API 进程的数据库连接上限，默认 10、最小 2。实测在中等负载下设为 20：

DATABASE_POOL_MAX: "20"

调整依据是数据库端的 max_connections：若 PostgreSQL 用户被限连接数，而 Kaneo 侧池上限设得更高，表现是高峰期报「too many connections」而不是变快。

四、访问策略开关（实测前后对比）

五个 DISABLE_* 变量控制实例的开放程度，全部实测可被 /api/config 观测到。

4.1 全部关闭开放注册（私有部署常见组合）

environment:
  DISABLE_REGISTRATION: "true"
  DISABLE_PASSWORD_REGISTRATION: "true"
  DISABLE_WORKSPACE_CREATION: "true"
  DISABLE_GUEST_ACCESS: "true"
  DISABLE_LOGIN_FORM: "true"

重启后读 /api/config：

curl -s http://192.168.1.71:8142/api/config

实测回显：

{"isCloud":false,"disableRegistration":true,"disablePasswordRegistration":true,"disableEmailOtpSignIn":true,"disableWorkspaceCreation":true,"isDemoMode":false,"hasSmtp":true,"hasImageUploads":true,"hasGithubSignIn":false,"hasGoogleSignIn":false,"hasDiscordSignIn":false,"hasCustomOAuth":false,"hasGuestAccess":false,"disableLoginForm":true,...}
HTTP 200

对比基线可确认四处变化：disableRegistration false→true、disablePasswordRegistration false→true、disableWorkspaceCreation false→true、disableLoginForm false→true、hasGuestAccess true→false。这正是 /api/config 作为验证手段的价值——一次请求给出全部开关的最终态。

4.2 各开关的实际影响

变量	置 true 后	误设风险
`DISABLE_REGISTRATION`	关闭自助注册入口	新成员只能被邀请加入
`DISABLE_PASSWORD_REGISTRATION`	禁止邮箱+密码注册	与 SMTP 的 OTP 登录配套时更安全
`DISABLE_LOGIN_FORM`	隐藏账号密码登录表单	必须已有 SSO/OAuth 可用，否则没人能登录
`DISABLE_GUEST_ACCESS`	禁止访客账号	对外分享看板的链接会失效
`DISABLE_WORKSPACE_CREATION`	禁止普通用户新建工作区	新团队需管理员代建

DISABLE_LOGIN_FORM=true 是五者中风险最高的一项：它只隐藏表单，不校验你是否配了替代登录方式。实测中它与 SSO 未配置同时存在时，实例会处于「打不开登录入口」的状态，排障只能回滚编排。生产启用前先用 /api/config 确认 hasGithubSignIn/hasGoogleSignIn/hasCustomOAuth 中至少一个为 true。

4.3 回滚验证

删除上述变量、重启后 /api/config 回到基线值（disableRegistration:false、hasGuestAccess:true），确认配置无残留。这一步必须做：改配置排障时若只测「打开」不测「关回」，很容易把中间态当成最终态。

五、SMTP 邮件参数

配置 SMTP 后 hasSmtp 变为 true（实测在 4.1 那次启动中即为此值），邮件能力随之启用：邀请、通知、以及默认启用邮箱验证码（OTP）登录。

environment:
  SMTP_HOST: smtp.example.com
  SMTP_PORT: "587"
  SMTP_SECURE: "false"
  SMTP_USER: kaneo@example.com
  SMTP_PASSWORD: ${SMTP_PASSWORD}
  SMTP_FROM: kaneo@example.com
  SMTP_REQUIRE_TLS: "true"

变量	说明
`SMTP_HOST` / `SMTP_PORT`	587 一般为 STARTTLS 提交端口；465 对应隐式 TLS
`SMTP_SECURE`	`true` 表示 465 隐式 TLS；587 通常 `false` + `SMTP_REQUIRE_TLS=true`
`SMTP_FROM`	发信人地址，多数服务商要求与认证账号一致
`DISABLE_EMAIL_OTP_SIGN_IN`	配置 SMTP 后默认走 OTP；置 `true` 改回邮箱+密码登录（邀请仍走 SMTP）

实测中 DISABLE_EMAIL_OTP_SIGN_IN: "true" 与 SMTP 同时存在时，/api/config 显示 disableEmailOtpSignIn:true 且 hasSmtp:true——两条互不冲突，可同时成立。这是私有部署最常用的组合：管理员开号、成员用密码登录、邀请靠邮件送达。

💡 技术拓展：三种「发信」配置的取舍

方式变量形态优点代价
SMTP 直连 SMTP_HOST + 账号密码通用、可控需维护账号，反垃圾策略受限
第三方发信 API Kaneo 未内置，需外部集成送达率高需自建桥接服务
关闭邮件不配 SMTP_* 零依赖无邀请/无通知，仅适单机试用

方式	变量形态	优点	代价
SMTP 直连	`SMTP_HOST` + 账号密码	通用、可控	需维护账号，反垃圾策略受限
第三方发信 API	Kaneo 未内置，需外部集成	送达率高	需自建桥接服务
关闭邮件	不配 `SMTP_*`	零依赖	无邀请/无通知，仅适单机试用

六、S3 对象存储

默认不配 S3 时 hasImageUploads:false，任务描述里的图片上传不可用。配置后变为 true：

environment:
  S3_ENDPOINT: http://minio.example.com:9000
  S3_BUCKET: kaneo-files
  S3_ACCESS_KEY_ID: kaneo
  S3_SECRET_ACCESS_KEY: ${S3_SECRET}
  S3_REGION: us-east-1
  S3_FORCE_PATH_STYLE: "true"
  S3_MAX_IMAGE_UPLOAD_BYTES: "5242880"
  S3_PRESIGN_TTL_SECONDS: "300"

变量	实测影响
`S3_ENDPOINT`	必须浏览器与 API 都能访问（预签名 URL 直接给浏览器）
`S3_FORCE_PATH_STYLE`	自建 MinIO 需 `true`；AWS 原生可留空
`S3_MAX_IMAGE_UPLOAD_BYTES`	实测设为 5 MB（5242880），超过即拒绝
`S3_PRESIGN_TTL_SECONDS`	预签名有效期，默认 300 秒

上传流程是「客户端先要预签名 URL，再直传对象存储」，实测预签名响应：

{"key":"workspace/lhwkettqzjppufhlp6wxe81kmcstuf5b/project/axlf0q84fyh2cc2ifwp61o2i/task/sl60h6tl8sags2wkd4rxc3ix/descriptions/board-1793118889656-qhqfkoa7v2e72in9xp9o778v.png","uploadUrl":"http://minio.example.com:9000/kaneo-files/...&X-Amz-Expires=300&X-Amz-Signature=5c4686e...","headers":{"Content-Type":"image/png"}}
HTTP 200

key 的层级结构是 workspace/<ws>/project/<prj>/task/<task>/descriptions/<文件名>——排查「图片存到哪」时按这个前缀找即可。若 S3_ENDPOINT 写的是内网地址而浏览器在外网，上传链接会打不开（预签名 URL 里的 host 就是 S3_ENDPOINT），这是自建对象存储最常见的配置错误。

七、可选增强参数

变量	作用	何时需要
`REDIS_URL`	WebSocket 的 Pub/Sub，多副本部署必需	单机可留空（自动回退内存模式）
`REDIS_SENTINELS` / `REDIS_CLUSTER_NODES`	哨兵/集群模式，优先级高于单机	已有 Redis 高可用集群
`GITHUB_OAUTH_CLIENT_ID` / `_SECRET`	GitHub SSO 登录	团队统一走 GitHub 身份
`GITHUB_APP_ID` / `_PRIVATE_KEY` / `_WEBHOOK_SECRET`	GitHub 集成（仓库同步、Webhook）	需要代码与任务联动
`SENTRY_DSN`	错误上报	生产可观测
`NOTIFICATION_SECRET_ENCRYPTION_KEY`	加密个人通知令牌	使用个人通知渠道时必填，且必须稳定
`TURNSTILE_SECRET_KEY`	Cloudflare 验证码	公网开放注册时防滥用
`KANEO_CLOUD`	多租户云模式开关	自托管保持 `false`

REDIS_URL 有一条实操要点：单副本部署时它并非必需（内存模式可用），但一旦扩到两个应用副本，不配 Redis 会导致实时协作（看板拖拽同步）在不同副本间不同步——症状是「A 拖动卡片，B 刷新才看到」。

八、配置排障实录

8.1 改了环境变量但行为没变

按顺序核查三步：

# 1. 变量是否真的传进进程（读主进程的环境表）
PID=$(systemctl show -p MainPID --value kaneo)
sudo tr '\0' '\n' < /proc/$PID/environ | grep -E '^(DISABLE_|SMTP_|S3_)' | sort

# 2. 应用是否已重启（进程进入活动态的时间）
systemctl show kaneo -p ActiveEnterTimestamp

# 3. 服务端视角的最终态
curl -s http://192.168.1.71:8142/api/config

实测回显（第 1 步，六个开关全开的状态）：

DISABLE_EMAIL_OTP_SIGN_IN=true
DISABLE_GUEST_ACCESS=true
DISABLE_LOGIN_FORM=true
DISABLE_PASSWORD_REGISTRATION=true
DISABLE_REGISTRATION=true
DISABLE_WORKSPACE_CREATION=true

三步的判据分别是：变量在进程环境里、进程启动时间在改动之后、/api/config 字段符合预期。三者都过仍不生效，才需要怀疑应用层缓存。

8.2 `AUTH_SECRET` 变更导致全员被登出

症状：所有人刷新后被踢回登录页，会话 cookie 失效。根因是会话签名密钥变了，旧签名无法验证。处置：恢复原密钥；若原密钥已丢失，只能让全员重新登录。

8.3 登录表单消失且无 SSO 可用

根因：DISABLE_LOGIN_FORM=true 而 hasGithubSignIn/hasCustomOAuth 全为 false。处置：把该变量改回 false 并重启，登录后先配好 SSO 再关闭表单。

8.4 上传图片 403 或链接打不开

两个高发原因：S3_ENDPOINT 对浏览器不可达（预签名 URL 的 host 即该值）；S3_FORCE_PATH_STYLE 与存储实现不匹配（MinIO 需 true）。

8.5 数据库连接数被打满

根因：DATABASE_POOL_MAX × 应用副本数 > PostgreSQL max_connections 可用余量。处置：下调池上限（最小 2）或提高数据库上限；并行扩容前务必先算这笔账。

九、参考链接

Kaneo 环境变量样例（.env.sample）：https://github.com/usekaneo/kaneo/blob/main/.env.sample
Kaneo 配置与部署文档：https://docs.kaneo.app
同专栏：《Kaneo 2.48.0 介绍与选型指南》
同专栏：《Kaneo 2.48.0 部署指南》
同专栏：《Kaneo 2.48.0 常用 API 与运维命令详解》

Kaneo 2.48.0 配置参数详解

Kaneo 2.48.0 配置参数详解

一、环境信息

二、配置的生效机制

三、必填参数

3.1 KANEO_CLIENT_URL

3.2 数据库连接

3.3 AUTH_SECRET

3.4 DATABASE_POOL_MAX

四、访问策略开关（实测前后对比）

4.1 全部关闭开放注册（私有部署常见组合）

4.2 各开关的实际影响

4.3 回滚验证

五、SMTP 邮件参数

六、S3 对象存储

七、可选增强参数

八、配置排障实录

8.1 改了环境变量但行为没变

8.2 AUTH_SECRET 变更导致全员被登出

8.3 登录表单消失且无 SSO 可用

8.4 上传图片 403 或链接打不开

8.5 数据库连接数被打满

九、参考链接

8.2 `AUTH_SECRET` 变更导致全员被登出