jw_JIAWEI WANGGitHub ↗
← 返回项目作品
04 / REALTIME COLLABORATION / CASE STUDY

Realtime Collab Editor

分布式实时协同代码编辑器

同一份代码,
让协作与恢复都有秩序。

用 Go 构建实时协同内核,连接 React 与 Monaco 浏览器编辑器。围绕并发编辑、多节点归属、断线恢复与动态权限,提供文档协作和隔离的 Go 代码执行。

ROLE个人项目 · 协同编辑系统
FOCUS分布式实时协同代码编辑器
SOURCEGitHub ↗
GoReactTypeScriptMonaco EditorOTQUICWebTransportMySQLRedisetcd
01 / THE PROBLEM

为什么做这个项目

实时编辑的难点,不止是把文字广播给另一个用户。两个人可能同时修改同一位置,网络会中断,文档 Owner 可能退出,权限也会在会话期间变化。这个项目围绕这些问题实现可恢复的协同编辑链路,并提供可操作的浏览器工作区。

01

协同工作区

文件夹与文档导航、文档搜索、分享和版本浏览 / 对比。

02

实时编辑

多用户编辑、远程光标与选区、在线成员和待同步编辑恢复。

03

Go 代码运行

对当前编辑内容执行单文件 Go 程序,展示 stdout、退出码与耗时。

02 / HOW IT WORKS

从输入,到可检查的结果

  1. 01

    建立受控会话

    REST 负责账号、文档与权限管理;浏览器实时连接优先使用显式配置的 WebTransport,或使用 WebSocket 兼容路径。

  2. 02

    定位文档 Owner

    入口节点根据可信成员信息解析归属。文档不在本节点时返回 Owner Redirect,客户端校验目标后连接。

  3. 03

    排序与变换编辑

    进入文档 Room 后串行处理事件,用版本化 OT 转换 Insert / Delete,并在事务中保存操作与状态。

  4. 04

    确认并恢复

    客户端跟踪文档版本和 pending 编辑;重连及 Owner 切换后以 Snapshot + Replay 恢复文档,再继续同步。

03 / SYSTEM DESIGN

架构与职责划分

把不同的职责放在明确的边界内,让每一步的输入、输出和失败方式都可以单独理解。

ARCHITECTURE MAPRealtime Collab · 协同数据面与执行隔离
实时会话进入单文档 Room,etcd 负责归属,MySQL 负责最终写入保护;代码执行使用独立 Runner 路径。
蓝色:核心模块 · 虚线:辅助依赖 / 独立路径↔ 横向滑动查看完整架构

蓝色节点为核心控制边界;Run 路径不进入 Room / OT / Operation Log。

分层职责速览

01 / 浏览器客户端React + TypeScript + Monaco / Zustand / IndexedDB
02 / 实时传输WebTransport / WebSocket / Native QUIC → 共享会话 → Room
03 / 一致性与归属etcd Lease / Ownership + MySQL Fencing / Logs / Snapshots
04 / 独立执行路径Execution API → 认证 Unix Socket → Runner → 临时 Docker Sandbox

核心工程实现

Room 单写入者与版本化 OT

每份文档由一个 Room goroutine 串行处理 Join、Leave、Edit、Resume、权限变化及关闭事件。编辑在该事件队列中完成权限校验、Version 检查、OT Transform 与 CommitEdit,支持 Insert/Insert、Insert/Delete、Delete/Insert、Delete/Delete 组合。

数据库必须先提交,之后才更新 Room 内存与广播。Operation Log 保存经过 OT 后实际应用的操作,request_id 提供重试幂等性;事务失败不会提前改变内存文档或让其他客户端看到尚未持久化的内容。

Ownership、Rendezvous 与数据库 Fencing

Rendezvous Hashing 对 READY 节点生成稳定候选顺序,但排名不授予写入权。候选通过 etcd Transaction 获取 Lease 保护的 Ownership,进入 RECOVERING,在 MySQL 激活更高的 Fencing Token,恢复并校验文档后才切换为 ACTIVE。

Edit、Permission、Snapshot 与恢复基线写入,都在同一个数据库行锁事务中验证 WriteAuthority 的 NodeID 和 FencingToken。etcd 与 MySQL 无法原子提交,因此最终写入资格放在持久化边界;新 Token 激活后,网络分区中仍运行的旧 Owner 也不能继续写入。

Snapshot + Replay 与 Room 生命周期

Room 重建加载最新 MySQL Snapshot,再按 Version 顺序重放后续实际应用的 Operation,最后与 documents 行比对。出现版本缺口或内容不一致时拒绝激活,避免向客户端提供错误基线。只有 Snapshot 保存成功后才推进 History Floor,防止失败快照导致增量历史被提前裁剪。

Room Manager 以 opening、active、stopping 管理本地 Entry,并发打开共享同一个 Entry。无客户端 Room 可在空闲超时后回收;Manager 锁只保护短暂状态变化,etcd 与存储 I/O 在锁外完成。关闭期间拒绝新工作,并等待在途编辑完成或通过 Context 取消。

共享会话核心与可信 Owner Redirect

