数据同步

应用服务

数据同步

本页目录

按个人或组织空间存取应用数据: 多设备同步、团队共享、版本冲突检测、附件去重,可要求端到端加密 (服务端只存密文)。CZL Connect 不解析业务数据,只负责存储、版本控制与分发;冲突处理、加解密与本地库都在客户端,Go 客户端用公开 SDK github.com/woodchen-ink/go-web-utils/syncsdk 即可接入,不需要自己实现协议与密码学。

适用场景

  • 桌面端 / 移动端没有自己的服务端,要做「多设备同步」或「团队共享数据」
  • 数据敏感 (客户名单、价格),要求服务端与运维都看不到内容
  • 配合 组织 做团队版:组织成员共享一个空间,角色决定能否写入

开通条件

按应用所有者的套餐开放,额度为账户名下全部应用的同步存储合计 (文档 + 历史版本 + 附件):

套餐同步存储合计
Lite不支持
Plus20 GB
Pro200 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。

应用开通了 收款与权益 时,同步按订阅放行:个人空间要求本人有有效订阅,组织空间要求组织有有效订阅;没有订阅 (未购买、到期且过了宽限期、已退款) 时空间只读,同样回 40302。有效订阅的空间存储上限取套餐额度 quotas.syncStorageGB (GB,可为小数),未设置则用应用同步设置里的每空间配额。没开通收款的应用不看订阅。

鉴权与限流

所有接口在 https://connect.czl.net/api/sync/v1 下,用用户的 OAuth2 访问令牌鉴权 (Authorization: Bearer <access_token>,与 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含义
40001400请求格式不对 (invalid_body / invalid_op / invalid_batch / grant_for_non_member 等)
40002400payload 不是合法 JSON,或端到端加密应用收到非信封格式
40003400轮换空间密钥时没有覆盖全部已开通成员
40004400非加密应用的附件内容与 blobId 摘要不符
40101401令牌无效或过期
40301403不是该空间成员 (组织不存在也回这个)
40302403空间只读
40303403应用未开通数据同步
40304403账号已被封禁
40310403集合未登记 (逐条)
40311403角色低于集合的最低写入角色 (逐条)
40312403只追加集合不能修改或删除 (逐条)
40401404文档、附件、设备请求不存在;not_enrolled 表示未开通端到端加密
40901409文档版本冲突 (baseRev 不等于当前 rev),data 为当前文档
40902409状态冲突:公钥已存在、恢复码版本不符、空间密钥版本已被抢先、设备请求状态不对
41001410游标早于已清理的墓碑,需全量重拉
41301413单条超限 (payload_too_large)、空间配额 (space_quota_exceeded)、账户额度不足以新建空间 (account_quota_exceeded)、附件超过 32 MB
42901429请求过于频繁
50301503同步服务暂不可用

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}/eventsSSE:有新写入推 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 文档。集成测试可以先用 SDK 自带的进程内假服务端 syncsdk/synctest,它与本服务按同一份契约实现。

数据保存与清理

数据保留
文档长期保留,直到删除 (墓碑) 或空间清理
墓碑180 天
只追加集合应用设置,默认 365 天
历史版本每份文档最近 N 个
未引用附件引用校正标记后 30 天
只读空间只读满 90 天记录删除预告,再过 30 天可删除 (由 CZL Connect 管理员开启,默认不删)
新设备授权请求10 分钟
「正在编辑」60 秒

写入不逐条记日志,按 (空间, 日) 聚合写入次数与字节数;空间的创建与清理记入应用的操作日志。