WBO 2.18.31 介绍与选型指南

WBO 2.18.31 介绍与选型指南：基于 2.18.31 实例实测的实时协作白板组件画像，覆盖核心架构、WebSocket 协议画像、持久化格式、功能特性与同类自托管白板选型对比。

WBOWBO自托管白板2026/10/30

WBO 2.18.31 介绍与选型指南

本文是 WBO 专栏的认知篇。文中架构、协议与持久化结论均来自一套 2026-10-30 实测运行的 WBO 2.18.31 实例（package.json 版本号与页面 data-wbo-version="2.18.31" 双重核实），选型对比数据截至 2026-10。部署实操见《WBO 2.18.31 Docker Compose 部署指南》，参数逐项调优见《WBO 2.18.31 配置参数详解》，WebSocket 消息与 HTTP 端点实测见《WBO 2.18.31 常用操作与 API 详解》。

一、环境信息

项目取值
实测组件版本WBO 2.18.31（data-wbo-version="2.18.31"）
运行时Node.js，官方声明 engines.node >= 22.23.4
操作系统Linux x86_64
许可证AGPL-3.0-or-later（package.json 中 license 字段原文）
实测时间2026-10-30
服务形态单进程 HTTP 服务，内置 WebSocket 通道，无外部数据库依赖

WBO 对操作系统没有额外要求，只要 Node.js 版本达标即可运行；数据落盘为普通 SVG 文件，不需要预装数据库或消息队列，这也是它在极简自托管场景下最容易跑起来的原因。

二、软件概述

WBO（开源仓库名 whitebophir，作者 lovasoa）是一款自由开源的实时协作 Web 白板：打开浏览器即可多人同时在一块无限画布上画图、写字、贴便签，无需注册账号。它的核心卖点是把「匿名可用」做到了极致——任意访问者输入一个板名（或直接从首页随机进入）就拥有一块独立白板，所有看到同一板名的人实时共享内容。

💡 技术拓展（实时协作白板的同步架构）：协作白板的同步方案主要有三类。① 消息广播型：服务端把每个用户的绘图操作原样转发给其他客户端，服务端不理解语义，实现简单但断线重连需要全量补发，WBO 即属此类（配合序号回放做增量补发）；② OT（Operation Transformation）：对并发操作做变换归位，Google Docs 一脉的代表，实现复杂度最高；③ CRDT（无冲突复制数据类型）：每个操作满足交换律，天然支持离线合并，Yjs/Automerge 生态多用。WBO 的操作是「画一笔、加一个点」这类不可变事件，冲突面天然很小，用广播 + 服务端权威序号（seq）已足够，这也是它单文件持久化的设计基础。

版本节奏方面，WBO 采用持续演进的小版本号（2.x 系列滚动迭代），实测仓库最近一次推送在 2026-01（awesome-repositories 收录口径），属于活跃但非高频发布的节奏；镜像与源码同步发布，部署时锁定版本号即可获得确定性。

三、核心架构

实测版本的服务端为模块化 Node.js 工程，入口 server.mjs，目录职责划分清晰（以下结构摘自实测运行目录）：

/opt/app/
├── server.mjs              # 进程入口
├── server/                 # 服务端模块
│   ├── http/               # HTTP 分发、压缩、模板渲染
│   ├── routes/             # 路由（板页、静态资源、板资产）
│   ├── socket/             # WebSocket 核心
│   │   ├── index.mjs       # 连接生命周期、事件分发
│   │   ├── replay.mjs      # 断线重连的序号回放（baselineSeq 机制）
│   │   ├── message_validation.mjs  # 消息契约校验（工具编码、字段范围）
│   │   ├── rate_limits.mjs # 多档限流
│   │   ├── bans.mjs / presence.mjs / temporary_moderators.mjs  # 管理能力
│   │   └── turnstile.mjs   # Cloudflare Turnstile 人机校验
│   ├── auth/               # 板级 JWT 鉴权
│   ├── board/              # 板状态（内存权威副本）
│   ├── persistence/        # SVG 持久化（whitebophir-svg-v2 格式）
│   ├── configuration.mjs   # 全部环境变量装载
│   └── observability/      # OpenTelemetry 日志/指标/追踪
├── client-data/            # 前端代码（工具、消息契约、协议常量）
└── server-data/            # 板持久化目录（WBO_HISTORY_DIR 默认值）