原生 QUIC、浏览器 WebTransport 与 WebSocket Adapter 进入同一个实时会话核心,共用 JWT / Session 校验、Owner Redirect、Room 接入、Resume / Sync、Cursor 和撤销语义。REST 负责认证、文档与权限管理,避免各传输层复制一套协作逻辑。

非 Owner 节点只使用可信 etcd Membership 中的目标,客户端校验重定向后重新连接;Owner-sensitive 权限写入通过内部 mTLS 转发并重新鉴权。非法目标、重定向循环或 Owner 不可达时拒绝执行。浏览器仅在缺少 WebTransport API 时自动回退,TLS 或 Origin 失败不会触发静默降级。

本地 Pending、断线恢复与操作幂等

客户端在网络发送前保存待确认编辑,恢复连接后先完成认证、文档版本同步,再按原始 request_id 顺序重试。浏览器使用 IndexedDB 保留 Pending;原生客户端使用 SQLite 保存版本与操作,Refresh Token 存入 OS Keyring。

连接状态机处理重连、指数退避、Owner 切换及 RESUME / SYNC / RESYNC_REQUIRED,避免同时运行多个重连循环。Pending 与服务端幂等检查共同处理“请求已提交但 ACK 丢失”,保证恢复过程不把同一编辑当作新的修改重复执行。

临时 Presence 与跨节点 Session 撤销

Monaco 的 UTF-16 位置先转换为 Unicode code-point offset,再发送带 Sequence 的节流 cursor_update。Owner Room 校验读取权限和版本,并用保留的 OT History 转换旧光标位置;服务端派生身份后广播远程光标与选区。Presence 不增加文档 Version,也不写入 Operation Log 或 Snapshot。

Session 撤销通过 Redis Operation Lease 协调在途业务操作,Pub/Sub 通知各节点关闭连接,周期性 reconciliation 补偿遗漏通知。每次认证使用仍检查 Session,Redis 异常时拒绝继续授权,不能只依靠可能丢失的通知保障撤权。

Execution API → Runner → Docker Sandbox

运行的是当前 Monaco Buffer,经 owner / write 权限检查、用户级与节点级限制后,通过认证 Unix Socket 交给独立 Runner。公共 API 不持有 Docker Socket,只有 Runner 能创建沙箱。执行不经过 Room、OT、Snapshot 或 Operation Log,也不改变文档版本。

每次请求使用无网络、非 Root 的临时 Docker 容器,约束资源、运行时间和输出大小,返回 stdout、退出码与耗时,源码与输出不长期持久化。当前边界为单文件 Go 与标准库;多文件工程、第三方依赖及其他语言不在范围内。

04 / ENGINEERING DECISIONS

技术难点与设计取舍

01

为什么每份文档由一个 Room goroutine 管理?

将文档状态和编辑事件集中在单一事件队列中,有助于明确操作顺序,减少并发修改共享状态的复杂度。慢客户端通过有界发送队列和非阻塞广播处理。

02

为什么有 etcd Lease,还需要数据库 Fencing?

租约表达当前归属,无法单独阻止因网络分区而继续运行的旧进程。写事务同时校验更高代次的 Fencing Token 与 NodeID,把最终写入资格落在持久化边界。

03

传输协议切换会不会复制协同逻辑?

不同传输适配器共用认证会话和 Room 路径,复用重定向、同步、游标和撤权逻辑。浏览器自动回退仅在缺少 WebTransport API 时使用,TLS 或 Origin 失败不自动降级。

04

为什么代码运行不进入文档日志?

运行的是当前 Monaco 缓冲区,执行本身不应改变协同文档版本。独立 Runner 承担 Docker 调用,公共 API 不持有 Docker Socket,执行结果与编辑数据链路分离。

06 / VERIFY & REFLECT

如何验证,以及做到哪里

01

并发与恢复验证

仓库包含 OT、Room、权限、协议与客户端状态机测试;真实依赖集成覆盖 Fencing、归属接管、Snapshot + Replay 与重连。

02

浏览器协同验证

仓库验收文档记录双用户编辑、IndexedDB pending 恢复、远程光标、跨节点切换及会话撤销的浏览器 E2E。

03

执行隔离与部署边界

仓库提供真实 Docker 沙箱验证和质量门禁记录。本轮只核对文档并检查作品集展示,没有重新运行这些集成测试或部署云资源。

CURRENT SCOPE

当前实现边界

编辑器同步线性文本、光标和选区,OT-lite 不等同于完整 CRDT。版本历史支持浏览和对比,未提供历史版本恢复或共享会话中仅撤销个人编辑。Runner 只执行单个 Go 源文件和标准库;多文件、第三方依赖及其他语言不在当前范围。Google Cloud Terraform 已准备,云部署未执行。

继续阅读

GitHub / 项目总览 ↗浏览器验收记录 ↗传输与恢复设计 ↗Go Runner 边界 ↗内容依据当前项目 README 与架构文档整理;展示工程设计和验证方式,不将示意图或流程描述作为实时运行数据。
NEXT PROJECT / 05

AquaGuard

家庭用水管理 Android App

↗