微服务架构在线协同编辑系统实战：从服务拆分到OT一致性

简介：这是一份面向毕业设计或课程设计场景的在线协同编辑系统完整源码，采用微服务架构，前端基于Vue实现，覆盖用户管理、文档协作、实时编辑等典型模块，适合作为高分开题素材或学习微服务落地实践的参考项目。包内共253个文件，以Java后端、Vue组件、TypeScript/JavaScript逻辑、YAML配置、Dockerfile容器化部署文件及SQL初始化脚本为主，整体约2.9MB，结构紧凑，便于按模块查阅。从文件构成看，项目既包含服务拆分与接口层代码，也包含前端页面、样式和构建配置，能够完整体现前后端分离的协同编辑工程结构；配套的Dockerfile、conf文件与数据库脚本，可辅助快速完成环境搭建。源码已经过本地编译验证，下载后结合说明配置环境即可运行，难度适中且经助教老师审定，能满足课程设计或毕设训练需求。目前已有195人浏览学习，可用于快速搭建可演示的协同编辑原型，也可借鉴其服务拆分、前后端交互与部署方案。

1. 在线协同编辑系统的微服务架构毕设源码，值不值得照着做

毕业设计答辩讲“在线协同编辑系统”的人不少，拿高分的人不多，因为大多数作品停在“能存能读”，没有做到“协同”。基于微服务架构的在线协同编辑系统，把文档存储、用户会话、实时协同拆到独立服务里，核心要打通的只有一件事：多个客户端同时编辑一份文档时，操作不互相覆盖，内容最终一致。这个题适合已经会 Spring Boot 基础 CRUD、但没实操过注册中心和 WebSocket 的同学；源码落地后，你可以把服务拆分、实时通信、冲突处理讲成一条完整的链路，答辩时一问一个准。

系统真正解决的不是文档 CRUD，而是并发编辑冲突和更新推送延迟。拿高分的关键也在这：单体应用很难解释“为什么文档保存会卡住长连接”，微服务架构天然把负载类型分开，文档落库走 HTTP 短连接，协同推送走 WebSocket 长连接，互不拖累。这篇笔记按架构设计、搭建顺序、核心代码、踩坑记录、答辩验证五个部分讲透这套源码怎么用起来。

2. 微服务架构的在线协同编辑系统怎么拆：服务边界、通信选型与一致性策略

2.1 服务边界：四个服务足够撑起微服务的全部概念

拿到在线协同编辑系统的源码压缩包，第一件事不是看代码，而是先数模块。成熟一点的毕设源码不会拆十几个服务，那会让论文篇幅全耗在服务通信上，业务反而讲不清楚。围绕一份在线文档的编辑场景，四个服务加一个注册中心就能把微服务架构的关键点全部覆盖：

这个拆分逻辑的核心是“负载类型分槽”：HTTP 流量走前三个服务，长连接流量走 collab-service。如果把 WebSocket 和文档 CRUD 塞进同一个进程，一旦文档保存触发慢 SQL，长连接心跳也会跟着卡顿，一次故障影响两类用户。这是微服务落地最直观的收益，也是答辩时最容易讲清楚的点。

服务发现建议用 Nacos，别用 Eureka 硬编码地址。四个服务的启动顺序要养成习惯：先启动注册中心，再启动业务服务。每个服务里spring.application.name必须全局唯一，否则网关用lb://做负载均衡路由时会串服务，后启动的实例会顶掉同名服务。常见做法是在父 pom 用dependencyManagement统一 Spring Cloud 版本，避免各模块引入的 Nacos client 版本不一致导致注册失败。

2.2 实时通信选型：Spring WebSocket 与 Netty 怎么取舍

在线协同系统的实时通道基本不会用 HTTP 轮询，因为轮询把网关和数据库都拖下水，还保证不了输入延迟。主流做法是 WebSocket 长连接，连接建立后双向推送文本帧。Java 技术栈里有两个方向：基于 Spring 的注解式 WebSocket，开发速度快，和 Spring Security 整合顺畅；基于 Netty 自研协议，吞吐上限更高，但要自己处理粘包半包、心跳、断线重连，代码量翻倍不止。

对毕设项目来说，性能瓶颈几乎不会出现在 WebSocket 框架本身。哪怕模拟 2000 个在线连接，Spring WebSocket 也能撑住，前提是心跳和线程池参数别用默认值。默认的容器线程池很小，高并发下握手请求会排队。建议在配置里把server.tomcat.threads.max提到 200，WebSocket 的maxSessionIdleTimeout设为 60000 ms 配合前端 30 秒一次心跳。

如果源码里选的是 Netty 协议栈，论文里就要补两块内容：一是粘包半包处理，二是空闲心跳检测。这两块反而能成为加分项，因为 Netty 方案比注解式 WebSocket 更能体现你对网络编程的理解。但要清醒，报文协议一旦自己定义，前端也要跟着改，调试成本比 Spring 方案高一个量级。

