1. 项目全貌：为什么叫Apollo-11
拿"Apollo-11"当项目代号，多少带点浪漫主义。阿波罗11号是人类第一次成功登月的任务代号，代表着"目标明确、过程波折、最终落地"。我们这个项目也是一样：要做的事不算复杂，但真正推进起来才发现，越简单的需求背后越是暗藏汹涌。这个代号是某团队内部一次头脑风暴时定下来的，后来一直沿用，几经折腾也没换过。
所谓"Apollo-11"，本质上是一个面向移动端H5和小程序场景的多人共享体验平台。用户创建一个房间，把链接发给别人，大家进入同一个工作台后，可以实时看到彼此的操作、共享同一个状态、在同一个画面上协作。想象两个人在同一张白纸上轮流写字，一个人落笔另一个人立刻能看到，这就是这个项目最核心的体验。
这个项目解决的问题其实非常具体：在弱网、多端、跨平台的环境下，让多人共享同一个动态页面状态，而且延迟要低、状态不能乱。听起来像是一个在线协作白板该做的事，但放到真实业务里会发现，很多团队并不需要那么复杂的协同编辑，他们需要的只是一个"轻量级共享容器"，把现有的H5页面、表单、播放器等装进去，就能获得实时同步能力。
合适谁来参考？如果你是做前端、小程序、或者通信层开发的人，这个项目的拆解会很有价值。尤其是那些正在做共享房间、联机互动、实时同步类功能的团队，这篇文章里很多坑你应该都会踩一遍。
开展这个项目之前，我们其实评估过现成的开源方案，也考虑过直接用第三方的实时协作服务。但最终决定自研，原因有三点：第一，业务场景里有大量定制的权限逻辑，现成方案改造成本不低；第二，数据要落到自己的服务器上，满足存储和审计要求；第三，当时的业务并发量虽然不高，但对成本敏感，自研一套轻量方案长期算下来更稳妥。说白了就是需求不算大，但定制多，租不如买，买不如造。
这个决定谈不上多高明，但在当时的约束下是最合理的选择。如果一个项目需求清晰、边界固定、没有复杂的定制逻辑，用现成的方案绝对更快。但Apollo-11不一样，它的核心壁垒恰恰在定制能力上。
2. 技术选型与架构设计：把"同步"这件事做稳
2.1 通信层方案：为什么放弃轮询，死磕WebSocket
最早做技术预研时，团队内部有过一轮争论：到底用轮询还是WebSocket？轮询的方案实现最简单，前端定时请求后端接口，把最新的状态拉下来。但稍微推演一下就发现问题很大——共享体验的核心是"实时"，如果轮询间隔设1秒，那用户的操作到其他人屏幕上至少要延迟1秒以上，稍微一卡顿就可能到3秒，这在协同操作场景里是不可接受的。
有人提出用长轮询，也就是前端发起请求后，后端不立即返回，而是挂起一段时间，有数据更新或者超时再返回。这个方案确实能缩短延迟，但代价是服务器资源消耗大，长连接的数量一多，后端线程池很容易被打满。
还有一个备选是SSE（Server-Sent Events），服务器单向推送消息给客户端。这个方案对某些场景是够用的，比如一个页面状态只被一个人修改，其他人只读。但Apollo-11的共享场景是双向的，A用户在画布上画一笔，B用户也需要能够回传自己的操作，SSE的单向特性根本撑不起来。
最后选定了WebSocket，全双工、低延迟、协议成熟，加上移动端浏览器和小程序对WebSocket的支持已经很完善，不需要额外引入SDK。用一句话解释WebSocket和普通HTTP的区别：HTTP就像你打电话时每说一句话就要挂断重拨，而WebSocket是一条电话接通后一直不挂断，双向说话，随时说随时听。这天然契合共享体验的场景。
WebSocket方案定下来后，后续又补了几个关键设计：
- 心跳机制：接收方和发送方每30秒发送一次ping帧，一个周期内没收到pong就判定连接异常。这个参数不是拍脑袋定的，而是多次压测后取的经验值，间隔太短会空耗资源，间隔太长则会延迟发现断线。
- 断线重连：前端监听到连接关闭或异常，执行指数退避重连策略——第一次等1秒，第二次等2秒，第三次等4秒，最多等30秒。这个策略避免了集体重连导致的服务端连接风暴。
- 连接状态分级：连接分为"未连接""连接中""已连接""重连中"四个状态，状态变化时同步更新UI展示。用户在线状态不再是模糊的"在不在"，而是"在线""离开""努力重连中"，体验会更直观。
2.2 状态同步与序列化方案：JSON一时爽，protobuf顶大梁
通信层的通道建立了，接下来要解决的是"数据怎么表达"的问题。共享体验平台里，实时同步的数据包括用户的坐标信息、页面操作指令、状态变更事件等，这些数据结构不算复杂，但频率很高。
最初的版本用的是JSON，前端把对象转成字符串通过WebSocket发送，后端拿到解析完存进Redis再广播。上线后发现一个问题：JSON的包体太臃肿了。一个用户的坐标信息，用JSON表达大概是这样的：
{"type":204,"roomId":"room_001","userId":"user_a","x":33.45,"y":67.89,"ts":1620134567890}这段文本将近100字节，但如果用二进制协议表达，同样的信息只需20字节左右。别小看这几十字节的差距，当房间里有100个人，每人每秒钟发送5次操作时，流量差距就非常可观了。更重要的是，在弱网环境下，包体越小意味着传输成功的概率越高。
所以第二版我们引入了protobuf，也就是Protocol Buffers，一种高效的二进制序列化协议。定义一个消息体大致是这样的：
message Frame { int32 type = 1; string room_id = 2; string user_id = 3; float x = 4; float y = 5; int64 ts = 6; }同样的数据用protobuf编码后，体积只有JSON的三分之一左右。这个升级带来的收益很直接：
- 带宽占用大幅下降：同样的带宽可以支撑更多的在线用户。
- 解析速度快：二进制协议不需要做字符串解析，CPU开销更低。
- 兼容性可控：protobuf天然支持字段的增删，升级协议时不会导致旧客户端崩掉。
从JSON切到protobuf不是没有成本，前端的js版本需要引入对应的解析库，后端的网关层也要做一次协议转换。但实测下来，这个切换是值得的。如果现在的你正在做类似的实时通信项目，一开始就直接上二进制协议，不要走JSON再切换的弯路，省下的重构时间比想象中多。
2.3 跨节点协同：Redis与消息队列的配合
单机版本跑通了只是第一步。真实业务不会只有一个WebSocket节点，一台服务器撑不住几千上万个长连接，必须横向扩展。这就引入了一个经典问题：用户A连接在节点1，用户B连接在节点2，A的操作如何同步给B？
有两个最朴素的方案：
方案一是直接在节点间建立长连接通道，每个节点连到其他所有节点，形成一个网状结构，消息在节点间转发。这个方案实现简单，但扩展性很差——节点从3个增加到10个，连接数会从3跳到45，随着集群规模扩大连接数会爆炸。
方案二是引入一个独立的消息中间件，节点收到消息后不是直接转发给目标节点，而是先发给中间件，中间件再按需推送给订阅了对应房间的其他节点。这个方案思路清晰，也是行业里的主流解法。
我们在方案二的基础上做了进一步简化：用Redis的Stream特性充当消息队列。不用Kafka的原因很简单——Apollo-11的体量根本用不上Kafka的百万级吞吐能力，多引入一个重度依赖意味着多一倍的运维成本。Redis本来就是系统里的基础设施，顺手承担消息路由的职责毫无压力。
消息流转大致是这样的：
- 节点1收到用户A的操作帧，解析校验后写入Redis Stream，消息带上房间号作为标识。
- 节点1同时把操作帧存入内存，同步给本节点上同一房间的其他用户。
- 节点2通过一个轻量级的消费线程，从Redis Stream中拉取属于自己节点用户所在房间的消息，再推送给客户端。
这套设计看起来简单，但细节里藏着一个非常重要的问题：消息至少需要投递一次，但重复投递会导致状态错乱吗？我们的解法是在消息帧里加上sequence序号，客户端按序号排序，重复的消息直接丢弃。这个序号就是所有客户端之间的"共同语言"。
2.4 为什么不用数据库存状态
有人会问，实时状态为什么不用数据库存？我们用Redis存状态，而不用MySQL或者MongoDB，核心原因就是读写的延迟和压力。一个用户操作引起状态变更，这个变更要在几十毫秒内广播给同房间所有人，而且这个操作可能每秒钟发生好多次。关系型数据库的每次写入都要走磁盘，这个延迟天然不适合高频写场景。
Redis是纯内存操作，单次读写延迟在亚毫秒级别，完全顶得住。再者，状态数据本身是临时性的——用户退出房间后，这条状态数据就没有价值了，留在内存里还能快速过期，不可能去占数据库的空间。
当然，纯内存方案也有风险。如果Redis崩溃，内存里的状态会全部丢失，各客户端的状态就不同步了。应对手段是定期做快照持久化，同时客户端本地缓存最近的操作记录，恢复连接后可以从断点续传。这两条防线保证了极端情况下也不至于全盘崩溃。
3. 实操过程：从零到一的六个关键步骤
3.1 搭建连接层与心跳保活
连接层是整个系统的门户，所有客户端先连到这里。连接层的主要职责包括：校验token、建立WebSocket长连接、维护连接状态表、处理心跳。
先说心跳的具体实现。我们用的是应用层心跳，也就是在WebSocket之上，由业务层定义一套心跳协议：客户端定时发送一个特殊的ping消息，服务端收到后回应pong消息。如果服务端在60秒内没有收到任何来自客户端的消息，就认为这个连接已经死掉了，主动断开，释放资源。
这里有一个容易踩的坑：WebSocket协议本身是有ping/pong帧的，所以在协议层做心跳是可行的。但实际操作中发现，HTTP代理、CDN等中间设备可能ping不通，应用层心跳反而更可控。我们最终选择了应用层心跳，并且把心跳和业务消息区分开，心跳帧的类型字段填的是固定值，解析时直接走心跳分支，不进入业务逻辑，减少不必要的处理开销。
3.2 消息协议设计：从JSON到protobuf的升级
消息协议的升级是整个项目中后期最伤筋动骨的一次改动。当初第一版直接用了JSON，一是开发速度快，二是调试方便。但上线两周后就发现问题：后台监控面板上，WebSocket的流量占到了总网络流量的40%以上，而实际业务请求量并没有那么夸张，罪魁祸首就是JSON的冗余字段。
换protobuf的时候留了个兼容方案：不直接断掉JSON，而是在消息头的type字段里增加一个protocol_type，客户端根据这个字段决定走JSON解析还是protobuf解析。这样新老客户端可以同时运行一段时间，等新版本覆盖到95%以上才彻底关掉JSON解析通道。
这里分享一个经验：协议升级一定要带兼容策略，不管是格式升级还是字段调整，别指望所有客户端一夜之间都更新完成，移动端和小程序的更新节奏参差不齐，如果强制切换，必然有人卡在登录页进不来。
3.3 状态一致性控制：版本号与冲突处理
共享体验最核心的难点就是状态一致。A在手机上画了一个圆，B在平板上同时画了一个方形，两个操作同时到达服务器，谁先谁后？如果处理不好，就会出现状态错乱。
Apollo-11选择的是中心化版本号方案，简单说就是：
- 每个房间维护一个全局自增版本号version。
- 任何客户端操作成功，服务端都会把version加1，然后连同最新状态一起广播。
- 客户端本地记录自己已经处理到的最新version。
- 收到新的广播帧时，比对version，如果相等说明是重复帧，丢弃；如果不相等，则更新本地状态。
这个方案在处理简单的顺序冲突时非常有效。对于复杂的同时编辑冲突，Apollo-11直接采用后写覆盖的策略——以服务端收到操作的时间为准，后到的操作覆盖先到的。业务方对这个限制是接受的，因为我们的共享场景不是文档协作，而是类似画板、互动播放器这样的场景，后写覆盖并不违背用户直觉。
如果是做多人文档或者实时表格，这个策略肯定不行，必须引入CRDT（换一种无冲突的数据类型）或者OT（操作变换）算法，那属于另一个量级的复杂度了。
3.4 权限与房间管理
权限模块看起来不起眼，但对共享体验来说，没有权限控制就等于是把家门钥匙贴在楼道里。
Apollo-11的房间权限分三层：
- 所有人可见：谁拿到链接都能进，只能观看，不能操作。适合直播观看、演示分享。
- 需要申请操作权限：进入后默认是观察者，要向房主申请操作权限，房主审批通过后才能操作。适合培训教学、远程协作。
- 密码保护：进入房间前需要输入密码，否则连观看都进不去。适合小范围内测、数据保密场景。
落地的难点不在权限策略本身，而在权限的实时撤销。比如房主把一个人的操作权限收回来了，但这个人正在发送一个移动指令，指令已经在半路上了。我们的方案是在服务端统一做权限校验，而不是依赖前端拦截——客户端发送的任何操作帧，服务端都会先查一下权限表，没有权限就直接拒绝，同时推送一个"权限已调整"的通知给该用户。前端隐藏按钮只能改善体验，不能代替后端的这道约束。
3.5 离线重连与断点续传
移动端网络稳定性永远是个玄学。地铁过隧道、电梯里、甚至人多时因为信号协商失败，WebSocket分分钟断开。Apollo-11做了两层保障。
第一层是指数退避重连：断开后，客户端按照1秒、2秒、4秒的间隔尝试重连，最多间隔30秒。如果连续重连失败5次，则提示用户"网络不稳定，请检查网络设置"，不再无休止地尝试，给用户一个明确的反馈。
第二层是断点续传。用户断开期间，服务端并不会立刻把它踢出房间，而是标记为"离线"，同时在Redis里缓存这个用户最后一次收到的消息序号。用户重连成功后，客户端会带上自己最近收到的一条消息序号，服务端把这个序号之后的消息重新推送给它，这样就补上了离线期间错过的状态。
断点续传用了一个比较抽象的设计思路，实际操作时并不复杂：本质就是让每个客户端都像一台录像机，服务端的广播帧都有编号，断开相当于录像暂停，重连相当于从缓存里继续播放。
3.6 前端落地：从埋点到渲染
前端工作是整个项目中"最不像技术"的部分，但恰恰是用户体感最直接的。Apollo-11的前端架构是：页面容器继承自一个统一的Room组件，Room组件内部负责和WebSocket网关通信，拿到状态数据后统一派发给各个子组件渲染。
这个设计有这样几个考虑：一是业务方不需要关心WebSocket细节，只需实现一个render方法，把状态渲染出来；二是方便做统一的埋点监控，连接状态、消息延迟、重连次数都集中在Room组件里上报，不需要每个业务方自己做统计。
前端的性能优化也有不少可以说的点。首屏加载时业务方经常传大量初始状态，一次性渲染几千个DOM节点很容易卡死页面。我们用了分批渲染策略：第一次只渲染可见区域的节点，其余节点在滚动时动态加载。这种延迟加载的思路，在共享画布、长列表、多维表格的场景下特别管用。
4. 实战中的坑与排查思路
4.1 断线重连风暴：一场凌晨三点的MySQL连接爆满
第一次遭遇大规模断线重连风暴，是上线后第三个星期的凌晨两点。运维告警群里突然炸了锅，数据库连接数直接打满，出现大量slow query。排查下来发现，不是数据库本身的问题，而是那天凌晨网络运营商做割接，全国有一部分用户的网络闪断，所有客户端在同一时间触发了重连逻辑。几千个用户同时重连，每个重连都要查询用户信息、创建房间上下文、拉取状态快照，数据库当然顶不住。
教训有两层。第一层是重连必须加随机抖动，即在指数退避的基础上，每次重连前加一个0到500毫秒之间的随机等待时间。这样的话，即使一万个人同时掉线，重连请求也不会排着队到达服务器。第二层是关键链路必须加缓存。用户基本信息和房间状态快照不应该每次重连都从数据库拉，而是缓存到Redis，重连时走缓存，数据库只做最终的兜底校验。经过这次事故之后，重连风暴再也没有出现过。
4.2 消息乱序：不是所有操作都按发送顺序到达
还有一次印象深刻的bug，是一个本该极简单的同步功能——用户A在画布上画了一个箭头，结果用户B经常看到箭头先出现，过一会儿才看到画箭头的轨迹。位置是对的，但动画时序是乱的。
问题出在WebSocket的消息不保证严格有序。虽然WebSocket协议本身按帧有序传输，但当多帧消息到达单个通道时，受网络缓冲和服务器处理并发的影响，不同用户的写操作可能被中间件以不同的顺序转发出去。A画的箭头分成了"开始画"和"画完"两帧，这两帧如果顺序颠倒，体验就完全不对。
解决办法分两侧进行。服务端在广播时给每条消息打上一个基于房间维度的自增序号；客户端维护一个小的接收队列，按序号处理消息，不连续的消息先存起来。这个改动并不复杂，但彻底解决了乱序问题。做实时系统，一定要在心里预设"消息会乱序、会重复、会迟到"，再针对这三种情况设计应对方案，而不是假定网络完美。
4.3 状态漂移：用户的屏幕和服务器对不上
状态漂移是多人实时系统里玄乎又最常见的问题。现象是：有的用户屏幕上显示的是旧状态，而其他用户看到的是新状态，服务器上的状态也是新的，只有那个用户的进程像定格了一样。
排查了很久才定位到原因：那个用户连接的是旧的WebSocket节点，而新消息被路由到了新的节点上。老的节点和新的节点之间，Redis Stream消费出现延迟，导致投递不到。这本质上是一个消费滞后问题。
解决手段是双管齐下。一方面给Redis Stream的消费组加上lag监控，当某个节点的消费积压超过阈值，主动把它标记为"不健康"，停止向它分配新连接，同时触发该节点上的客户端进行重连。另一方面，在客户端和服务端都维护一个状态哈希值，当状态更新时这个哈希会变化，如果发现服务端的哈希比客户端更新，客户端主动发起一次全量状态同步。这样即使滞后，最终也能收敛到一致。
4.4 常见问题速查表
整理一下Apollo-11开发和上线过程中遇到的高频问题，供各位参考。
| 问题 | 现象 | 根因 | 解决方案 |
|---|---|---|---|
| 连接闪断频繁 | 用户操作时提示"网络不稳定" | 心跳超时设置过短 | 心跳间隔调至30秒，超时调至60秒 |
| 消息延迟突增 | 操作后有1秒以上延迟 | Redis Stream消费堆积 | 增加消费线程并监控lag |
| 内存缓慢增长 | 节点运行几天后内存升高 | 房间上下文未及时释放 | 增加空闲房间的过期回收逻辑 |
| 弱网下消息丢失 | 用户短暂断网后状态缺失 | 重连后无补发机制 | 增加断点续传和消息缓存 |
| 高峰期CPU抖动 | 节点CPU使用率忽高忽低 | 大量JSON解析耗CPU | 切换protobuf，降低解析开销 |
| 白屏无法进入 | 进入房间后页面一直加载 | 初始状态数据量过大 | 分批渲染，加首屏加载进度 |
4.5 排查利器：全链路日志与状态埋点
最后说一个项目后期才补上的东西——全链路日志。早期排查问题基本上靠猜，前端报一个错误，后端报一个错误，两边日志对不上。后来做了一个统一的requestId机制，也就是从客户端发起一个操作帧开始，这个操作帧就携带一个唯一的requestId，网关收到后记录一条日志，转发到Redis Stream以及广播给其他节点时，日志里都带上同一个requestId。
这样一来，排查一次"用户B看不到用户A的操作"就可以直接把两个用户各自的requestId拉出来，从头到尾串一遍，看消息在哪一步断了。排查效率提升了不止一个数量级。实时系统的排错核心不是看代码，而是看链路。
5. 项目落地的长期收益与复盘
Apollo-11从立项到稳定运行，前后经历了大约五个月。这五个月的时间，投入的研发人力并不多，核心开发实际上只有三个人：一个人负责网关和通信层，一个人负责前端，一个人负责后端服务和数据层。可以说，这是一个小团队能完成的上限级别的项目了。
复盘这个项目，有几个决策值得单独拎出来讲。
第一，先搭骨、再填肉。项目启动第一周没有写任何业务代码，只做了两件事：搭好WebSocket网关的骨架，定义好消息协议的前三版。骨架和协议是这座建筑的地基，地基没打好，后面加再多的功能都会晃。节奏上我们狠狠心把这一步拉长了一周，后面证明是完全值得的。
第二，不要总想着一次到位。很多同学做技术选型时会纠结"这个方案天花板不够高"，然后选一个复杂度极高、学习成本极大的方案。Apollo-11用的都是非常成熟、没有"惊喜"的技术：WebSocket、Redis、protobuf。这些技术可能不够炫，但足够稳。对一个业务场景明确的项目来说，把八十分的技术用出九十分的效果，远比用九十分的技术做出八十分的效果要强。
第三，性能优化要放在流量进来之前。很多项目是上线后用户暴增才开始优化，那个阶段每慢一步都在流失用户。Apollo-11在上线前就做了一轮完整的压测，模拟了3000人同时在线的场景，发现WebSocket网关的线程模型有问题——同步阻塞式处理消息导致CPU利用率上不去。赶在上线前改成了基于事件循环的异步模型，才顶住了后面的真实流量。
第四，做共享体验项目，要始终记得"延迟是体验，数据是底线"。延迟影响的是用户爽不爽，数据的一致性和正确性影响的是用户信不信。宁可多花两倍的时间把状态同步和异常恢复做扎实，也不要为了看起来流畅而牺牲准确性。用户不会因为一次慢就卸载你的产品，但会因为一次"数据错了"而彻底失去信任。
这个项目做完之后，我们内部的技术栈里多了一个被反复复用的"共享能力模块"。后来的好几个新项目，甚至在立项之前就直接把这个模块接进去，省掉了大量重复造轮子的时间。回头看，当初取名为"Apollo-11"，有一点登月成功那样的里程碑意味——不是说技术有多难，而是我们把一件从零到一的事情完整地做成了，并且让它真正跑在了业务线上。这一点，比任何技术方案的完美都要实在。
