应用服务
数据同步
按个人或组织空间存取应用数据: 多设备同步、团队共享、版本冲突检测、附件去重,可要求端到端加密 (服务端只存密文)。CZL Connect 不解析业务数据,只负责存储、版本控制与分发;冲突处理、加解密与本地库都在客户端,Go 客户端用公开 SDK github.com/woodchen-ink/go-web-utils/syncsdk 即可接入,不需要自己实现协议与密码学。
适用场景
- 桌面端 / 移动端没有自己的服务端,要做「多设备同步」或「团队共享数据」
- 数据敏感 (客户名单、价格),要求服务端与运维都看不到内容
- 配合 组织 做团队版:组织成员共享一个空间,角色决定能否写入
开通条件
按应用所有者的套餐开放,额度为账户名下全部应用的同步存储合计 (文档 + 历史版本 + 附件):
| 套餐 | 同步存储合计 |
|---|---|
| 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(用户在本应用的标识,与 OIDCsub相同) 与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 附服务端当前文档或记录:
{"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
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 秒 |
写入不逐条记日志,按 (空间, 日) 聚合写入次数与字节数;空间的创建与清理记入应用的操作日志。