2.3 一致性策略：OT 还是 CRDT，各看一段再决定

多人编辑同一份文档，真正复杂的是并发冲突。两个用户同时在一行文字的不同位置插入，谁的先应用，谁的索引向后偏移，必须由算法决定。业界两条路：操作转换（OT）和无冲突复制数据类型（CRDT）。OT 的思路是给每个编辑操作带一个起始版本号，服务端按版本串行化操作，当两个操作基于同一版本并发产生时，后到的操作做一次转换再应用。CRDT 的思路是不做全局排序，每个操作携带足够的上下文信息，任意顺序合成都收敛到一致结果。

毕设源码如果用了 OT，核心代码一般集中在服务端的操作转换器里，客户端只管发送操作和接收转换后的操作。OT 实现相对直观，版本号管理虽然有边界情况，但论文里能用图把转换过程画清楚。CRDT 如果用了 Yjs 这类库，代码层面大量细节被封在库内部，论文不好展开。从答辩角度考虑，OT 的简化实现更值得投入，因为你能把“版本号递增、偏移量计算、冲突合并”三步讲进代码里。

协同服务的存储也要讲清楚：collab-service 本身不该持久化文档正文，它只负责传输和转换，操作日志落到 document-service 侧的 operation_log 表。如果协同服务挂了，文档服务还能根据快照和操作日志恢复现场。这个设计与微服务架构“故障隔离”的理念绑定，论文里必须写。

3. 复现在线协同编辑系统源码的过程：注册中心、网关路由与协同核心代码

3.1 启动顺序与最小配置：先把四个服务拉起来

代码包解压后一般是 Maven 多模块结构，四个服务加上一个公共 common 模块。先从启动脚本顺序入手，能最快验证环境没问题。这里给出常见的启动流程，按步骤执行：

# 1. 启动注册中心，standalone 单机模式即可 sh nacos/bin/startup.sh -m standalone # 2. 确认 8848 端口已经监听 curl -X GET "http://127.0.0.1:8848/nacos/v1/console/health/readiness" # 3. 编译整个工程，跳过测试 mvn clean package -DskipTests -pl document-service,auth-service,collab-service,gateway-service # 4. 先启动依赖数据库的业务服务：认证与文档服务 java -jar auth-service/target/*.jar --server.port=9100 & java -jar document-service/target/*.jar --server.port=9200 & # 5. 再启动网关和协同服务 java -jar gateway-service/target/*.jar --server.port=9000 & java -jar collab-service/target/*.jar --server.port=9300 &

逻辑说明：注册中心必须在业务服务之前启动。Nacos 健康检查接口返回{"status":"UP"}再往下执行。编译参数里-pl只编译指定模块，避免把测试模块一起打包浪费几分钟。启动顺序选“先认证和文档，再网关和协同”是经验之谈，网关启动时要拉取全部路由信息，协同服务启动时要创建 WebSocket 端口，晚一步启动能减少日志里一堆 “service not found” 的告警。

参数说明：端口不是写死的，可以用--server.port覆盖。如果本机 8848 被占用，需要同步修改每个模块 bootstrap.yml 里的spring.cloud.nacos.server-addr。一个常见误区是只改 application.yml 不改 bootstrap.yml，导致服务仍然连旧地址。微服务项目的注册中心配置一般放在 bootstrap.yml，它比 application.yml 更早加载。

3.2 网关配置：路由规则、鉴权旁路与 WebSocket 代理

网关是前端访问后端唯一入口。文档接口走 HTTP 路由，协同接口走 WebSocket 代理。Spring Cloud Gateway 里配置如下：

spring: cloud: gateway: routes: - id: auth-route uri: lb://auth-service predicates: - Path=/api/auth/** - id: document-route uri: lb://document-service predicates: - Path=/api/docs/** - id: collab-ws-route uri: lb:ws://collab-service predicates: - Path=/ws/**

逻辑说明：lb://开头表示走负载均衡服务发现，网关会通过 Nacos 找到对应服务的实例，实现按服务名转发。协同服务的路由必须是lb:ws://协议前缀，否则 WebSocket 握手请求会在网关层变成普通 HTTP，连接没法升级，前端会一直报 401。文档接口如果按Path=/api/docs/**转发，前端所有 HTTP 请求统一走 9000 端口，跨域配置也只需要在网关做一次。

