给本地编辑器增加云空间，难点并不只是把文件上传到服务器。网络中断后文件是否还在，用户关闭自动保存后请求是否真的停止，账号过期后旧会话会不会继续写入，以及同一套业务逻辑在桌面与移动端能否保持一致，都会影响数据处理的可靠性。
本文以开源项目海豹办公（Seal Office）1.9.15 为案例，分析可选云同步的职责划分、传输适配、会话失效、待同步队列与测试方法。讨论基于项目当前实现，不依赖某一家云产品，也不将代码实现等同于安全审计或所有故障场景均已验证。
图1：海豹办公 1.9.15 的本地工作台。基础编辑与可选在线能力分别呈现，图片为实际界面，不代表所有文档格式均已完成验收。
先明确本地编辑与在线服务的边界
海豹办公提供文字、表格、演示文稿和 PDF 页面工具，基础编辑与本地保存不要求登录。账号和云空间属于可选能力：用户可以只处理本地文件，也可以在需要时启用在线文件管理。
这一区分应当落实到调用关系，而不是只写在产品介绍里。打开文档、编辑和本地保存不应因为云端暂时不可用而被替换成全局错误页；在线请求失败也不应被误报为本地保存失败。界面需要分别表达“本地已保存”“离线待同步”“云端已保存”和“版本冲突”等状态。
1.9.15 将云空间界面调整为文件浏览器，提供目录面包屑、搜索、网格与列表切换、排序、批量操作、历史版本和回收站。界面更清楚以后，底层仍然需要回答状态是否准确，不能把一个成功提示同时用于本地写入与远端提交。
在业务服务之外适配平台传输
桌面端可以直接使用 Node.js 的 HTTP 与 HTTPS 能力，移动端则需要通过平台适配层完成网络请求。若把上传、会话和错误处理在两端各写一遍，后续很容易出现“同一个错误码，两端处理结果不同”。
当前项目的云服务通过 createService 接受可选 transport。业务层组织请求与状态，适配层负责具体传输。移动端在 mobile/web/bridge.ts 中注入基于 platformFetch 的实现，同时保留 signal，使业务服务可以取消正在进行的请求。
桥接层有一个容易忽略的细节：从桌面请求头迁移到浏览器环境时，需要删除由浏览器管理的 Content-Length。直接复制桌面 HTTP 配置，不代表浏览器端就能按相同方式发送请求。
下面节选移动端传输适配中的取消与超时处理，省略正文编码和响应解析：
const controller = new AbortController()
const timer = setTimeout(() => controller.abort(), 30000)
const abort = () => controller.abort()
options.signal?.addEventListener('abort', abort, {
once: true })
try {
if (options.signal?.aborted) controller.abort()
// 请求使用 controller.signal，正文与响应按调用类型处理。
} finally {
clearTimeout(timer)
options.signal?.removeEventListener('abort', abort)
}
这里同时存在外部取消和本地超时两个入口。finally 中清理计时器与监听器，避免请求已经结束后仍留下无用回调。错误还需要携带业务可以识别的状态码，不能把所有非成功响应都折叠成一条没有上下文的字符串。
会话失效不是只把登录按钮改成未登录
在当前自定义传输路径中，收到 401 后，服务会清除 token、根密钥状态与账号状态，增加会话代次，取消活动请求，并持久化失效状态。下次重新创建服务时，也应读取到未登录状态，而不是从本地安全记录中恢复一个已经失效的账号。
其中，代次可以理解为当前会话的一次版本标记。请求开始时记住自己的代次；完成时如果发现代次已经变化，就不能继续把旧结果应用到新状态。它用于减少退出、切换和取消期间的竞态，并不取代服务端鉴权或数据库并发控制。
对前端交互来说，401 提示应指向重新登录，而不能仅提供“刷新文件列表”。刷新并不能修复失效的身份；反复重试还可能掩盖真正的问题。
关闭自动保存要有可观察的取消结果
“关闭自动保存”如果只是修改界面的开关，后台仍可能继续上传已经排队的请求。当前服务使用活动请求集合与取消信号，在关闭自动保存时更新状态、增加代次并中止相关活动传输。
移动端适配层必须继续传递这一取消语义。如果业务层有 AbortSignal，而平台传输忽略了它，那么接口形式上相同，实际行为仍然不一致。
仓库 main/cloud/service.transport.test.js 中有两项直接相关的测试：一项检查 401 后清除账号，并且重新创建服务仍保持失效状态；另一项让请求停留在进行中，关闭自动保存后检查 signal 已被中止。它们验证的是状态与取消行为，不代表已经完成全部网络、设备或安全场景的测试。
用待同步队列承接网络失败
对于文档编辑工具，保存请求失败后最重要的问题是内容有没有丢失。当前实现先把待上传内容加密写入本地文件，再持久化队列记录，将状态标记为离线待同步，然后尝试发送。
写队列文件时采用临时文件、写入、fsync 和重命名的流程，以减少直接覆盖文件造成的不完整记录。这个流程改善的是写入过程，并不能让磁盘故障、设备丢失或人为删除消失，重要资料仍需要独立备份。
同步过程保留上传标识、偏移与预期版本，服务端提交成功后再更新版本与摘要。当同一个文档又产生新版本时，还需要区分正在发送的内容和最新队列内容，避免旧请求完成后误删新数据。
以下状态应分开显示与处理：
| 条件 | 当前实现中的处理重点 | 界面不能误报为什么 |
|---|---|---|
| 连接失败或超时 | 保留待同步内容，明确本地与远端的不同状态 | 云端已保存 |
| 401 会话失效 | 清理账号和密钥状态，要求重新登录 | 普通目录刷新失败 |
| 409 版本冲突 | 保留冲突状态，避免自动按成功处理 | 已覆盖为最新版本 |
| 413 空间不足 | 显示空间不足，保留后续处理路径 | 网络稍后自然恢复 |
版本冲突、空间不足和网络断开具有不同的恢复条件。为它们统一增加一个“重试”按钮，并不能形成完整的恢复策略。
说明加密实现 也说明它不能证明什么
当前项目的云文件加密封装使用 AES-256-GCM，每次调用生成 12 字节随机 IV，并通过附加认证数据区分上下文。元数据、文件密钥和文件内容在代码中使用不同的上下文字符串；桌面会话持久化依赖系统安全存储接口。
这些是实现事实，不是“绝对安全”或“无需审计”的结论。生产部署仍需评估密钥生命周期、恢复流程、访问控制、日志、备份与依赖更新。公开问题反馈和截图中也不应出现 token、恢复密钥或真实业务文件。
用户没有启用云空间时，不能把文档自动送入上传流程。智能助手同样属于独立可选网络能力，使用用户配置的模型地址与密钥，主动调用时会向对应服务商发送完成请求所需内容。将所有功能统称为“完全离线”，反而会使数据去向变得不清楚。
如何测试 而不是只测试成功上传
建议把测试拆成服务层、平台适配层和最终应用三部分。服务层用可控 transport 制造 401、超时、取消和冲突；适配层检查错误状态、二进制与 JSON 响应、signal 传递及资源清理；最终应用再执行登录、离线保存、恢复网络和切换页面等用户路径。
测试用例应当明确观察什么：不只是 Promise 是否结束，还包括账号是否被清除、请求是否中止、队列文件是否保留、版本是否更新，以及重新创建服务后状态是否一致。测试替身也不能用于证明真实系统安全存储或真实设备网络的行为。
界面截图适合解释入口与登录层级，但不能单独证明云同步正确。代码、状态断言、包内资源核对与目标设备验收，需要分别回答各自的问题。
复用这套思路时的检查清单
先画清本地保存与云提交的边界，再为请求定义可取消的传输接口；明确哪些状态可以重试，哪些需要用户处理；将队列写入、远端提交与版本更新分开观察；最后在生产构建与目标设备中验证。
本案例的实现并不是可直接复制到所有业务中的通用同步协议。多人协同编辑、严格事务一致性、大文件分片校验和企业级灾备，会提出不同要求，不能因为具备文件版本与待同步队列，就推导出这些能力已经全部存在。
案例源码
本文为基于海豹办公 1.9.15 源码的技术复盘，使用 AI 辅助整理文字。项目按 MIT 许可证开放，依赖组件与第三方服务按各自条款使用。
