WBO 2.18.31 配置参数详解

本文是 WBO 专栏的配置篇。全部参数名称、默认值与取值校验行为均从 2.18.31 实例的配置装载源码（server/configuration.mjs 及 server/configuration/helpers.mjs）逐项核实，限流档语法、Turnstile 测试密钥等行为性描述来自源码内注释与实测验证。组件画像见《WBO 2.18.31 介绍与选型指南》，容器化落地见《WBO 2.18.31 Docker Compose 部署指南》，参数对接口行为的影响实测见《WBO 2.18.31 常用操作与 API 详解》。

一、环境信息

二、前置条件

1. 已按部署指南跑通一套 WBO 实例，或以 systemd/裸进程方式运行；
2. 具备服务管理权限（能重启服务使环境变量生效）；
3. 如走反向代理，确认代理层已配置 X-Forwarded-For 透传（真实 IP 相关参数的前提）。

三、参数查看与修改方式

WBO 没有配置文件，也没有管理后台，全部行为由环境变量驱动：进程启动时读取一次，改完必须重启。裸机/systemd 部署的标准做法是用一个环境文件统一管理：

# /etc/wbo/wbo.env —— systemd 通过 EnvironmentFile= 加载
LOG_LEVEL=info
WBO_HISTORY_DIR=/var/lib/wbo
WBO_SAVE_INTERVAL=2000

# /etc/systemd/system/wbo.service（要点节选）
[Service]
EnvironmentFile=/etc/wbo/wbo.env
ExecStart=/usr/bin/node ./server/server.mjs
WorkingDirectory=/opt/wbo
User=wbo
Restart=on-failure

修改流程固定为「改环境文件 → systemctl restart wbo → 看日志确认」。配置装载器对非法值的态度是快速失败：启动直接报错退出，错误信息包含合法格式提示，例如限流档写错时会得到（源码原文）：

Invalid rate-limit duration: 60x. Expected formats like 500ms, 60s, or 2m.

WBO_TRUST_PROXY_HOPS 配置矛盾时同理（源码原文）：

WBO_TRUST_PROXY_HOPS requires WBO_IP_SOURCE to be X-Forwarded-For or Forwarded

排障时若怀疑参数未生效，先确认进程实际环境（cat /proc/<pid>/environ | tr '\0' '\n' | grep WBO），再对照本文表格核对。

四、参数总览

2.18.31 全量环境变量一览（默认值取自 configuration.mjs 原文）：

五、核心参数分类详解

5.1 监听与运行态（PORT / HOST / NODE_ENV / LOG_LEVEL）

PORT 服务端默认 8080（容器镜像默认注入 80），HOST 不设则监听全部接口——生产建议显式 HOST=127.0.0.1 只对反代开放。NODE_ENV 决定开发/生产态（IS_DEVELOPMENT = NODE_ENV !== "production"），生产必设。LOG_LEVEL 取值固定四个：debug、info、warn、error，写别的值启动即报 Invalid LOG_LEVEL: ... Expected one of: debug, info, warn, error；日常 info 足够，排查重连/限流问题时临时切 debug（日志中会出现 socket.connection_replay_rejected、wbo.socket.baseline_seq 等结构化字段）。

5.2 持久化与重连窗口（WBO_HISTORY_DIR / WBO_SAVE_INTERVAL / WBO_MAX_SAVE_DELAY / WBO_SEQ_REPLAY_RETENTION_MS）

• WBO_HISTORY_DIR：每块板对应目录下一个 <板名>.svg 文件，格式 whitebophir-svg-v2，文件头 data-wbo-seq 是断电恢复的权威位点。该目录必须落在可写卷上，这是 WBO 唯一的持久化状态。
• WBO_SAVE_INTERVAL（默认 2000ms）与 WBO_MAX_SAVE_DELAY（默认 60000ms）构成「定期 + 防抖」双阈值：每 2 秒检查一次有变更的板，但任何一块板从变更到落盘最多延迟 60 秒。调小 WBO_SAVE_INTERVAL 换取更低丢笔风险，代价是更频繁的小文件写；WBO_MAX_SAVE_DELAY 是丢数据窗口的上界，按业务容忍度调整。
• WBO_SEQ_REPLAY_RETENTION_MS（默认 60000ms）：内存中操作日志的保留窗口，决定断线重连能增量回放多久的操作。该值必须小于网关层 WebSocket 空闲超时——否则客户端重连时基线已超出窗口，服务端拒绝连接（baseline_not_replayable，实测回显见 D1）。公网部署建议同步调大两侧：先调网关超时到 5 分钟，再视内存余量调大该窗口。

5.3 画布与对象上限（WBO_MAX_BOARD_SIZE / WBO_MAX_ITEM_COUNT / WBO_MAX_CHILDREN）

