Wekan Snap 配置键完整指南用snap set管理看板服务的每一项设置【免费下载链接】wekanThe Open Source kanban, built with Meteor. GitHub issues/PRs are only for FLOSS Developers, not for support, support is at https://wekan.fi/commercial-support/ . PR source translation to imports/i18n/data/en.i18n.json, other translations at https://app.transifex.com/wekan/wekan项目地址: https://gitcode.com/GitHub_Trending/we/wekan本文是一份面向 Wekan Snap 部署运维者的配置键参考手册系统讲解如何通过snap set wekan keyvalue命令调整看板服务的数据库绑定、邮件、Caddy 反向代理、LDAP/OAuth2 认证、Matomo 统计与浏览器安全策略等全部设置。读完本文你将能借助wekan.help与sudo snap get wekan完整查询所有支持键及其默认值并能结合 snap-src/bin/config 中的定义与默认值独立完成生产环境下的 Snap 调优。设置机制总览一条命令全量热配置Wekan 的 Snap 包当前仓库 snapcraft.yaml 中版本号为11.72基于base: core24构建把所有运行期配置统一收敛为 Snap 的配置键snap configuration key。运维者不需要登录容器、不需要手改环境变量文件只需要一条命令即可修改任意配置项$ snap set wekan key namekey value例如把 Web 端口改为 8080、关闭内置 MongoDB 服务$ sudo snap set wekan port8080 $ sudo snap set wekan disable-mongodbtrue这套机制的实现分为两层键的权威定义所有支持键、描述与默认值都集中在 snap-src/bin/config 中。该文件维护了一个keys变量全部支持的键名列表并为每个键声明DESCRIPTION_*描述、DEFAULT_*默认值与KEY_*snap 键名三组变量。设置生效的执行器snap set写入配置后会触发 Snap 的 configure hooksnap/hooks/configure该脚本读取相关键并决定如何重启wekan、mongodb、ferretdb、caddy服务。因此文档末尾强调的那句话是有源码依据的当设置被修改后wekan / mongo / caddy 服务会自动重启以使更改生效。查询设置wekan.help与snap get列出所有可能设置的键Snap 内置了一个帮助命令会完整打印所有支持的配置键、描述以及当前值与默认值$ wekan.help | less该命令的实现位于 snap-src/bin/wekan-help。其输出由两部分组成前半部分是针对常用键S3、邮件、LDAP、OAuth2、Matomo、锁账户策略等的详细用法示例后半部分则遍历 snap-src/bin/config 中keys变量里的每一个键逐行打印键名、描述以及当前值/默认值未设置时提示No value set, using default value: ...。运行wekan.help时实际看到的键数会远多于文档表格列举的数量因为keys列表涵盖认证、安全、附件上传、通知等上百个键。查看当前 Snap 设置要查看当前实例实际生效的配置值使用sudo snap get wekan它会列出所有已设置的键值对对于使用默认值的键则不会出现在输出中此时可用wekan.help确认其默认值。取消设置恢复默认与snap set配套的是snap unset wekan key可撤销某个键的自定义值、恢复默认。例如$ sudo snap unset wekan debug $ sudo snap unset wekan with-api核心配置键详解下面按功能域整理文档列出的支持键并补充来自 snap-src/bin/config 与 snap-src/bin/wekan-help 的默认值与使用细节。数据库绑定MongoDB / FerretDBWekan Snap 默认自带数据库服务MongoDB 7 或 FerretDB v1取决于架构与迁移状态以下键控制其绑定方式键说明默认值mongodb-bind-unix-socketMongoDB 绑定 Unix socket。默认行为倾向于使用 Unix socket 绑定要禁用 Unix socket 绑定设置为字符串nill要通过 content interface 绑定到外部 snap 提供的 MongoDB 实例设置为shared目录内 socket 的相对路径使用 Unix socket 绑定mongodb-bind-ipMongoDB 绑定 IP 地址例如127.0.0.1表示仅本机可访问。未定义时改用默认的 Unix socket 绑定config 中默认127.0.0.1mongodb-portMongoDB 绑定端口例如使用 localhost 时为2701727019disable-mongodb禁用 snap 内置的 mongodb 服务仅当绑定到 snap 之外的数据库时使用。合法值为true/falsefalse从 snap-src/bin/wekan-control 的启动逻辑可以看出这三个键如何共同决定MONGO_URL当mongodb-bind-unix-socket既非nill也非空时优先构造 Unix socket 连接串否则使用mongodb://bind-ip:port/wekan并且对 IPv6 字面量会自动加方括号[::1]以构成合法 URI。disable-mongodbtrue时snap/hooks/configure 会停止并禁用 mongodb 服务仅当外部数据库存在时才应使用。此外仓库中的 snap 还支持mongo-url覆盖整个 MongoDB 连接串优先级最高、mongo-oplog-url、mongo-log-destinationdevnull/snapcommon/syslog默认devnull以及 FerretDB 相关的wekan-ferretdb-oplog默认true控制是否尾随 OpLog 以获得实时更新、wekan-ferretdb-handler默认sqlite可选外部postgresql/mysql后端、wekan-ferretdb-url外部 FerretDB 后端的连接串。邮件服务mail-url 与 mail-from键说明默认值mail-urlWekan 的 SMTP 绑定串。示例smtps://user:passmailserver.examples.com:453/smtp://user:passmailserver.examples.com:25/mail-from管理员发件人显示名 邮箱。示例Boards Support supportexample.comwekan-adminexample.com实际生产环境常按 snap-src/bin/wekan-help 中给出的方式配置带 TLS 选项的完整 URL例如$ sudo snap set wekan mail-urlsmtp://username:passwordemail-smtp.eu-west-1.amazonaws.com:587?tls{ciphers:SSLv3}secureConnectionfalse $ sudo snap set wekan mail-fromBoards Support supportexample.com邮件相关还有mail-service、mail-service-user、mail-service-password当前标注为暂未启用以及mail-tls-ca-cert信任的自签名/内网 CA 证书 PEM 或其文件路径、mail-tls-servername当主机名与证书名称不一致时用于校验的服务器名。密码类键也支持mail-service-password-file从文件读取Docker secrets 风格。对外访问root-url、port 与 bind-ip键说明默认值root-urlWekan 的根 URL例如http://127.0.0.1、https://example.com、https://wekan.example.com、http://example.com/wekanhttp://127.0.0.1portWekan 对外暴露的端口8080root-url会影响邮件链接、导出链接与 OAuth2 回调地址的生成反向代理或使用自定义域名时务必与对外地址保持一致。另外config 中还定义了bind-ip键默认空值表示沿用 Meteor 默认0.0.0.0仅 IPv4设为::可在双栈主机上同时监听 IPv6 与 IPv4设为具体地址则只监听该地址。Caddy 反向代理Snap 内置了 Caddy 服务Every Site on HTTPS可用两个键控制键说明默认值caddy-enabled设为true启用 Caddy 服务。Caddy 的许可证区分个人非商业用途与商业用途启用前请确认你的使用场景对应的许可要求仓库 snapcraft.yaml 中caddypart 使用 Apache 2.0 许可的官方预编译二进制。Caddy 的配置通过/var/snap/wekan/common/Caddyfile管理falsecaddy-bind-portCaddy 期望反代的目标端口该值也会被写入 Caddyfile3001从 snap/hooks/configure 的代码可见当caddy-enabledtrue时hook 会用caddy-bind-port与port两个值更新$SNAP_COMMON/Caddyfile分别替换反代目标端口与监听端口然后启动并重启 caddy 服务否则停止并禁用 caddy 服务。API 与 CORS键说明默认值with-api启用 Wekan 的 API。注意如果 API 被禁用将看板导出为 JSON 的功能将不可用truecors设置Access-Control-Allow-Origin响应头。示例snap set wekan cors*默认禁用与 CORS 相关的还有两个扩展键cors-allow-headers设置Access-Control-Allow-Headers跨域使用 API 时必须包含Authorization,Content-Type与cors-expose-headers设置Access-Control-Expose-Headers一般场景无需设置。配置示例$ sudo snap set wekan cors* $ sudo snap set wekan cors-allow-headersAuthorization,Content-Type浏览器安全策略browser-policy-enabled 与 trusted-url键说明默认值browser-policy-enabled启用浏览器策略只允许一个受信任 URL 通过 iframe 内嵌 Wekan。不推荐设为false它会同时关闭所有其他浏览器策略保护并允许任意 iframing相关实现见 server/policy.jstruetrusted-url当浏览器策略启用时位于该 URL 的 HTML 代码可以通过 iframe 内嵌 Wekan。示例trusted-urlhttps://example.com在 server/policy.js 中可以看到服务端启动时会读取BROWSER_POLICY_ENABLED环境变量为true时读取TRUSTED_URL作为受信任内嵌来源为false时则放开 framing 限制源码注释明确提示仅限内部局域网使用勿暴露到互联网。这就是文档中设为 false 不推荐警告的底层实现依据。Outgoing Webhook 属性键说明默认值webhooks-attributes控制 Outgoing Webhook 发送哪些属性可留空以忽略。默认包含全部cardId,listId,oldListId,boardId,comment,user,card,commentId全部默认属性# 显式启用全部默认属性 $ sudo snap set wekan webhooks-attributescardId,listId,oldListId,boardId,comment,user,card,commentId # 清空以发送全部默认属性 $ sudo snap set wekan webhooks-attributes与之相关的还有card-opened-webhook-enabled卡片被打开时发送 webhook 消息默认false。LDAP 认证配置文档指出 LDAP 相关设置的完整列表可通过wekan.help命令以及 snap-src/bin/config 查看LDAP 功能由 wekan-ldap 仓库维护其 bug 与功能请求也归于该仓库。文档给出的最小可用示例$ sudo snap set wekan ldap-enabletrue $ sudo snap set wekan default-authentication-methodldap $ sudo snap set wekan ldap-fullname-fieldCN其中default-authentication-method决定当用户不存在时使用哪种方法创建并认证可选password或ldapldap-fullname-field指定存放用户全名的 LDAP 属性。结合 snap-src/bin/config 与 snap-src/bin/wekan-help 中的完整定义常用的 LDAP 键还包括键说明默认值ldap-portLDAP 服务器端口389ldap-hostLDAP 服务器主机名ldap-basednLDAP 树的基础 DN例如ouuser,dcexample,dcorgldap-ad-simple-authAD 简单认证启用后无需ldap-basedn同时需设置ldap-user-authenticationtrueldap-username-field/ldap-fullname-field/ldap-email-field分别指定 LDAP 中用户名、全名、邮箱对应的属性ldap-user-search-field/ldap-user-search-filter查找用户所用的属性与附加过滤条件必要时保留最外层括号ldap-user-search-scope搜索范围base仅 DN、oneDN 下一层、sub整个子树ldap-encryption使用 LDAPS 时设为sslfalseldap-ca-certLDAPS 服务器的 CA 证书整段 PEM 文本ldap-reject-unauthorized是否拒绝未授权证书falseldap-reconnect连接丢失后是否自动重连trueldap-timeout/ldap-connect-timeout/ldap-idle-timeout整体/连接/空闲超时毫秒10000ldap-authentication搜索是否需要专用用户账号falseldap-authentication-userdn搜索用户 DN例如CNwekan_adm,OUserviceaccounts,OUadmin,OUprod,DCmydomain,DCcomldap-authentication-password搜索用户密码亦支持ldap-authentication-password-file从文件读取ldap-background-sync是否在后台同步用户falseldap-background-sync-interval后台同步间隔格式遵循 later 文本解析器如every 1 hour空值等同每小时ldap-login-fallback登录失败时回退到默认认证方法falseldap-merge-existing-users是否将 LDAP 登录与同邮箱的既有 Wekan 账号合并falseldap-group-filter-enable启用登录限制组过滤仅组成员可登录falseldap-sync-admin-status/ldap-sync-admin-groups依据 LDAP 组同步管理员状态及管理员组名单ldap-sync-organizations/ldap-sync-teams将用户的 LDAP 组同步为 Wekan 组织 / 团队falseldap-default-domain默认域用于 AD SimpleAuth 拼接绑定用户名或用于生成邮箱启用 LDAP 后还需要把默认认证方法一并切过去$ sudo snap set wekan default-authentication-methodldap若想隐藏密码登录表单可将password-login-enabled设为false默认true。Snap 还支持通过 HTTP 请求头自动登录SiteMinder 场景header-login-id、header-login-firstname、header-login-lastname、header-login-email分别对应HEADERUID、HEADERFIRSTNAME、HEADERLASTNAME、HEADEREMAILADDRESS等头出于安全考虑还必须设置header-login-trusted-ips信任的反代来源 IP 白名单为空时该功能拒绝一切登录fail closed。OAuth2 / OIDCRocket.Chat 等身份提供方接入文档特别指出一种常见组合如果 Rocket.Chat 自身已通过 LDAP/SAML/Google 等完成登录则这些用户同样可以登录 Wekan前提是让Rocket.Chat 向 Wekan 提供 OAuth2 登录。完整的对接配置指南见仓库文档 OAuth2 登录指南。对应到 Snap 配置键定义于 snap-src/bin/config主要步骤为# 启用 OAuth2 并填写提供方信息以 Rocket.Chat 为例 $ sudo snap set wekan oauth2-enabledtrue $ sudo snap set wekan oauth2-client-idabcde12345 $ sudo snap set wekan oauth2-secret54321abcde $ sudo snap set wekan oauth2-server-urlhttps://chat.example.com $ sudo snap set wekan oauth2-auth-endpoint/oauth/authorize $ sudo snap set wekan oauth2-userinfo-endpoint/oauth/userinfo $ sudo snap set wekan oauth2-token-endpoint/oauth/token常用 OAuth2/OIDC 键一览键说明默认值oauth2-enabled启用 OAuth2 连接falseoidc-redirection-enabled启用 OIDC/OAuth2 自动登录跳转falseoauth2-login-style登录方式popup或redirectredirectoauth2-request-permissions请求的 scopes空格分隔且不带引号如openid profile emailopenid profile emailoauth2-id-map/oauth2-username-map/oauth2-fullname-map/oauth2-email-mapID、用户名、全名、邮箱的字段映射oauth2-adfs-enabled/oauth2-b2c-enabled启用 ADFS / Azure AD B2C 变体falseoauth2-ca-cert可选的 OAuth2 提供方 CA 证书oauth2-auto-registration为false时拒绝没有既有 Wekan 账号按已验证邮箱匹配的 OIDC 登录trueoauth2-merge-existing-users安全敏感是否把 OIDC 登录合并到同邮箱的既有账号。默认false表示拒绝合并防止利用伪造的 email 声明接管账号确需开启时必须确认提供方的 email 声明可信且发送email_verifiedtruefalseoauth2-admin-groups逗号/空格分隔的组名其成员自动成为 Wekan 管理员除通用 OAuth2 外Snap 还支持 CAScas-enabled、cas-base-url、cas-login-url、cas-validate-url、SAMLsaml-enabled、saml-provider、saml-entrypoint、saml-issuer、saml-cert、saml-private-keyfile、saml-public-certfile、saml-identifier-format、saml-local-profile-match-attribute、saml-attributes以及 Google、GitHub、Facebook、Twitter/X、Meteor Developer、Weibo、Meetup 等第三方 OAuth 登录各自对应oauth-provider-enabled、-client-id/-app-id/-consumer-key、-secret及-secret-file系列键并支持oauth-providers-login-style默认popup统一设置按钮式登录的弹窗方式。passwordless-enabled可改为邮件发送一次性登录码的免密登录需配置mail-url。Matomo Web Analytics 集成Wekan Snap 原生支持与自建统计平台 Matomo 集成。文档给出的配置示例$ sudo snap set wekan matomo-addresshttps://matomo.example.com/ $ sudo snap set wekan matomo-site-id25 $ sudo snap set wekan matomo-with-usernametrue $ sudo snap set wekan matomo-do-not-trackfalse四个 Matomo 相关键的完整语义键说明默认值matomo-address托管 Matomo 的服务器地址matomo-site-idMatomo 服务器中为 Wekan 分配的站点 IDmatomo-do-not-track允许用户不被 Matomo 跟踪truematomo-with-username允许 Matomo 获取用户名false服务端对这些键的消费在 server/policy.js 中有所体现当MATOMO_ADDRESS环境变量存在时会为 Matomo 脚本与图片源放开浏览器策略白名单确保统计代码在浏览器策略开启的情况下也能正常加载执行。认证与账户安全补充键除了上文 LDAP/OAuth2 外snap-src/bin/config 还定义了一组账户安全策略键可在生产环境直接使用键说明默认值accounts-lockout-known-users-failures-before已知用户锁定的失败次数阈值需大于 03accounts-lockout-known-users-period已知用户锁定周期秒60accounts-lockout-known-users-failure-window已知用户失败窗口秒15accounts-lockout-unknown-users-failures-before未知用户锁定失败次数阈值3accounts-lockout-unknown-users-lockout-period未知用户锁定周期秒60accounts-lockout-unknown-users-failure-window未知用户失败窗口秒15accounts-common-login-expiration-in-days登录过期天数90logout-with-timer/logout-in/logout-on-hours/logout-on-minutes定时强制注销的组合开关与天/时/分参数false/notify-on-assign用户被添加为卡片成员/负责人时是否直接通知true示例启用 3 次失败锁定 60 秒并开启 9 小时 5 分钟后强制注销$ sudo snap set wekan accounts-lockout-known-users-failures-before3 $ sudo snap set wekan accounts-lockout-known-users-period60 $ sudo snap set wekan logout-with-timertrue $ sudo snap set wekan logout-in1 $ sudo snap set wekan logout-on-hours9 $ sudo snap set wekan logout-on-minutes5附件、上传与文件存储扩展键针对看板中频繁使用的附件与头像Snap 提供了一组上传校验键定义于 snap-src/bin/config键说明示例attachments-upload-external-program/avatars-upload-external-program用外部程序校验上传文件{file}会被替换为上传文件路径如接入杀毒扫描/usr/local/bin/avscan {file}attachments-upload-mime-types附件允许的 MIME 类型image/*,text/*attachments-upload-max-size附件最大字节数5000000avatars-upload-mime-types头像允许的 MIME 类型image/*avatars-upload-max-size头像最大字节数500000max-image-pixel/image-compress-ratio贴入/上传图片时自动缩小的像素上限与压缩比率文件存储位置由 snap-src/bin/wekan-control 中的WRITABLE_PATH决定默认落盘于$SNAP_COMMON/files附件与头像存放在磁盘而非数据库这是备份与迁移时必须整体拷贝的目录。其他实用键以下键同样被 snap-src/bin/config 与 snap-src/bin/wekan-help 收录可按需配置debug调试 OIDC/OAuth2 等流程sudo snap set wekan debugtrue默认false。node-options增加 Node 堆内存例如node-options--max_old_space_size4096snap-src/bin/wekan-control 会自动按可用内存计算默认堆上限约为总内存的 3/5封顶 4096 MiB。cards-loading看板卡片加载模式all默认全部载入浏览器或lazy每个列表按需只加载可见卡片适合超大看板。richer-card-comment-editor卡片评论启用富文本编辑器默认false。default-board-idOIDC 登录后自动把新用户加入指定默认看板。bigevents-pattern无论通知设置如何都强制通知的事件模式NONE禁用/ 全部received|start|due|end。notify-due-days-before-and-after到期提醒提前天数逗号分隔如2,0表示提前 2 天与到期当天。notify-due-at-hour-of-day到期提醒发送的小时0–23默认早上 8 点。email-notification-timeout邮件通知超时毫秒默认30000。results-per-page默认每页搜索结果数。wait-spinner默认等待动画样式默认Bounce。s3AWS S3 文件存储JSON 格式{s3:{key:xxx,secret:xxx,bucket:xxx,region:eu-west-1}}亦支持s3-secret-file从文件读取Docker secrets。metrics-allowed-ip-addresses允许访问 Metrics 的 IP 白名单逗号分隔。meteor-reactivity-orderMeteor 响应式驱动顺序默认changeStreams,oplog,polling无副本集环境回退为oplog,polling。wekan-autopick/wekan-autopick-timeout启动时是否对比 MongoDB 迁移前后两份数据副本以选择最新者默认true超时 900 秒关闭后站点启动更快但数据库选择需手动通过wekan.database-compare/wekan.database-merge完成。ddp-transport仅支持sockjssnap 未内置 uWebSockets.jsuws会在启动时被强制转换为sockjs。设置变更的生效机制文档结尾强调当设置被修改后wekan / mongo / caddy 服务会自动重启以使更改生效。这一行为由 snap/hooks/configure 实现其执行流程为source $SNAP/bin/config载入所有键定义读取caddy-enabled若为true则用caddy-bind-port与port更新$SNAP_COMMON/Caddyfile并启动/重启 caddy 服务否则停止并禁用 caddy调用 snap-src/bin/database-role 判断当前数据库角色运行 FerretDB 则启动 ferretdb、停止 mongodb否则依据disable-mongodb决定 mongodb 的启停database这一旧设置键已被移除旧值会被自动清理并提示忽略最后snapctl restart ${SNAP_NAME}.wekan重启 Wekan 主服务。因此每执行一次snap set服务都可能经历一次自动重启——这也是 snap-src/bin/wekan-help 末尾有些改动会导致部分或全部服务重启请谨慎使用警告的由来。总结Wekan Snap 把原本分散的环境变量配置统一成了几十上百个snap set键运维者只需掌握三个动作即可完成日常调优snap set wekan keyvalue修改、wekan.help查询全部键及默认值、sudo snap get wekan查看当前生效值。所有键的权威定义、描述与默认值都维护在 snap-src/bin/config 中随版本持续演进设置变更后的服务重启与 Caddyfile 同步则由 snap/hooks/configure 自动完成。将本文与 snapcraft.yaml 中的应用定义wekan、mongodb、ferretdb、caddy、database-backup 等命令配合阅读即可获得对 Wekan Snap 部署全貌的完整掌握。【免费下载链接】wekanThe Open Source kanban, built with Meteor. GitHub issues/PRs are only for FLOSS Developers, not for support, support is at https://wekan.fi/commercial-support/ . PR source translation to imports/i18n/data/en.i18n.json, other translations at https://app.transifex.com/wekan/wekan项目地址: https://gitcode.com/GitHub_Trending/we/wekan创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Wekan Snap 配置键完整指南：用 `snap set` 管理看板服务的每一项设置
Wekan Snap 配置键完整指南用snap set管理看板服务的每一项设置【免费下载链接】wekanThe Open Source kanban, built with Meteor. GitHub issues/PRs are only for FLOSS Developers, not for support, support is at https://wekan.fi/commercial-support/ . PR source translation to imports/i18n/data/en.i18n.json, other translations at https://app.transifex.com/wekan/wekan项目地址: https://gitcode.com/GitHub_Trending/we/wekan本文是一份面向 Wekan Snap 部署运维者的配置键参考手册系统讲解如何通过snap set wekan keyvalue命令调整看板服务的数据库绑定、邮件、Caddy 反向代理、LDAP/OAuth2 认证、Matomo 统计与浏览器安全策略等全部设置。读完本文你将能借助wekan.help与sudo snap get wekan完整查询所有支持键及其默认值并能结合 snap-src/bin/config 中的定义与默认值独立完成生产环境下的 Snap 调优。设置机制总览一条命令全量热配置Wekan 的 Snap 包当前仓库 snapcraft.yaml 中版本号为11.72基于base: core24构建把所有运行期配置统一收敛为 Snap 的配置键snap configuration key。运维者不需要登录容器、不需要手改环境变量文件只需要一条命令即可修改任意配置项$ snap set wekan key namekey value例如把 Web 端口改为 8080、关闭内置 MongoDB 服务$ sudo snap set wekan port8080 $ sudo snap set wekan disable-mongodbtrue这套机制的实现分为两层键的权威定义所有支持键、描述与默认值都集中在 snap-src/bin/config 中。该文件维护了一个keys变量全部支持的键名列表并为每个键声明DESCRIPTION_*描述、DEFAULT_*默认值与KEY_*snap 键名三组变量。设置生效的执行器snap set写入配置后会触发 Snap 的 configure hooksnap/hooks/configure该脚本读取相关键并决定如何重启wekan、mongodb、ferretdb、caddy服务。因此文档末尾强调的那句话是有源码依据的当设置被修改后wekan / mongo / caddy 服务会自动重启以使更改生效。查询设置wekan.help与snap get列出所有可能设置的键Snap 内置了一个帮助命令会完整打印所有支持的配置键、描述以及当前值与默认值$ wekan.help | less该命令的实现位于 snap-src/bin/wekan-help。其输出由两部分组成前半部分是针对常用键S3、邮件、LDAP、OAuth2、Matomo、锁账户策略等的详细用法示例后半部分则遍历 snap-src/bin/config 中keys变量里的每一个键逐行打印键名、描述以及当前值/默认值未设置时提示No value set, using default value: ...。运行wekan.help时实际看到的键数会远多于文档表格列举的数量因为keys列表涵盖认证、安全、附件上传、通知等上百个键。查看当前 Snap 设置要查看当前实例实际生效的配置值使用sudo snap get wekan它会列出所有已设置的键值对对于使用默认值的键则不会出现在输出中此时可用wekan.help确认其默认值。取消设置恢复默认与snap set配套的是snap unset wekan key可撤销某个键的自定义值、恢复默认。例如$ sudo snap unset wekan debug $ sudo snap unset wekan with-api核心配置键详解下面按功能域整理文档列出的支持键并补充来自 snap-src/bin/config 与 snap-src/bin/wekan-help 的默认值与使用细节。数据库绑定MongoDB / FerretDBWekan Snap 默认自带数据库服务MongoDB 7 或 FerretDB v1取决于架构与迁移状态以下键控制其绑定方式键说明默认值mongodb-bind-unix-socketMongoDB 绑定 Unix socket。默认行为倾向于使用 Unix socket 绑定要禁用 Unix socket 绑定设置为字符串nill要通过 content interface 绑定到外部 snap 提供的 MongoDB 实例设置为shared目录内 socket 的相对路径使用 Unix socket 绑定mongodb-bind-ipMongoDB 绑定 IP 地址例如127.0.0.1表示仅本机可访问。未定义时改用默认的 Unix socket 绑定config 中默认127.0.0.1mongodb-portMongoDB 绑定端口例如使用 localhost 时为2701727019disable-mongodb禁用 snap 内置的 mongodb 服务仅当绑定到 snap 之外的数据库时使用。合法值为true/falsefalse从 snap-src/bin/wekan-control 的启动逻辑可以看出这三个键如何共同决定MONGO_URL当mongodb-bind-unix-socket既非nill也非空时优先构造 Unix socket 连接串否则使用mongodb://bind-ip:port/wekan并且对 IPv6 字面量会自动加方括号[::1]以构成合法 URI。disable-mongodbtrue时snap/hooks/configure 会停止并禁用 mongodb 服务仅当外部数据库存在时才应使用。此外仓库中的 snap 还支持mongo-url覆盖整个 MongoDB 连接串优先级最高、mongo-oplog-url、mongo-log-destinationdevnull/snapcommon/syslog默认devnull以及 FerretDB 相关的wekan-ferretdb-oplog默认true控制是否尾随 OpLog 以获得实时更新、wekan-ferretdb-handler默认sqlite可选外部postgresql/mysql后端、wekan-ferretdb-url外部 FerretDB 后端的连接串。邮件服务mail-url 与 mail-from键说明默认值mail-urlWekan 的 SMTP 绑定串。示例smtps://user:passmailserver.examples.com:453/smtp://user:passmailserver.examples.com:25/mail-from管理员发件人显示名 邮箱。示例Boards Support supportexample.comwekan-adminexample.com实际生产环境常按 snap-src/bin/wekan-help 中给出的方式配置带 TLS 选项的完整 URL例如$ sudo snap set wekan mail-urlsmtp://username:passwordemail-smtp.eu-west-1.amazonaws.com:587?tls{ciphers:SSLv3}secureConnectionfalse $ sudo snap set wekan mail-fromBoards Support supportexample.com邮件相关还有mail-service、mail-service-user、mail-service-password当前标注为暂未启用以及mail-tls-ca-cert信任的自签名/内网 CA 证书 PEM 或其文件路径、mail-tls-servername当主机名与证书名称不一致时用于校验的服务器名。密码类键也支持mail-service-password-file从文件读取Docker secrets 风格。对外访问root-url、port 与 bind-ip键说明默认值root-urlWekan 的根 URL例如http://127.0.0.1、https://example.com、https://wekan.example.com、http://example.com/wekanhttp://127.0.0.1portWekan 对外暴露的端口8080root-url会影响邮件链接、导出链接与 OAuth2 回调地址的生成反向代理或使用自定义域名时务必与对外地址保持一致。另外config 中还定义了bind-ip键默认空值表示沿用 Meteor 默认0.0.0.0仅 IPv4设为::可在双栈主机上同时监听 IPv6 与 IPv4设为具体地址则只监听该地址。Caddy 反向代理Snap 内置了 Caddy 服务Every Site on HTTPS可用两个键控制键说明默认值caddy-enabled设为true启用 Caddy 服务。Caddy 的许可证区分个人非商业用途与商业用途启用前请确认你的使用场景对应的许可要求仓库 snapcraft.yaml 中caddypart 使用 Apache 2.0 许可的官方预编译二进制。Caddy 的配置通过/var/snap/wekan/common/Caddyfile管理falsecaddy-bind-portCaddy 期望反代的目标端口该值也会被写入 Caddyfile3001从 snap/hooks/configure 的代码可见当caddy-enabledtrue时hook 会用caddy-bind-port与port两个值更新$SNAP_COMMON/Caddyfile分别替换反代目标端口与监听端口然后启动并重启 caddy 服务否则停止并禁用 caddy 服务。API 与 CORS键说明默认值with-api启用 Wekan 的 API。注意如果 API 被禁用将看板导出为 JSON 的功能将不可用truecors设置Access-Control-Allow-Origin响应头。示例snap set wekan cors*默认禁用与 CORS 相关的还有两个扩展键cors-allow-headers设置Access-Control-Allow-Headers跨域使用 API 时必须包含Authorization,Content-Type与cors-expose-headers设置Access-Control-Expose-Headers一般场景无需设置。配置示例$ sudo snap set wekan cors* $ sudo snap set wekan cors-allow-headersAuthorization,Content-Type浏览器安全策略browser-policy-enabled 与 trusted-url键说明默认值browser-policy-enabled启用浏览器策略只允许一个受信任 URL 通过 iframe 内嵌 Wekan。不推荐设为false它会同时关闭所有其他浏览器策略保护并允许任意 iframing相关实现见 server/policy.jstruetrusted-url当浏览器策略启用时位于该 URL 的 HTML 代码可以通过 iframe 内嵌 Wekan。示例trusted-urlhttps://example.com在 server/policy.js 中可以看到服务端启动时会读取BROWSER_POLICY_ENABLED环境变量为true时读取TRUSTED_URL作为受信任内嵌来源为false时则放开 framing 限制源码注释明确提示仅限内部局域网使用勿暴露到互联网。这就是文档中设为 false 不推荐警告的底层实现依据。Outgoing Webhook 属性键说明默认值webhooks-attributes控制 Outgoing Webhook 发送哪些属性可留空以忽略。默认包含全部cardId,listId,oldListId,boardId,comment,user,card,commentId全部默认属性# 显式启用全部默认属性 $ sudo snap set wekan webhooks-attributescardId,listId,oldListId,boardId,comment,user,card,commentId # 清空以发送全部默认属性 $ sudo snap set wekan webhooks-attributes与之相关的还有card-opened-webhook-enabled卡片被打开时发送 webhook 消息默认false。LDAP 认证配置文档指出 LDAP 相关设置的完整列表可通过wekan.help命令以及 snap-src/bin/config 查看LDAP 功能由 wekan-ldap 仓库维护其 bug 与功能请求也归于该仓库。文档给出的最小可用示例$ sudo snap set wekan ldap-enabletrue $ sudo snap set wekan default-authentication-methodldap $ sudo snap set wekan ldap-fullname-fieldCN其中default-authentication-method决定当用户不存在时使用哪种方法创建并认证可选password或ldapldap-fullname-field指定存放用户全名的 LDAP 属性。结合 snap-src/bin/config 与 snap-src/bin/wekan-help 中的完整定义常用的 LDAP 键还包括键说明默认值ldap-portLDAP 服务器端口389ldap-hostLDAP 服务器主机名ldap-basednLDAP 树的基础 DN例如ouuser,dcexample,dcorgldap-ad-simple-authAD 简单认证启用后无需ldap-basedn同时需设置ldap-user-authenticationtrueldap-username-field/ldap-fullname-field/ldap-email-field分别指定 LDAP 中用户名、全名、邮箱对应的属性ldap-user-search-field/ldap-user-search-filter查找用户所用的属性与附加过滤条件必要时保留最外层括号ldap-user-search-scope搜索范围base仅 DN、oneDN 下一层、sub整个子树ldap-encryption使用 LDAPS 时设为sslfalseldap-ca-certLDAPS 服务器的 CA 证书整段 PEM 文本ldap-reject-unauthorized是否拒绝未授权证书falseldap-reconnect连接丢失后是否自动重连trueldap-timeout/ldap-connect-timeout/ldap-idle-timeout整体/连接/空闲超时毫秒10000ldap-authentication搜索是否需要专用用户账号falseldap-authentication-userdn搜索用户 DN例如CNwekan_adm,OUserviceaccounts,OUadmin,OUprod,DCmydomain,DCcomldap-authentication-password搜索用户密码亦支持ldap-authentication-password-file从文件读取ldap-background-sync是否在后台同步用户falseldap-background-sync-interval后台同步间隔格式遵循 later 文本解析器如every 1 hour空值等同每小时ldap-login-fallback登录失败时回退到默认认证方法falseldap-merge-existing-users是否将 LDAP 登录与同邮箱的既有 Wekan 账号合并falseldap-group-filter-enable启用登录限制组过滤仅组成员可登录falseldap-sync-admin-status/ldap-sync-admin-groups依据 LDAP 组同步管理员状态及管理员组名单ldap-sync-organizations/ldap-sync-teams将用户的 LDAP 组同步为 Wekan 组织 / 团队falseldap-default-domain默认域用于 AD SimpleAuth 拼接绑定用户名或用于生成邮箱启用 LDAP 后还需要把默认认证方法一并切过去$ sudo snap set wekan default-authentication-methodldap若想隐藏密码登录表单可将password-login-enabled设为false默认true。Snap 还支持通过 HTTP 请求头自动登录SiteMinder 场景header-login-id、header-login-firstname、header-login-lastname、header-login-email分别对应HEADERUID、HEADERFIRSTNAME、HEADERLASTNAME、HEADEREMAILADDRESS等头出于安全考虑还必须设置header-login-trusted-ips信任的反代来源 IP 白名单为空时该功能拒绝一切登录fail closed。OAuth2 / OIDCRocket.Chat 等身份提供方接入文档特别指出一种常见组合如果 Rocket.Chat 自身已通过 LDAP/SAML/Google 等完成登录则这些用户同样可以登录 Wekan前提是让Rocket.Chat 向 Wekan 提供 OAuth2 登录。完整的对接配置指南见仓库文档 OAuth2 登录指南。对应到 Snap 配置键定义于 snap-src/bin/config主要步骤为# 启用 OAuth2 并填写提供方信息以 Rocket.Chat 为例 $ sudo snap set wekan oauth2-enabledtrue $ sudo snap set wekan oauth2-client-idabcde12345 $ sudo snap set wekan oauth2-secret54321abcde $ sudo snap set wekan oauth2-server-urlhttps://chat.example.com $ sudo snap set wekan oauth2-auth-endpoint/oauth/authorize $ sudo snap set wekan oauth2-userinfo-endpoint/oauth/userinfo $ sudo snap set wekan oauth2-token-endpoint/oauth/token常用 OAuth2/OIDC 键一览键说明默认值oauth2-enabled启用 OAuth2 连接falseoidc-redirection-enabled启用 OIDC/OAuth2 自动登录跳转falseoauth2-login-style登录方式popup或redirectredirectoauth2-request-permissions请求的 scopes空格分隔且不带引号如openid profile emailopenid profile emailoauth2-id-map/oauth2-username-map/oauth2-fullname-map/oauth2-email-mapID、用户名、全名、邮箱的字段映射oauth2-adfs-enabled/oauth2-b2c-enabled启用 ADFS / Azure AD B2C 变体falseoauth2-ca-cert可选的 OAuth2 提供方 CA 证书oauth2-auto-registration为false时拒绝没有既有 Wekan 账号按已验证邮箱匹配的 OIDC 登录trueoauth2-merge-existing-users安全敏感是否把 OIDC 登录合并到同邮箱的既有账号。默认false表示拒绝合并防止利用伪造的 email 声明接管账号确需开启时必须确认提供方的 email 声明可信且发送email_verifiedtruefalseoauth2-admin-groups逗号/空格分隔的组名其成员自动成为 Wekan 管理员除通用 OAuth2 外Snap 还支持 CAScas-enabled、cas-base-url、cas-login-url、cas-validate-url、SAMLsaml-enabled、saml-provider、saml-entrypoint、saml-issuer、saml-cert、saml-private-keyfile、saml-public-certfile、saml-identifier-format、saml-local-profile-match-attribute、saml-attributes以及 Google、GitHub、Facebook、Twitter/X、Meteor Developer、Weibo、Meetup 等第三方 OAuth 登录各自对应oauth-provider-enabled、-client-id/-app-id/-consumer-key、-secret及-secret-file系列键并支持oauth-providers-login-style默认popup统一设置按钮式登录的弹窗方式。passwordless-enabled可改为邮件发送一次性登录码的免密登录需配置mail-url。Matomo Web Analytics 集成Wekan Snap 原生支持与自建统计平台 Matomo 集成。文档给出的配置示例$ sudo snap set wekan matomo-addresshttps://matomo.example.com/ $ sudo snap set wekan matomo-site-id25 $ sudo snap set wekan matomo-with-usernametrue $ sudo snap set wekan matomo-do-not-trackfalse四个 Matomo 相关键的完整语义键说明默认值matomo-address托管 Matomo 的服务器地址matomo-site-idMatomo 服务器中为 Wekan 分配的站点 IDmatomo-do-not-track允许用户不被 Matomo 跟踪truematomo-with-username允许 Matomo 获取用户名false服务端对这些键的消费在 server/policy.js 中有所体现当MATOMO_ADDRESS环境变量存在时会为 Matomo 脚本与图片源放开浏览器策略白名单确保统计代码在浏览器策略开启的情况下也能正常加载执行。认证与账户安全补充键除了上文 LDAP/OAuth2 外snap-src/bin/config 还定义了一组账户安全策略键可在生产环境直接使用键说明默认值accounts-lockout-known-users-failures-before已知用户锁定的失败次数阈值需大于 03accounts-lockout-known-users-period已知用户锁定周期秒60accounts-lockout-known-users-failure-window已知用户失败窗口秒15accounts-lockout-unknown-users-failures-before未知用户锁定失败次数阈值3accounts-lockout-unknown-users-lockout-period未知用户锁定周期秒60accounts-lockout-unknown-users-failure-window未知用户失败窗口秒15accounts-common-login-expiration-in-days登录过期天数90logout-with-timer/logout-in/logout-on-hours/logout-on-minutes定时强制注销的组合开关与天/时/分参数false/notify-on-assign用户被添加为卡片成员/负责人时是否直接通知true示例启用 3 次失败锁定 60 秒并开启 9 小时 5 分钟后强制注销$ sudo snap set wekan accounts-lockout-known-users-failures-before3 $ sudo snap set wekan accounts-lockout-known-users-period60 $ sudo snap set wekan logout-with-timertrue $ sudo snap set wekan logout-in1 $ sudo snap set wekan logout-on-hours9 $ sudo snap set wekan logout-on-minutes5附件、上传与文件存储扩展键针对看板中频繁使用的附件与头像Snap 提供了一组上传校验键定义于 snap-src/bin/config键说明示例attachments-upload-external-program/avatars-upload-external-program用外部程序校验上传文件{file}会被替换为上传文件路径如接入杀毒扫描/usr/local/bin/avscan {file}attachments-upload-mime-types附件允许的 MIME 类型image/*,text/*attachments-upload-max-size附件最大字节数5000000avatars-upload-mime-types头像允许的 MIME 类型image/*avatars-upload-max-size头像最大字节数500000max-image-pixel/image-compress-ratio贴入/上传图片时自动缩小的像素上限与压缩比率文件存储位置由 snap-src/bin/wekan-control 中的WRITABLE_PATH决定默认落盘于$SNAP_COMMON/files附件与头像存放在磁盘而非数据库这是备份与迁移时必须整体拷贝的目录。其他实用键以下键同样被 snap-src/bin/config 与 snap-src/bin/wekan-help 收录可按需配置debug调试 OIDC/OAuth2 等流程sudo snap set wekan debugtrue默认false。node-options增加 Node 堆内存例如node-options--max_old_space_size4096snap-src/bin/wekan-control 会自动按可用内存计算默认堆上限约为总内存的 3/5封顶 4096 MiB。cards-loading看板卡片加载模式all默认全部载入浏览器或lazy每个列表按需只加载可见卡片适合超大看板。richer-card-comment-editor卡片评论启用富文本编辑器默认false。default-board-idOIDC 登录后自动把新用户加入指定默认看板。bigevents-pattern无论通知设置如何都强制通知的事件模式NONE禁用/ 全部received|start|due|end。notify-due-days-before-and-after到期提醒提前天数逗号分隔如2,0表示提前 2 天与到期当天。notify-due-at-hour-of-day到期提醒发送的小时0–23默认早上 8 点。email-notification-timeout邮件通知超时毫秒默认30000。results-per-page默认每页搜索结果数。wait-spinner默认等待动画样式默认Bounce。s3AWS S3 文件存储JSON 格式{s3:{key:xxx,secret:xxx,bucket:xxx,region:eu-west-1}}亦支持s3-secret-file从文件读取Docker secrets。metrics-allowed-ip-addresses允许访问 Metrics 的 IP 白名单逗号分隔。meteor-reactivity-orderMeteor 响应式驱动顺序默认changeStreams,oplog,polling无副本集环境回退为oplog,polling。wekan-autopick/wekan-autopick-timeout启动时是否对比 MongoDB 迁移前后两份数据副本以选择最新者默认true超时 900 秒关闭后站点启动更快但数据库选择需手动通过wekan.database-compare/wekan.database-merge完成。ddp-transport仅支持sockjssnap 未内置 uWebSockets.jsuws会在启动时被强制转换为sockjs。设置变更的生效机制文档结尾强调当设置被修改后wekan / mongo / caddy 服务会自动重启以使更改生效。这一行为由 snap/hooks/configure 实现其执行流程为source $SNAP/bin/config载入所有键定义读取caddy-enabled若为true则用caddy-bind-port与port更新$SNAP_COMMON/Caddyfile并启动/重启 caddy 服务否则停止并禁用 caddy调用 snap-src/bin/database-role 判断当前数据库角色运行 FerretDB 则启动 ferretdb、停止 mongodb否则依据disable-mongodb决定 mongodb 的启停database这一旧设置键已被移除旧值会被自动清理并提示忽略最后snapctl restart ${SNAP_NAME}.wekan重启 Wekan 主服务。因此每执行一次snap set服务都可能经历一次自动重启——这也是 snap-src/bin/wekan-help 末尾有些改动会导致部分或全部服务重启请谨慎使用警告的由来。总结Wekan Snap 把原本分散的环境变量配置统一成了几十上百个snap set键运维者只需掌握三个动作即可完成日常调优snap set wekan keyvalue修改、wekan.help查询全部键及默认值、sudo snap get wekan查看当前生效值。所有键的权威定义、描述与默认值都维护在 snap-src/bin/config 中随版本持续演进设置变更后的服务重启与 Caddyfile 同步则由 snap/hooks/configure 自动完成。将本文与 snapcraft.yaml 中的应用定义wekan、mongodb、ferretdb、caddy、database-backup 等命令配合阅读即可获得对 Wekan Snap 部署全貌的完整掌握。【免费下载链接】wekanThe Open Source kanban, built with Meteor. GitHub issues/PRs are only for FLOSS Developers, not for support, support is at https://wekan.fi/commercial-support/ . PR source translation to imports/i18n/data/en.i18n.json, other translations at https://app.transifex.com/wekan/wekan项目地址: https://gitcode.com/GitHub_Trending/we/wekan创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考