# 数据同步 按个人或组织空间存取应用数据: 多设备同步、团队共享、版本冲突检测、附件去重,可要求端到端加密 (服务端只存密文)。CZL Connect 不解析业务数据,只负责存储、版本控制与分发;冲突处理、加解密与本地库都在客户端,Go 客户端用公开 SDK [`github.com/woodchen-ink/go-web-utils/syncsdk`](https://go-web-utils.czl.net/docs/syncsdk) 即可接入,不需要自己实现协议与密码学。 ## 适用场景 - 桌面端 / 移动端没有自己的服务端,要做「多设备同步」或「团队共享数据」 - 数据敏感 (客户名单、价格),要求服务端与运维都看不到内容 - 配合 [组织](/docs/orgs) 做团队版:组织成员共享一个空间,角色决定能否写入 ## 开通条件 按应用所有者的套餐开放,额度为账户名下全部应用的同步存储合计 (文档 + 历史版本 + 附件): | 套餐 | 同步存储合计 | |---|---| | Lite | 不支持 | | Plus | 20 GB | | Pro | 200 GB | | Enterprise | 不限 | 超出后拒绝新建空间,已有空间写入照常。套餐降到 Lite 后空间转只读 (可拉取、可下载附件),数据不删除。 ## 应用中开通 进入应用详情 → **数据同步** (仅应用所有者可改): | 设置 | 说明 | |---|---| | 开通数据同步 | 关闭后同步接口拒绝访问,已存数据保留,重新开通即恢复 | | 端到端加密 | `off`:服务端用按空间派生的密钥加密存储;`required`:只接受客户端加密后的信封,附件标识不是明文摘要。**开启后不能关闭** | | 集合 | 登记集合名 (小写字母、数字、`-`、`_`,最多 50 个)、最低写入角色 (默认 `member`)、是否只追加、保留的历史版本数 (0 ~ 20)。集合名须与客户端代码一致;未登记的集合拒绝写入,改名或取消登记后客户端写不进去,已存文档保留且照常可拉取 | | 单条文档上限 | 默认且最大 1 MB,可调低 | | 每个空间的存储 / 文档数 | 0 为不限 (仍受账户合计额度约束) | | 只追加集合保留天数 | 默认且最大 365 天,可调低 | 同一页显示空间数、文档数、附件数、本应用存储 (其中附件占用)、近 30 天写入次数,以及账户合计用量。 ## 概念 - **空间**:个人空间 `me` (每个用户在每个应用一个) 或组织空间 (路径用组织公开标识)。用户能访问自己的个人空间与所在组织的空间 - **集合**:应用登记的名字,如 `shipments`、`contacts`。服务端可见,不要放业务信息 - **文档**:(空间, 集合, 文档 id) 唯一,`payload` 为不透明 JSON。文档 id 1 ~ 200 字节,不含 `/ \ ? #` 与控制字符,同样服务端可见 - **序号**:每个空间一条单调递增序列,文档的 `rev` 是最后一次写入的序号,拉取游标也是序号 - **修改人**:每份文档的 `updatedBy` (用户在本应用的标识,与 OIDC `sub` 相同) 与 `updatedAt` 由服务端按令牌写入,在密文之外下发;展示「谁改的」只认这两个字段 ## 角色与只读 | 角色 | 同步权限 | |---|---| | 个人空间本人 | 视为 `owner` | | `owner` / `admin` | 读写;端到端加密时负责为新成员封装空间密钥、成员移除后轮换 | | `member` | 读写 (受集合最低写入角色约束) | | `viewer` | 只读 | 组织只读 (所有者被封禁等)、套餐不支持同步时,空间只能拉取与下载附件,写入整个请求回 `403 40302 space_readonly`。 应用开通了 [收款与权益](/docs/app-billing) 时,同步按订阅放行:个人空间要求本人有有效订阅,组织空间要求组织有有效订阅;没有订阅 (未购买、到期且过了宽限期、已退款) 时空间只读,同样回 `40302`。有效订阅的空间存储上限取套餐额度 `quotas.syncStorageGB` (GB,可为小数),未设置则用应用同步设置里的每空间配额。没开通收款的应用不看订阅。 ## 鉴权与限流 所有接口在 `https://connect.czl.net/api/sync/v1` 下,用用户的 OAuth2 访问令牌鉴权 (`Authorization: Bearer `,与 [OAuth2](/docs/oauth2) 授权得到的令牌相同);空间只在令牌所属应用内解析。令牌无效回 `401 40101`,SDK 会刷新令牌后重试一次。 限流按 (用户, 空间) 分桶,每分钟 600 次,超限回 `429 42901` 并带 `Retry-After`。 ## 响应格式 成功为 HTTP 200 + `{"code": 200, "data": ..., "msg": "success"}`。失败为对应 HTTP 状态 + 业务码 + snake_case 英文短语,`409` 时 `data` 附服务端当前文档或记录: ```json {"code": 40901, "data": {"collection": "shipments", "id": "s1", "rev": 12, "deleted": false, "payload": {...}, "updatedBy": "...", "updatedAt": "2026-11-20T08:00:00.123Z"}, "msg": "version_conflict"} ``` | 业务码 | HTTP | 含义 | |---|---|---| | `40001` | 400 | 请求格式不对 (`invalid_body` / `invalid_op` / `invalid_batch` / `grant_for_non_member` 等) | | `40002` | 400 | payload 不是合法 JSON,或端到端加密应用收到非信封格式 | | `40003` | 400 | 轮换空间密钥时没有覆盖全部已开通成员 | | `40004` | 400 | 非加密应用的附件内容与 `blobId` 摘要不符 | | `40101` | 401 | 令牌无效或过期 | | `40301` | 403 | 不是该空间成员 (组织不存在也回这个) | | `40302` | 403 | 空间只读 | | `40303` | 403 | 应用未开通数据同步 | | `40304` | 403 | 账号已被封禁 | | `40310` | 403 | 集合未登记 (逐条) | | `40311` | 403 | 角色低于集合的最低写入角色 (逐条) | | `40312` | 403 | 只追加集合不能修改或删除 (逐条) | | `40401` | 404 | 文档、附件、设备请求不存在;`not_enrolled` 表示未开通端到端加密 | | `40901` | 409 | 文档版本冲突 (`baseRev` 不等于当前 `rev`),`data` 为当前文档 | | `40902` | 409 | 状态冲突:公钥已存在、恢复码版本不符、空间密钥版本已被抢先、设备请求状态不对 | | `41001` | 410 | 游标早于已清理的墓碑,需全量重拉 | | `41301` | 413 | 单条超限 (`payload_too_large`)、空间配额 (`space_quota_exceeded`)、账户额度不足以新建空间 (`account_quota_exceeded`)、附件超过 32 MB | | `42901` | 429 | 请求过于频繁 | | `50301` | 503 | 同步服务暂不可用 | `403` / `413` 出现在 batch 的逐条结果里时只影响该条;作为整个请求的响应时 (空间只读、非成员、新建空间超额度) 客户端应保留本地修改,稍后重试。 ## 接口 | 方法与路径 | 说明 | |---|---| | `GET /spaces` | 可访问的空间:`id`、`type`、`name` (组织名)、`role`、`readonly`、`e2e`、`seq`、`quota`、`usage` | | `GET /spaces/{space}/changes?since=&limit=` | `rev > since` 的文档 (含墓碑),按 `rev` 升序,`limit` 上限 500;返回 `docs`、`cursor` (下次的 `since`)、`hasMore` 与 `presence` (他人与本人其他设备,见「规则 · 正在编辑」) | | `PUT /spaces/{space}/docs/{collection}/{id}` | 请求体 `{"baseRev": 0, "payload": {...}}`,新建时 `baseRev` 为 0;成功返回写入后的元数据 (不带 payload) | | `DELETE /spaces/{space}/docs/{collection}/{id}?baseRev=` | 写墓碑,规则同 `PUT` | | `POST /spaces/{space}/batch` | `{"ops": [{"op": "put" \| "delete", "collection", "id", "baseRev", "payload"}]}`,最多 100 条,返回与请求一一对应的 `results` (`status`、`code`、`msg`、`doc`),不保证原子 | | `GET /spaces/{space}/docs/{collection}/{id}/revisions` | 开启了历史版本的集合里一份文档的历史,新的在前 | | `HEAD /spaces/{space}/blobs/{blobId}` | 附件是否存在 (200 / 404),用于上传前去重 | | `PUT /spaces/{space}/blobs/{blobId}` | 上传附件 (请求体为原始字节,最大 32 MB),幂等,已存在不覆盖 | | `GET /spaces/{space}/blobs/{blobId}` | 302 到 5 分钟有效的预签名下载地址 | | `PUT /spaces/{space}/blob-refs` | 可选的引用校正:`{"blobIds": [...]}` 上报空间里仍被引用的全部附件 (owner / admin),其余标记为未引用,30 天后删除。不调用则附件不会被清理 | | `GET /spaces/{space}/events` | SSE:有新写入推 `event: changed` + `{"seq": n}`,他人编辑状态变化推 `event: presence` + `{"presence": [...]}`;`Last-Event-ID` 小于当前序号时连上即补发一条 `changed`;每 25 秒一行注释心跳 | | `PUT /spaces/{space}/presence/{collection}/{id}` | 「正在编辑」心跳,60 秒过期 | | `GET / PUT /keys/me` | 本人公钥与私钥加密副本 (端到端加密) | | `GET /spaces/{space}/keys` | 本人在该空间各版本的封装密钥、待授予成员、全部已开通成员、是否需要轮换 | | `PUT /spaces/{space}/keys/{version}` | owner / admin 提交封装密钥:`rotate: true` 建立新版本 (须为当前版本 + 1,覆盖全部已开通成员),否则给已有版本补授 | | `POST /devices/requests` | 新设备发起授权请求 (见下文「端到端加密」) | | `GET /devices/requests` | 已有设备列出本人待处理的授权请求 | | `GET / DELETE /devices/requests/{id}` | 查询一条授权请求的状态 / 拒绝或撤回 | | `POST /devices/requests/{id}/{step}` | 推进授权,`step` 为 `challenge` / `reveal` / `approve` / `claim` | ## 规则 - **写入校验顺序**:令牌 → 空间权限 (成员、只读、权益) → 集合登记与最低写入角色 → 单条大小与格式 → 配额 → 版本 - **版本冲突**:`baseRev` 与服务端当前 `rev` 不同回 `409` 并附当前文档,由客户端决定覆盖、保留服务端版本或另存副本。重试时发现服务端内容就是自己上次发出的 (应答丢失),SDK 视为成功 - **墓碑与游标**:删除写墓碑,墓碑保留 180 天后清理;游标早于已清理墓碑的 `changes` 回 `410`,客户端清空本地副本后从 0 重拉 - **只追加集合**:只能新建 (`baseRev` 为 0),修改、删除都回 `403 40312`。适合操作记录:记录内容照常加密,操作人与时间以服务端的 `updatedBy` / `updatedAt` 为准,成员无法冒充他人或抹掉记录。超过保留天数后由服务端清理 - **历史版本**:集合开启后,每次覆盖或删除前把旧版本存为历史,保留最近 N 个,计入存储。调小 N 时多出的旧版本在该文档下次写入时清掉;改为 0 后不再新增,已有历史保留。找回某个版本由客户端完成:读 `revisions` 拿到旧 `payload`,按普通写入 `PUT` 回去 (生成新的 `rev`,当前内容同时进历史) - **正在编辑 (presence)**:按设备区分。客户端每个请求带 `X-Sync-Device` (本机稳定的设备标识,1~64 位字母、数字、`-` `_` `.`,每台设备生成一次存在本机,不随配置同步) 与可选的 `X-Sync-Device-Name` (设备显示名,UTF-8 百分号编码,最多 64 字);presence 记录为 `{collection, id, userId, deviceId, deviceName, expiresAt}`,`changes` 与 SSE 下发时只排除调用方本设备,同一账号在另一台设备上打开同一份文档也能看到 (个人空间据此提示「另一台设备正在使用」)。不带 `X-Sync-Device` 的老客户端仍按账号排除,看不到自己的任何设备;设备标识格式不对按未带处理 - **非加密应用**:payload 由服务端按空间密钥 AES-GCM 加密后落库,读取时解密下发;键顺序与空白可能被规整,客户端不要依赖字节级一致 ## 附件 - `blobId` 为 64 位小写十六进制:非加密应用为明文 SHA-256 (服务端校验),端到端加密应用为 HMAC-SHA256 (附件标识密钥按空间,同空间可去重但服务端看不到明文摘要),内容为分块密文 - 附件引用由应用自己写进文档 payload,服务端不解析 - 附件大小计入空间与账户存储;下载经 302 跳到对象存储,`Authorization` 头不会被带过去 ## 端到端加密 应用设为 `required` 后,服务端只保存: | 内容 | 说明 | |---|---| | 用户公钥 (X25519) 与私钥加密副本 | `PUT /keys/me`:首次 `recoveryVersion` 为 1;重置恢复码时公钥不变、版本加 1;版本不符或公钥已存在回 `409 40902` | | 空间密钥的封装副本 | 用各成员公钥封装,按 (空间, 版本, 成员) 存 | | 文档信封 | `{"v":1,"kv":<密钥版本>,"nonce":"...","ct":"..."}`,服务端只校验格式 | - **新成员**:接受组织邀请并开通后出现在 `pending`,任一 owner / admin 的客户端同步时自动为其封装,授予前能看到空间但读不到内容 - **移除成员**:服务端删除其封装副本并标记 `rotationRequired`,下一个在线的 owner / admin 客户端轮换出新版本;被移除者本机已有的副本无法收回 - **新设备**:输入恢复码解开私钥副本;或由已登录设备批准:新设备 `POST /devices/requests` (临时公钥 + 承诺) → 已有设备 `challenge` (nonce) → 新设备 `reveal` (nonce) → 两端显示同一个 6 位码 → 已有设备 `approve` (封装给临时公钥的私钥) → 新设备 `claim`。请求 10 分钟过期,各值只能写一次,任一方 `DELETE` 即拒绝 / 撤回。经批准获得密钥、重置恢复码时本人会收到通知中心的安全通知 - **不可恢复**:用户丢失全部设备且没有恢复码时个人空间无法恢复;CZL Connect 客服无法代为恢复,开通时务必让用户保存恢复码 ## Go SDK ```go import "github.com/woodchen-ink/go-web-utils/syncsdk" client, _ := syncsdk.NewClient(syncsdk.ClientOptions{ BaseURL: "https://connect.czl.net/api/sync/v1", Tokens: tokens, // 实现 Token(ctx), 可选 InvalidateToken (401 时刷新) // 本机设备标识 (存数据目录, 不随配置同步), presence 按设备区分; 显示名可选 DeviceID: deviceID, // syncsdk.LoadOrCreateDeviceID(filepath.Join(dataDir, "device-id")) DeviceName: "办公室台式机", }) keys, _ := syncsdk.NewKeyManager(client, keyStore, syncsdk.KeyManagerOptions{Namespace: "myapp/" + userID}) engine, _ := syncsdk.NewEngine(syncsdk.EngineOptions{ Client: client, Keys: keys, // 未开启端到端加密时 Keys 传 nil Outbox: outbox, Cursors: cursors, Applier: localDB, Resolver: resolver, AppendOnly: []string{"activity"}, BlobCacheDir: blobCacheDir, }) _ = engine.Save(ctx, "me", "shipments", id, row.Rev, payload) // 断网照常入队 go engine.Subscribe(ctx, "me", syncsdk.SubscribeOptions{}) // SSE + 回退轮询, 持续同步 ``` 应用需要实现持久化出站队列、游标存储、本机密钥库 (Windows DPAPI / macOS 钥匙串)、`Applier` (把变更落到本地库) 与冲突回调。开通、恢复码、设备授权、成员授予与轮换的完整流程见 [SDK 文档](https://go-web-utils.czl.net/docs/syncsdk)。集成测试可以先用 SDK 自带的进程内假服务端 `syncsdk/synctest`,它与本服务按同一份契约实现。 ## 数据保存与清理 | 数据 | 保留 | |---|---| | 文档 | 长期保留,直到删除 (墓碑) 或空间清理 | | 墓碑 | 180 天 | | 只追加集合 | 应用设置,默认 365 天 | | 历史版本 | 每份文档最近 N 个 | | 未引用附件 | 引用校正标记后 30 天 | | 只读空间 | 只读满 90 天记录删除预告,再过 30 天可删除 (由 CZL Connect 管理员开启,默认不删) | | 新设备授权请求 | 10 分钟 | | 「正在编辑」 | 60 秒 | 写入不逐条记日志,按 (空间, 日) 聚合写入次数与字节数;空间的创建与清理记入应用的操作日志。