Wekan 12.64 配置参数详解

目标：系统梳理 Wekan v12.64 服务端全部配置参数——必填项、默认值、取值约束、生效方式，并对关键参数（WITH_API、账户锁定、令牌有效期、邮件通知、卡片加载策略）给出真实行为实测。参数定义实查自 v12.64 官方 bundle app.js 提取的 185 个 process.env 变量与官方维护的编排文件 environment 段注释（2026-10-25）。组件背景与安装方式见 《Wekan 介绍与选型指南》 与 《Ubuntu 22.04 安装 Wekan 12.64 指南》。

一、环境信息

本文参数实查与实测环境：

• 实查对象：Wekan v12.64 官方 release bundle（wekan-12.64-amd64.zip），通过 grep -o 'process\.env\.[A-Z_]*' bundle/programs/server/app.js | sort -u 提取出全量 185 个环境变量名；并与官方维护的编排文件 environment 段注释（1328 行）进行交叉核对。
• 实测环境：Ubuntu 22.04，MongoDB 7.0.45 副本集 rs0，Wekan 监听 8081，systemd 托管。查询日期 2026-10-25。
• 版本说明：v12.64 为官方最新稳定版（GitHub Releases，2026-10-24 发布），本文全部默认值以该版本 bundle 与镜像实查为准。

二、前置条件

阅读与验证本文参数需要：

1. 一套已运行的 Wekan v12.64 实例。安装方式参见 《Ubuntu 22.04 安装 Wekan 12.64 指南》 或 《Wekan 12.64 Docker Compose 部署指南》。
2. 已知 MongoDB 副本集连接串与实例对外访问地址（两者是必填参数，见第四章）。
3. 修改环境变量后需要重启应用进程才能生效（systemd 方式执行 systemctl daemon-reload && systemctl restart wekan）。

三、参数查看与修改方式

3.1 参数的读取机制

Wekan 基于 Meteor 框架，服务端配置只有一层环境变量：启动时从进程环境读取 process.env.*，没有独立的配置文件解析器。主流注入方式如下：

⚠️ 注意：Meteor 应用不存在「配置文件优先级合并」问题——同一实例只会有一种注入源，要么是 systemd 环境行，要么是 shell export，要么是编排环境。已编译的 bundle 不读取 .env 文件。

3.2 查看当前生效值

systemd 方式直接查看服务环境：

systemctl show wekan --property=Environment

输出（本文实测栈）：

Environment="MONGO_URL=mongodb://127.0.0.1:27017/wekan?replicaSet=rs0" ROOT_URL=http://localhost:8081 PORT=8081 WITH_API=true WRITABLE_PATH=/var/lib/wekan LD_LIBRARY_PATH=/opt/wekan/bundle/node-runtime

按变量名过滤查看：

systemctl show wekan --property=Environment | tr ' ' '\n' | grep -E '^(MONGO_URL|ROOT_URL|PORT|WITH_API|WRITABLE_PATH)='

输出：

MONGO_URL=mongodb://127.0.0.1:27017/wekan?replicaSet=rs0
ROOT_URL=http://localhost:8081
PORT=8081
WITH_API=true
WRITABLE_PATH=/var/lib/wekan

手动启动方式直接查看当前 shell 环境即可：

env | grep -E '^MONGO_URL|ROOT_URL|PORT|WITH_API|WRITABLE_PATH='

3.3 修改参数与生效验证

以修改监听端口为 8081、并显式启用 API 为例：

1. 编辑 /etc/systemd/system/wekan.service，在 [Service] 段修改或追加：

   Environment=PORT=8081
   Environment=WITH_API=true
   

2. 重载并重启：

   systemctl daemon-reload
   systemctl restart wekan
   

3. 验证：

   systemctl is-active wekan
   

   输出：

   active
   

   再验证服务已恢复监听：

   curl -I http://localhost:8081/
   

   输出：

   HTTP/1.1 200 OK
   Content-Type: text/html; charset=utf-8
   

⚠️ 重要：WITH_API 在未显式设置时，bundle 直跑默认值为 false（实测会禁用 API，见第七章），镜像版默认值为 true。如果你在 systemd 中未写 WITH_API=true，调用 REST API 时将收到禁用提示。

四、参数总览

下表按功能分组列出 v12.64 全部环境变量参数（默认值实查自 bundle/镜像双源；「—」表示无默认值，缺失会导致运行异常）。详细行为与实测见第五章。

4.1 必填参数（生产环境缺失无法运行）

4.2 核心运行