• WBO_MAX_BOARD_SIZE（默认 655360）：板坐标的最大绝对值，超出被消息校验拒绝。注意持久化画布是固定 5000×5000，坐标上限远大于画布是为了给变换/动画留空间，构图仍按 5000×5000 规划。
• WBO_MAX_ITEM_COUNT（默认 32768）：单板元素总数上限，防止单板把内存打爆；大教室场景默认值够用，长期挂着的公共板建议配合定期清理。
• WBO_MAX_CHILDREN（默认 500）：单元素子项上限，画笔一笔的拐点数即受它约束（协议层还有客户端提示值 192，服务端硬上限 500）。

此外消息校验层还有一组写死的硬限制（源码 client-data/js/message_limits.js，非环境变量，列出供排障对照）：线宽 size 取值 10–500、透明度 opacity 0.1–1、文本最长 280 字符、元素 id 最长 128 字符。实测中给画笔传 size=8 直接被拒，回显 {"reason":"size: invalid size"}（完整实测见 D1）。

5.4 限流档语法（WBO_MAX_EMIT_COUNT 等 4 项）

四档限流共用一套档位语法：<板名|*>:<次数>/<周期> 空格分隔多段，周期单位 ms/s/m。* 是全局默认档，具名板名是针对单板的覆盖档，例如：

# 全局每 socket 5 秒 250 次 emit；公共板 public 公开课场景放宽到 5 秒 600 次
WBO_MAX_EMIT_COUNT=*:250/5s public:600/5s

# 建设性操作（新建/追加）：匿名用户 10 秒 20 次，登录板成员 10 秒 40 次
WBO_MAX_CONSTRUCTIVE_ACTIONS_PER_IP=*:40/10s anonymous:20/10s

# 破坏性操作（删除/清板）单独收紧
WBO_MAX_DESTRUCTIVE_ACTIONS_PER_IP=*:190/60s anonymous:95/60s

# 文本创建防刷屏：默认每秒 2 次
WBO_MAX_TEXT_CREATIONS_PER_IP=*:2/1s anonymous:30/60s

触发限流后服务端向客户端发 rate-limited 事件并拒收该操作。治理思路：EMIT 档是总闸（含光标移动等高频无害消息），按带宽调；建设性/破坏性/文本三档按 IP 精细管，破坏性档建议始终比建设性档宽松（删东西不该比画东西更容易被限）。

5.5 反向代理与真实 IP（WBO_IP_SOURCE / WBO_TRUST_PROXY_HOPS / WBO_BASE_PATH）

• WBO_IP_SOURCE：客户端 IP 解析来源，可选 remoteAddress（默认，直连场景）、X-Forwarded-For、Forwarded 或任意请求头名。限流与封禁都基于它，挂反代必配，否则所有人共享代理 IP，一个用户触发限流全体遭殃。
• WBO_TRUST_PROXY_HOPS：可信代理跳数（默认 0），从 X-Forwarded-For 链右侧往左数第 N 跳取真实 IP。>0 时强制要求 WBO_IP_SOURCE 为 X-Forwarded-For 或 Forwarded，否则启动报错（见第三节回显）。单层 nginx 填 1。
• WBO_BASE_PATH：WBO 被挂在子路径（如 https://example.com/wbo/）且希望服务端感知前缀时设置。若代理层已经剥前缀（proxy_pass 末尾带斜杠的写法），服务端无需该变量——两种方案二选一，见部署指南第九节。
• WBO_HTML_HEAD_SNIPPET_PATH：指向一个 HTML 片段文件，内容注入每个页面 <head>（统计脚本、水印样式等），文件随 WBO_WEBROOT 静态机制读取。

5.6 管控与治理（WBO_BLOCKED_TOOLS / WBO_BLOCKED_SELECTION_BUTTONS / AUTO_FINGER_WHITEOUT）

WBO_BLOCKED_TOOLS 按工具 id 禁用（逗号分隔，id 与协议编码一致：pencil、straight-line、rectangle、ellipse、text、eraser、hand、grid、download、zoom、clear、cursor），禁用后服务端直接拒绝对应消息，不只是隐藏按钮。WBO_BLOCKED_SELECTION_BUTTONS 同理禁用选中菜单按钮。AUTO_FINGER_WHITEOUT 是开关型旗标（禁用类参数设为 1/true 类取值即启用禁用行为）。

5.7 认证与版主（WBO_BOARD_MODERATORS / AUTH_SECRET_KEY / TURNSTILE 四项）