三个实测确认的架构要点：

  1. 实时通道是 Socket.IO（实测依赖 socket.io ^4.8.4）：WebSocket 端点挂在 /socket.io 路径，板名通过连接查询参数 board 传入。客户端到服务端的写入事件名是 broadcast，服务端回推也复用 broadcast、boardstate、user_joined 等事件名（完整事件与消息格式见 D1）。
  2. 持久化格式为带序号的 SVG：每块板在 WBO_HISTORY_DIR 下对应一个 <板名>.svg 文件。实测文件头为 <svg ... data-wbo-format="whitebophir-svg-v2" data-wbo-seq="4" data-wbo-readonly="false">，data-wbo-seq 记录已持久化到的操作序号，服务端重启后以该文件为基线恢复板内容——这也是白板「无限画布」却只需单文件的原因：画布尺寸固定 5000×5000，元素按 SVG 标准标签（path/rect/text 等）存储。
  3. 序号回放（replay）是重连同步的核心：2.18.31 的服务端为每条被接受的写操作分配全局递增 seq，客户端重连时携带自己的基线序号 baselineSeq，服务端只回放 baselineSeq 之后的增量（replay.mjs 实现）。若基线已超出可回放窗口（日志被压缩或序号超前），连接会被拒绝并返回 baseline_not_replayable 错误——该行为已在实测中完整复现并记录于 D1，运维排障时值得重点关注。

另外，实测服务端带完整的可观测性依赖（OpenTelemetry 全家桶：logs/metrics/traces 三个 exporter），日志级别由 LOG_LEVEL 控制（debug/info/warn/error，默认 info），这是同体量自托管组件里少见的配置。

四、功能特性

以下特性均经实测页面与协议验证：

  • 匿名板：板名即访问凭据，首页随机进入或自取名字；私有板走 板名 + JWT 鉴权（server/auth/），配合 AUTH_SECRET_KEY 使用。
  • 绘图工具全家桶：画笔（pencil）、直线、矩形、椭圆、文本、橡皮擦，另有视角手型、网格、缩放、光标等辅助工具，协议层共 12 个工具编码（pencil=1 … cursor=12，完整表见 D1）。
  • 实时同步与在线感知：写操作广播回显带全局 seq 与 acceptedAtMs 时间戳；成员进出触发 user_joined/user_left，在线用户带随机昵称与代表色（实测 user_joined 回显含 userId、name、color、position）。
  • 多人管理：板级版主（WBO_BOARD_MODERATORS 环境变量按板配置用户密钥）、临时版主授予、封禁（ban）、举报（report）、强制断开（moderation_disconnect），服务端事件 active_bans 会在连入时同步封禁名单。
  • 防滥用三件套：四档按 IP 限流（总 emit、建设性操作、破坏性操作、文本创建，档位语法见 C1）、Cloudflare Turnstile 人机校验（含官方测试密钥）、工具/按钮禁用（WBO_BLOCKED_TOOLS 等）。
  • 导出：SVG/PNG 导出由前端完成（工具栏 download 工具，编码 9）；注意实测中服务端旧版的 /export、/history HTTP 端点已不存在（分别返回 400/404），导出不占服务端资源。
  • 无外部依赖的水平扩展限制：板状态是单进程内存权威副本 + 单文件落盘，天然单机定位；多实例负载均衡会导致同一板分裂在两个进程，不属于官方支持形态。

五、快速开始（最小可用示例）

最短路径是容器化部署（完整实测步骤与 compose 文件见《WBO 2.18.31 Docker Compose 部署指南》）；源码方式则要求 Node.js ≥ 22.23.4，官方启动命令为 npm ci && npm start（package.json 中 start 脚本原文：node ./server/server.mjs）。

服务起来后，两条命令即可确认实例健康（回显为 2.18.31 实测原文，节选）：