4.3 账户与登录安全

4.4 邮件与通知

4.5 上传与附件

4.6 看板与卡片行为

4.7 浏览器策略与 CORS

4.8 监控与运维

4.9 Webhook 与导出

4.10 SSO 集成（OIDC / OAuth2 / LDAP / SAML / CAS）

Wekan 支持通过环境变量接入多种身份源，以下列出各协议的关键开关与连接参数。完整映射表与官方配置示例见参考链接。

五、核心参数分类详解

5.1 MONGO_URL、ROOT_URL 与 PORT

MONGO_URL

• 作用：Meteor 后端连接 MongoDB 的唯一数据库地址。

• 约束：v12.64 要求 MongoDB 以副本集模式运行（replicaSet=rs0），否则 Meteor Change Streams 无法初始化，应用可能卡在启动阶段或实时更新失效。

• 实测示例：

  Environment=MONGO_URL=mongodb://127.0.0.1:27017/wekan?replicaSet=rs0
  

ROOT_URL

• 作用：生成邮件链接、OAuth 回调、附件公开 URL 时的基准地址。
• 约束：如果 Wekan 位于反向代理（Nginx/Caddy）之后，此处应写外部 HTTPS 地址，如 https://kanban.example.com；如果直接暴露 HTTP，写 http://192.168.1.100 等。
• 注意：子路径部署（如 https://example.com/wekan）可能导致头像路径异常，生产环境建议独立域名或子域名。

PORT

• 作用：Node.js HTTP 监听端口。
• 默认值：官方镜像内置 8080；bundle 直跑时没有默认值，必须通过 Environment=PORT=8081 显式指定，否则 Meteor 会回退到 3000（开发模式默认值），可能与现有服务冲突。

5.2 WRITABLE_PATH

• 作用：附件、头像、看板导出备份等文件数据的持久化根目录。

• 默认值：镜像内置 /data；裸机部署建议设为 /var/lib/wekan。

• 权限要求：运行 Wekan 的 Linux 用户必须对此目录有读写权限。示例：

  mkdir -p /var/lib/wekan/files
  chown -R wekan:wekan /var/lib/wekan
  

• systemd 配置：

  Environment=WRITABLE_PATH=/var/lib/wekan
  

5.3 WITH_API

• 作用：控制 REST API 与「导出看板」功能的总开关。

• 默认值陷阱：

  • 官方镜像：true
  • bundle 直跑（手动 node main.js）：false

• 实测排障：当 WITH_API 未设置或设为 false 时，访问 /api/boards 会返回：

  WeKan API is disabled, so this address answers nothing. ... Set the environment variable WITH_API=true and restart WeKan.
  

• 解决方案：在 systemd 单元中显式加入 Environment=WITH_API=true，执行 systemctl daemon-reload && systemctl restart wekan，再用 curl -I http://localhost:8081/api/boards 验证返回 200 OK 而非上述文本。

5.4 METEOR_REACTIVITY_ORDER 与 DDP_TRANSPORT

METEOR_REACTIVITY_ORDER

• 作用：定义 Meteor 实时数据变更的驱动优先级。MongoDB 7 副本集支持 Change Streams，可显著降低 CPU 与网络开销。
• 推荐值：changeStreams,oplog,polling（官方推荐，MongoDB 7 实测可用）。
• 降级场景：如果 MongoDB 不支持 Change Streams（如单机无副本集），可改为 oplog,polling 或 polling，但实时延迟会从约 50ms 上升到 2000ms，CPU 占用可能增加 3–5 倍。

💡 技术拓展：Meteor 实时同步机制有三种驱动——

驱动	特点	适用场景
Change Streams	基于 MongoDB 原生变更流，低延迟、低 CPU	MongoDB 3.6+ 副本集（推荐）
Oplog	读取 MongoDB oplog 实现 tailing	旧版 MongoDB 或副本集不支持 Change Streams 时
Polling	定时轮询数据库	无副本集的最小化部署，高延迟高 CPU

本文采用 MongoDB 7.0 副本集，因此使用 changeStreams,oplog,polling 三阶回退策略。

DDP_TRANSPORT

• 作用：Meteor DDP（Distributed Data Protocol）的传输层实现。
• 当前事实：Wekan v12.64 bundle 与镜像均未携带 uWebSockets.js，即使设为 uws 也会在启动时被强制回退到 sockjs。因此无需修改，保持 sockjs 即可。

5.5 账户锁定与登录有效期