• WBO_BOARD_MODERATORS：板级版主授权表，格式 板名1:用户密钥1 板名2:用户密钥2（空格分隔多块板）。用户密钥对应访问者浏览器里 wbo-user-secret-v1 cookie 的值——即先让目标用户拿到自己的密钥，再把「板名:密钥」写进环境变量重启。版主可封禁用户、授予临时版主、强制断开（对应协议事件 set_temporary_moderator、report_user、unban_user）。
• AUTH_SECRET_KEY：私有板 JWT 签名密钥（服务端 auth 模块用 jsonwebtoken），要使用私有板权限体系时必须设置非空强随机值。
• Turnstile 四项：TURNSTILE_SITE_KEY + TURNSTILE_SECRET_KEY 启用人机校验，TURNSTILE_VERIFY_URL 指向 Cloudflare 校验端点（默认官方地址），TURNSTILE_VALIDATION_WINDOW_MS（默认 900000 = 15 分钟）是校验通过后 socket 的免重复校验窗口。源码注释内置了官方测试密钥，联调时先用测试密钥验证链路再换真钥：1x0000000000000000000000000000000AA（恒通过）/ 2x0000000000000000000000000000000AA（恒拒绝）、站点键 1x00000000000000000000AA（恒通过可见）/ 3x00000000000000000000FF（交互挑战）。

六、生产配置模板

中型团队（≤50 人）内网/公网部署的推荐起点，按场景注释：

# /etc/wbo/wbo.env —— 生产基线（2.18.31 实测口径）

# ── 监听 ─────────────────────────────────────────────
# 只对本机反代开放；内存：Node 进程常规 150-300MB，建议 systemd MemoryMax=512M 兜底
HOST=127.0.0.1
PORT=8080
NODE_ENV=production
LOG_LEVEL=info

# ── 持久化 ────────────────────────────────────────────
# 磁盘：单板 SVG 通常 KB 级（实测几笔笔画 333-705 字节），1GB 空间可容千级板量
WBO_HISTORY_DIR=/var/lib/wbo
WBO_SAVE_INTERVAL=2000
WBO_MAX_SAVE_DELAY=60000
# 重连回放窗口：与网关 WS 空闲超时联动，网关 5 分钟则此处 300000
WBO_SEQ_REPLAY_RETENTION_MS=60000

# ── 画布 ──────────────────────────────────────────────
WBO_MAX_BOARD_SIZE=655360
WBO_MAX_ITEM_COUNT=32768
WBO_MAX_CHILDREN=500

# ── 限流（默认档即合理基线，按实测被限情况微调）─────────
WBO_MAX_EMIT_COUNT=*:250/5s
WBO_MAX_CONSTRUCTIVE_ACTIONS_PER_IP=*:40/10s anonymous:20/10s
WBO_MAX_DESTRUCTIVE_ACTIONS_PER_IP=*:190/60s anonymous:95/60s
WBO_MAX_TEXT_CREATIONS_PER_IP=*:2/1s anonymous:30/60s

# ── 反代（挂 nginx 时启用）────────────────────────────
WBO_IP_SOURCE=X-Forwarded-For
WBO_TRUST_PROXY_HOPS=1

# ── 认证（按需启用）───────────────────────────────────
AUTH_SECRET_KEY=<强随机串，如 openssl rand -hex 32 生成>
# WBO_BOARD_MODERATORS=team-whiteboard:ab12cd34ef56
# TURNSTILE_SITE_KEY=<从 Cloudflare 控制台获取>
# TURNSTILE_SECRET_KEY=<从 Cloudflare 控制台获取>

配套 nginx 关键配置（升级头 + IP 透传）与目录规划见部署指南第三节，此处不重复。

七、常见问题

1. 改了环境变量没生效：参数只在启动时装载。确认改的是进程真正加载的文件（systemd 场景 EnvironmentFile 路径、容器场景 compose environment 段），重启后用 /proc/<pid>/environ 核对；NODE_ENV 漏设会导致实例跑在开发态。

2. 启动直接失败并报 Invalid rate-limit duration / Expected one of: debug, info, warn, error：限流档语法或日志级别写错，装载器快速失败。档位格式严格匹配 <板名|*>:<次数>/(ms|s|m)，多段用空格分隔。

3. 挂了 nginx 后限流误伤：WBO_IP_SOURCE 仍是默认 remoteAddress，所有请求被视为代理 IP。按 5.5 节配置 X-Forwarded-For + WBO_TRUST_PROXY_HOPS=1。

4. 重连频繁报 baseline_not_replayable：WBO_SEQ_REPLAY_RETENTION_MS（默认 60 秒）小于网关 WS 空闲超时所致。两侧同步调大（建议网关 ≥ 5 分钟、该窗口 ≥ 300000），实测回显与处理建议见 D1。

5. 公共板被恶意刷大图：组合拳——WBO_MAX_ITEM_COUNT 收紧、WBO_MAX_CONSTRUCTIVE_ACTIONS_PER_IP 收紧、WBO_BLOCKED_TOOLS 禁用高消耗工具、Turnstile 启用，四项都在本文范围内可解。

八、参考链接

• 组件画像与架构：《WBO 2.18.31 介绍与选型指南》
• 部署实操与反代配置：《WBO 2.18.31 Docker Compose 部署指南》
• 接口行为与限流/回放实测：《WBO 2.18.31 常用操作与 API 详解》
• 源码仓库（configuration.mjs 为参数权威来源）：https://github.com/lovasoa/whitebophir
• Cloudflare Turnstile 文档：https://developers.cloudflare.com/turnstile/