# 1) 首页可达性：确认版本口径
curl -s http://127.0.0.1:80/ | head -c 200

<!DOCTYPE html>
<html lang="en" dir="ltr" data-wbo-version="2.18.31">
  <head>
    <meta charset="utf-8" />
    <title>WBO — Collaborative whiteboard</title>

# 2) 板页按需创建：访问不存在的板名即自动建板
curl -s http://127.0.0.1:80/boards/demo | head -c 160

<!DOCTYPE html>
<html lang="en" dir="ltr" data-wbo-version="2.18.31" data-ui-direction="ltr">

<head>
	<meta charset="utf-8" />
	<title>demo | WBO | Collaborative whiteboard</title>

浏览器打开板页即可多人协作；程序化写入（WebSocket 消息格式、工具编码、实测脚本与逐条回显）见《WBO 2.18.31 常用操作与 API 详解》。

六、适用场景与限制

适用场景：

  • 团队站会、头脑风暴、远程教学涂鸦——免注册、开链接即用的场景是它的主场；
  • 嵌入自有产品的轻量协作画布：AGPL-3.0 允许商用集成（注意网络服务分发义务），协议层有完整的工具编码与消息校验契约，程序化驱动可行；
  • 低资源长期挂着的家庭服务器/内网工具：单进程 Node.js、无数据库、数据为单个 SVG 文件，备份即复制文件。

限制与注意：

  • 不支持多实例：板状态单进程权威 + 单文件持久化，不能横向扩容，多人高并发大板时注意 WBO_MAX_ITEM_COUNT（默认 32768）与限流档位；
  • 画布固定 5000×5000：坐标超出 WBO_MAX_BOARD_SIZE（默认 655360，协议换算后仍受 5000 画布约束）会被校验拒绝，超大尺寸构图需要规划；
  • 重连依赖序号回放窗口：WBO_SEQ_REPLAY_RETENTION_MS（默认 60 秒）之外的增量不可回放，服务端会拒绝过旧/超前的基线并返回 baseline_not_replayable，客户端需全量刷新——网关层长连接超时务必大于该窗口；
  • AGPL 传染性：对外提供网络服务时需遵守 AGPL-3.0 的源码提供义务，商业闭源集成需法务评估；
  • 导出依赖前端：服务端无服务端渲染导出端点，自动化批量导出需自行驱动无头浏览器。

七、同类选型对比

与主流可自托管的协作白板对比（数据截至 2026-10，星数取自 openalternative/awesome-repositories 收录口径）：

维度WBO (whitebophir)Excalidrawtldraw
GitHub 星数约 2.6K约 134K约 51K
许可证AGPL-3.0MITSDK 4.0（2025-09）起商用需付费授权
技术栈原生 JS + Socket.IO + Node.jsReact + TypeScriptReact + TypeScript
服务端依赖Node.js 单进程，零外部服务同步服务需另配（官方快照方案）需 WebSocket 后端（官方示例用 Cloudflare Durable Objects）
持久化单文件 SVG（whitebophir-svg-v2 + 序号）场景 JSON（快照存储）依赖所选后端实现
匿名可用原生支持，板名即凭据支持实时协作房间需自建多用户方案
防滥用/治理内置限流、Turnstile、版主/封禁无内置，需自加SDK 层无，需自建
版本节奏2.x 滚动迭代，2026-01 仍有推送高频发布高频发布（SDK 商业化节奏）
兼容矩阵现代浏览器；服务端 Node ≥ 22.23.4现代浏览器现代浏览器 + React 18/19
适合谁要一个「开箱即用的多人白板服务」且愿意自己管治理要手绘风格 diagram + 生态插件要把画布当 SDK 嵌进自家产品

选型结论：把「多人同时涂画、零账号、低运维」作为第一诉求时 WBO 的综合成本最低——治理（限流/人机校验/版主）开箱即有，持久化与备份最简单；要手绘风图表与庞大生态选 Excalidraw；要做画布型产品选 tldraw（注意其 2025-09 起的商用授权变化）。

八、参考链接