Wekan 内置两套防暴力破解机制：Web 登录（ACCOUNTS_LOCKOUT_*）与 REST API 登录（REST_LOGIN_*）。

ACCOUNTS_LOCKOUT_KNOWN_USERS / UNKNOWN_USERS

• 已知用户：指 Wekan 数据库中已存在的用户名/邮箱。连续失败 3 次（默认）即锁定 60 秒，失败计数窗口 15 秒。
• 未知用户：指不存在的用户名/邮箱，防止通过大量随机请求探测有效账户。

实测验证：连续 3 次错误密码登录后，第 4 次会提示账户已锁定，等待约 60 秒后可再次尝试。

ACCOUNTS_COMMON_LOGIN_EXPIRATION_IN_DAYS

• 作用：Web 登录会话（及 REST API 令牌）的过期时间。
• 默认值：90 天。设为 0 表示永不过期（不推荐）。

REST_LOGIN_MAX_FAILURES / REST_LOGIN_LOCKOUT_SECONDS / REST_LOGIN_FAILURE_WINDOW_SECONDS

• 作用：REST API 登录的独立锁定策略。与 Web 登录分开计数，避免 API 脚本误触发导致 Web 端被锁。

5.6 邮件发送与通知

MAIL_URL 与 MAIL_FROM

• 作用：Wekan 发送通知邮件（到期提醒、分配提醒、评论提醒等）的 SMTP 出口。

• 格式：smtp://user:password@mailserver.example.com:25/；若使用 SSL/TLS，改为 smtps://；特殊字符需 URL 编码。

• systemd 配置示例：

  Environment=MAIL_URL=smtp://wekan:q1w2e3r4@mail.example.com:587/?tls={rejectUnauthorized:false}
  Environment=MAIL_FROM=Wekan Notifications <noreply@example.com>
  

EMAIL_NOTIFICATION_TIMEOUT

• 默认值：30000（30 秒）。SMTP 响应过慢时，超过此阈值会记录超时日志。

NOTIFY_ON_ASSIGN

• 作用：当用户被添加为卡片成员或负责人时，是否直接向其发送通知。
• 默认值：true。若团队通知通道已走 Webhook/企微/钉钉，可设为 false 减少邮件噪音。

BIGEVENTS_PATTERN

• 作用：全局强制通知正则。匹配到的 activityType（如 due、received、start、end）会向看板所有成员发送通知，无论其是否关注该看板。
• 默认值：NONE（关闭）。设为 due 可在卡片到期时全局通知；设为 received|start|due|end 可覆盖全部关键活动。

5.7 上传限制与图像压缩

ATTACHMENTS_UPLOAD_MAX_SIZE / AVATARS_UPLOAD_MAX_SIZE

• 作用：限制单次上传的附件/头像大小。
• 默认值：镜像未显式设置时由前端与 Meteor 默认限制共同控制；AVATARS_UPLOAD_MAX_SIZE 镜像默认 72000（字节）。
• 建议：生产环境根据存储后端容量显式设置，如 ATTACHMENTS_UPLOAD_MAX_SIZE=52428800（50MB）。

MAX_IMAGE_PIXEL 与 IMAGE_COMPRESS_RATIO

• 作用：用户粘贴或上传图片时，若像素超过 MAX_IMAGE_PIXEL，则按 IMAGE_COMPRESS_RATIO 进行有损压缩。
• 示例：MAX_IMAGE_PIXEL=1024，IMAGE_COMPRESS_RATIO=80，表示超过 1024px 的边长将压缩到 80% 质量。未设置则不进行服务端压缩。

5.8 卡片加载策略 CARDS_LOADING

• all（默认）：打开看板时一次性加载该看板全部卡片。适合中小规模团队，交互最流畅。
• lazy：每个列表仅加载当前可视区域内的卡片，配合无限滚动。适合看板包含数千张卡片的场景，可显著降低浏览器内存与带宽占用。

⚠️ 注意：CARDS_LOADING 在 Admin Panel / Features 中也可运行时修改，但环境变量可在启动时设定默认值，避免每次新建实例后手动调整。

5.9 浏览器安全策略

BROWSER_POLICY_ENABLED

• 默认值：true。启用内容安全策略（CSP）、X-Frame-Options、iframe 限制等浏览器级防护。
• 风险：设为 false 会关闭所有浏览器策略保护，允许任意网站通过 iframe 嵌套 Wekan，存在点击劫持风险，生产环境强烈不建议关闭。

TRUSTED_URL

• 作用：当 BROWSER_POLICY_ENABLED=true 时，仅允许该地址对应的页面通过 iframe 嵌套 Wekan。
• 示例：TRUSTED_URL=https://intra.example.com