参数说明：路由优先级按配置顺序匹配，/ws/**放在最后。如果项目里有文件上传接口且带了MultipartFile，记得给该路由加spring.codec.max-in-memory-size配置，不然网关默认 256KB 上限会让大文档导入直接失败。鉴权可以在网关卡一道全局过滤器，但内部服务之间的调用不应再重复校验，避免 token 在同一个链路里被解析两遍。

3.3 协同服务核心：WebSocket 接入、房间管理与操作广播

协同服务按文档 ID 划分房间，每个房间对应一个文档的实时编辑会话。使用 Spring 注解式 WebSocket 实现端点：

@Component @ServerEndpoint("/ws/collab/{docId}") public class CollabSocketEndpoint { // 房间映射：docId -> 当前在线 Session 集合 private static final Map<String, Set<Session>> ROOMS = new ConcurrentHashMap<>(); @OnOpen public void onOpen(Session session, @PathParam("docId") String docId) { ROOMS.computeIfAbsent(docId, k -> ConcurrentHashMap.newKeySet()).add(session); session.setMaxIdleTimeout(60000); } @OnMessage public void onMessage(String message, @PathParam("docId") String docId) { // 1. 解析客户端编辑操作 DocOp op = JsonUtils.parse(message, DocOp.class); // 2. 调用 OT 转换，合并到当前版本 DocOp transformed = opTransformer.transform(op, docId); // 3. 广播给该房间内其他客户端 ROOMS.get(docId).forEach(s -> { if (!s.equals(session)) { s.getBasicRemote().sendText(JsonUtils.toJson(transformed)); } }); } @OnClose public void onClose(Session session, @PathParam("docId") String docId) { ROOMS.getOrDefault(docId, Set.of()).remove(session); } }

逻辑说明：ConcurrentHashMap.newKeySet()保证并发线程安全，多个客户端同时接入时不会出现 ConcurrentModificationException。onMessage里先做 OT 转换再广播，顺序不能反，否则后到的客户端操作会基于旧版本应用到新文档上，产生内容回滚。广播时排除自己，避免接收端重复应用操作导致重复插入文字。

参数说明：setMaxIdleTimeout(60000)含义是 60 秒内既没有发消息也没有心跳，服务端主动断开连接。前端需要每 30 秒发送一次{"type":"ping"}心跳帧，配合服务端空闲超时使用。房间管理用的是 JVM 内存 Map，单机部署没有跨节点问题；如果协同服务扩到多实例，就要把房间信息搬到 Redis，用发布订阅广播操作，这是后期优化点。

3.4 简化版 OT 实现：版本号与偏移量计算

一套能答辩的协同编辑系统，至少要有一个 OT 转换的雏形。下面的代码是简化版操作转换，处理插入和删除两类操作的索引偏移：

public DocOp transform(DocOp op, String docId) { DocumentSnapshot snapshot = docService.getSnapshot(docId); int baseVersion = op.getBaseVersion(); int currentVersion = snapshot.getVersion(); if (baseVersion == currentVersion) { op.setBaseVersion(currentVersion); return op; } int offset = 0; // 从 base 到 current 之间的所有历史变更，逐个判断是否影响本次操作位置 for (EditChange change : snapshot.getChangesSince(baseVersion)) { if (change.getInsertIndex() <= op.getIndex()) { offset += change.getInsertLength(); } else if (change.getDeleteIndex() < op.getIndex()) { offset -= change.getDeleteLength(); } } op.setIndex(op.getIndex() + offset); op.setBaseVersion(currentVersion); return op; }

逻辑说明：两个客户端在同一位置插入时，后到达服务端的操作要先“让路”。getChangesSince拉取从操作起始版本到当前版本之间所有已应用变更，逐条计算索引偏移。插入位置在当前操作位置之前，索引往后移；删除位置在当前操作位置之前，索引往前移。转换完成后更新操作的基准版本号，保证下一次并发冲突计算准确。

参数说明：op.getBaseVersion()是客户端记录的服务端版本号，客户端每次收到广播后要回写版本号。如果客户端连续输入速度快，本地会产生多个未确认操作，这组操作要按队列串行发送，不能并行，否则版本号会错位。这里的版本号只代表操作序列的计数，不做分布式 ID 生成，单文档场景用自增版本即可。

4. 在线协同编辑系统微服务化避坑记录：启动、同步、连接三类重灾区

4.1 现象：服务启动秒退，日志报 Nacos 注册失败

原因：最常见的是注册中心还没就绪就启动了业务服务。Nacos 单机模式要 10 秒左右完成初始化，业务服务连不上就拒绝启动。另一个原因是 bootstrap.yml 里的server-addr写的是 localhost，而 Nacos 绑定的是局域网 IP，出现连接被拒。

解决：严格按顺序启动，用健康检查接口确认注册中心就绪再跑业务服务。地址统一改成127.0.0.1:8848，不要用 localhost，避免 IPv6 解析问题。启动失败时优先看 Nacos 控制台的“服务列表”，服务名出现两次才说明注册成功。

4.2 现象：协同编辑内容回滚，后输入的文字消失在已保存内容里

原因：OT 转换的版本号没有回写。客户端发送操作后，没有把服务端返回的最新版本号更新到本地缓存，第二次操作仍然携带旧的 baseVersion。服务端认为操作基于旧版本，做了转换后应用，但实际上客户端本地的文档内容已经包含部分新内容，再次应用旧操作就导致重复或者错位。

解决：在客户端收到广播消息后，立即更新 localVersion。每次发送操作前，把baseVersion设为本地缓存的版本号，而不是上一次发送时记录的版本号。调试时在服务端日志打印op.baseVersion -> currentVersion，如果出现跳号，优先检查客户端状态管理。

4.3 现象：WebSocket 连接频繁断开，前端反复重连

原因：服务端 60 秒空闲超时，前端心跳间隔超过 60 秒，或者反向代理层的空闲超时比服务端更短。很多教程给的 Netty 心跳配置是 30 秒，但 Spring WebSocket 默认的空闲超时很宽松，两套配置互相冲突，导致连接被代理层先断掉。

解决：把服务端maxIdleTimeout显式设为 60000 ms，前端心跳固定 30 秒一次。如果网关层开了 nginx，proxy_read_timeout要大于服务端超时时间，建议 75 秒。心跳消息不要走业务 JSON 序列化，单独定义{"type":"ping"}帧，逻辑层直接丢弃。

4.4 现象：网关偶尔返回 401，但直接访问内部服务却正常

原因：认证服务和网关使用的 JWT 密钥不一致。微服务模块各自维护一份密钥配置，认证服务签发的 token，网关用另一把密钥解析，结果是 token 时而有效时而无效。这种问题不是每次都出现，只在密钥旋转或模块单独部署时爆发。

解决：JWT 密钥放配置中心统一管理，本地开发时用环境变量注入，不要把密钥写死在application.yml。网关过滤器解析 token 只做合法性校验，用户信息从X-User-Id头透传给下游服务，下游服务不要再重复解析 token。

4.5 现象：文档保存报死锁，MySQL 日志出现 lock wait timeout

原因：document-service 里保存文档正文和写操作日志是两条 SQL，事务顺序不一致。两个用户同时编辑，一个先更新文档表再插入日志表，另一个先插入日志表再更新文档表，互相持有锁等对方释放。

解决：统一事务内 SQL 顺序，先更新文档版本表和正文，再插入操作日志。更稳妥的做法是文档正文和操作日志用同一个事务提交，版本号用SELECT ... FOR UPDATE锁定后再更新，避免乐观锁冲突导致的死锁。死锁发生后优先看两张表的索引是否有重叠，索引设计不当会放大锁范围。

5. 把在线协同编辑系统做成高分答辩项目：验证手段、压测指标与演示顺序

系统的正确性验证比性能数字更有说服力，答辩现场的翻车事故九成出在演示环节，所以要先把协同一致性场景打透。打开两个浏览器窗口同时进入同一文档，分别在句首和句尾输入文字，观察两个窗口内容是否都完整包含双方编辑。这个场景验证的是 OT 索引偏移是否正确，如果出现内容回滚，说明版本号管理有问题。接着在同一个位置快速输入连续字符，观察是否有覆盖和丢失，这个场景验证的是客户端操作队列和版本号回写是否正常。用两个窗口反复输入、撤回、再输入，能覆盖掉大部分边界问题，比压测多活 20 个连接更有答辩价值。

性能指标只验证两个数字就够：在线连接数和操作广播延迟。用 WebSocket 压测脚本模拟 200 个客户端同时连接，观察服务端线程池和内存占用；再用每秒发送 100 次编辑操作的频率跑 5 分钟，统计服务端广播延迟是否稳定在 100ms 以内。这两个数字能让答辩委员快速判断你的系统在并发编辑场景下的真实承载能力。

演示顺序建议按“微服务架构全景图 → 协同编辑实时演示 → 代码中 OT 核心 → 故障恢复”来安排。先讲为什么拆四个服务，再现场操作两个浏览器协作编辑，把内容冲突化解过程放大给评委看，然后切到代码定位版本号转换那段逻辑，最后补充服务挂掉后操作日志如何恢复。答辩问题若问“为什么不用单机模式”，就从负载类型隔离和故障隔离两个角度回答；若问“并发冲突更多时怎么办”，就把版本号自增的局限和引入分布式 ID 的方向说出来。

我自己带毕设时最深的体会是：源码能不能跑通决定下限，能不能讲清“冲突是怎么解决的”决定上限。拿到这套在线协同编辑系统源码后，我希望你至少改动两个地方再上答辩台，比如把心跳间隔做成可配置项、给操作日志增加按时间查询的接口。这两处的改动虽小，却能证明代码是你消化过的，而不是下载后原样提交的。希望这篇笔记能帮你在答辩前把每个模块的边界都摸清，把最容易被问住的协同一致性讲出底气。

本文还有配套的精品资源，点击获取