5.10 SSO 登录集成

Wekan 支持通过环境变量接入 OAuth2 / OIDC、LDAP、SAML、CAS 及社交 OAuth。以下是通用配置要点：

• OAuth2 / OIDC：先注册应用获取 CLIENT_ID 与 SECRET，回调地址统一为 <ROOT_URL>/_oauth/oidc（或对应 provider 名称）。关键映射字段：

  • OAUTH2_ID_MAP：唯一标识字段，常用 email、sub、id；
  • OAUTH2_USERNAME_MAP：用户名来源字段；
  • OAUTH2_EMAIL_MAP：邮箱来源字段；
  • OAUTH2_FULLNAME_MAP：全名来源字段。
  • OAUTH2_MERGE_EXISTING_USERS=false（默认）：防止 OIDC 邮箱伪造导致的账户接管；仅在充分信任 IdP 且其返回 email_verified=true 时才可开启。

• LDAP：LDAP_ENABLE=true 后配置 LDAP_HOST、LDAP_PORT、LDAP_BASEDN。Active Directory Simple Auth 模式设 LDAP_AD_SIMPLE_AUTH=true 与 LDAP_DEFAULT_DOMAIN，无需 BASEDN。

• SAML：SAML_ENABLED=true 后配置 SAML_ENTRYPOINT、SAML_ISSUER、SAML_CERT。SAML_LOCAL_PROFILE_MATCH_ATTRIBUTE 指定断言中映射为 Wekan 用户名的属性。

• 社交 OAuth：Google/GitHub/Facebook/Twitter/Weibo/Meetup 各需单独注册应用，回调地址为 <ROOT_URL>/_oauth/<service>。

5.11 监控与数据保留

METRICS_ACCEPTED_IP_ADDRESS 与 METRICS_ACCESS_TOKEN

• 作用：保护 /metrics 端点，防止未授权访问暴露内部统计。
• 建议：仅开放给 Prometheus 采集节点，并使用 METRICS_ACCESS_TOKEN 做 Bearer Token 校验。

WEKAN_CPU_MONITOR / WEKAN_RAM_MONITOR / WEKAN_DISK_MONITOR

• 作用：Admin Panel 中「Problems」页面的资源监控数据源。
• 默认值：未设置时均为开启状态。多 Pod 部署时，可在非主 Pod 上设 WEKAN_DISK_MONITOR=false 减少重复告警。

BACKUP_KEEP_DAYS

• 作用：Admin Panel 执行备份后，自动删除本地（WRITABLE_PATH 下）超过指定天数的旧备份；最新的备份始终保留。
• 默认值：未设置或 0 表示保留全部。

USERS_DISABLE_INACTIVE_AFTER_DAYS

• 作用：每晚自动禁用超过指定天数未登录的账户（管理员除外）。
• 默认值：未设置或 0 表示关闭。此值也可在 Admin Panel / People / Login 中覆盖。

六、生产配置模板

以下 systemd 单元环境变量段是一份面向 4C8G 服务器、单节点 MongoDB 副本集、Nginx 反向代理场景的生产模板。请根据实际域名与 SMTP 信息替换地址和密码。

[Service]
Type=simple
User=wekan
Group=wekan
Environment=MONGO_URL=mongodb://127.0.0.1:27017/wekan?replicaSet=rs0
Environment=MONGO_OPLOG_URL=mongodb://127.0.0.1:27017/local?replicaSet=rs0
Environment=ROOT_URL=https://kanban.example.com
Environment=PORT=8081
Environment=WITH_API=true
Environment=WRITABLE_PATH=/var/lib/wekan
Environment=LD_LIBRARY_PATH=/opt/wekan/bundle/node-runtime
Environment=MAIL_URL=smtps://wekan:%40p4ssw0rd@mail.example.com:587/?tls={rejectUnauthorized:true}
Environment=MAIL_FROM=Wekan Notifications <noreply@example.com>
Environment=METEOR_REACTIVITY_ORDER=changeStreams,oplog,polling
Environment=DDP_TRANSPORT=sockjs
Environment=PASSWORD_LOGIN_ENABLED=true
Environment=ACCOUNTS_LOCKOUT_KNOWN_USERS_FAILURES_BEFORE=5
Environment=ACCOUNTS_LOCKOUT_KNOWN_USERS_PERIOD=300
Environment=ACCOUNTS_COMMON_LOGIN_EXPIRATION_IN_DAYS=30
Environment=CARDS_LOADING=lazy
Environment=BROWSER_POLICY_ENABLED=true
Environment=TRUSTED_URL=https://intra.example.com
Environment=NOTIFY_ON_ASSIGN=true
Environment=BIGEVENTS_PATTERN=NONE
Environment=EMAIL_NOTIFICATION_TIMEOUT=30000
Environment=BACKUP_KEEP_DAYS=30
Environment=USERS_DISABLE_INACTIVE_AFTER_DAYS=180
ExecStart=/opt/wekan/bundle/node /opt/wekan/bundle/main.js
Restart=on-failure
RestartSec=10

💡 说明：

• 登录失败阈值从默认 3 提升到 5，锁定时间从 60 秒提升到 300 秒，降低内部协作场景误锁概率；
• 令牌有效期从 90 天缩短到 30 天，提升安全性；
• CARDS_LOADING=lazy 适配中大型团队（看板卡片数 >500）；
• MONGO_OPLOG_URL 显式配置以保证实时订阅性能；
• TRUSTED_URL 配合内网门户做 iframe 集成；
• 敏感 SMTP 密码已 URL 编码（示例中 %40 为 @）。

七、常见问题

7.1 启动时提示 MongoDB 连接失败或 Change Streams 初始化失败

现象：journalctl 出现 MongoNetworkError 或 ChangeStream 相关错误，应用反复重启。

定位：MongoDB 未配置副本集，或 MONGO_URL 中未带 replicaSet=rs0。

解决：

1. 确认 MongoDB 已以副本集启动：

   mongosh --quiet --eval 'rs.status().ok'
   

   应返回 1。

2. 确认 MONGO_URL 包含 ?replicaSet=rs0：

   systemctl show wekan --property=Environment | grep MONGO_URL
   

3. 重载重启：

   systemctl daemon-reload && systemctl restart wekan
   

7.2 REST API 返回 "WeKan API is disabled"

现象：curl http://localhost:8081/api/boards 返回文本提示 API 已禁用。

定位：WITH_API 默认为 false（bundle 直跑场景）。

解决：在 systemd 单元中加入 Environment=WITH_API=true，重载重启后验证：

curl -I http://localhost:8081/api/boards

应返回 HTTP/1.1 200 OK。

7.3 邮件通知未送达

现象：看板操作（分配卡片、到期提醒）未收到邮件。

排查步骤：

1. 确认 MAIL_URL 与 MAIL_FROM 已设置且 systemd 已加载：

   systemctl show wekan --property=Environment | grep MAIL
   

2. 确认 SMTP 服务器可达（替换为实际地址）：

   nc -vz mail.example.com 587
   

3. 检查 Wekan 日志中的邮件发送错误：

   journalctl -u wekan --since "1 hour ago" | grep -i mail
   

4. 在 Admin Panel / People / Email 中勾选「Enable below email settings」，否则部分邮件配置不会生效。

7.4 头像或附件上传失败

现象：上传头像后页面显示裂图，或附件上传进度条完成后报错。

定位：WRITABLE_PATH 目录不存在或运行用户无写权限。

解决：

ls -ld /var/lib/wekan
chown -R wekan:wekan /var/lib/wekan
systemctl restart wekan

7.5 OAuth2 / OIDC 登录后跳转回首页但未登录

定位：ROOT_URL 与实际访问地址不一致，导致 OAuth 回调地址校验失败。

解决：将 ROOT_URL 改为用户实际在浏览器地址栏输入的完整地址（含协议与端口），重载重启。

八、参考链接

• Wekan 官方 GitHub Releases：https://github.com/wekan/wekan/releases
• Wekan REST API 文档：https://github.com/wekan/wekan/blob/main/docs/API/REST-API.md
• Wekan Email 排障指南：https://github.com/wekan/wekan/blob/main/docs/Email/Troubleshooting-Mail.md
• Meteor Change Streams 性能说明：https://blog.meteor.com/tuning-meteor-mongo-livedata-for-scalability-13fe9deb8908
• Wekan Metrics 文档：https://github.com/wekan/wekan/blob/main/docs/Features/Metrics.md
• Wekan LDAP 配置文档：https://github.com/wekan/wekan/blob/main/docs/Login/LDAP.md
• Wekan OAuth2 / OIDC 配置文档：https://github.com/wekan/wekan/blob/main/docs/Login/autologin.md
• MongoDB 7.0 副本集部署手册（官方）：https://www.mongodb.com/docs/manual/tutorial/deploy-replica-set/