fix(sync): 强化 S-05 上传持久性

2026-09-09 12:53:43 +08:00
parent 0890cabf3b
commit 0c82f1f78e
7 changed files with 901 additions and 49 deletions
@@ -1,6 +1,6 @@
 # Sync Protocol v1

-状态：服务端协议原型已实现，生产运维与桌面客户端尚未验收。入口为 `server sync/sync_server`；运行时 `/openapi.json` 是字段约束来源。不能将 SQLite Fixture 结果称为 PostgreSQL / MinIO 验收。
+状态：服务端协议已实现，PostgreSQL 17、MinIO 与双 Worker 的 S-04 生产并发验收已通过；其余服务运维门和发布端到端验收仍在推进。入口为 `server sync/sync_server`；运行时 `/openapi.json` 是字段约束来源。SQLite Fixture 只用于协议回归，不能代替生产依赖验收。

 ## Rust 上传客户端增量

@@ -40,7 +40,7 @@ Workspace schema 4 增加持久 inbox、分页 boundary 和冲突记录，并为
 | GET `/vaults/{id}/history/{file_id}` | before/limit 倒序历史 |
 | GET `/vaults/{id}/objects/{hash}` | 经鉴权读取与摘要复核 |

-上传分块最大 1 MiB，对象最大 100 MiB。offset 冲突为 409 `UPLOAD_OFFSET`，响应给出已确认偏移；客户端查询偏移后续传。完成请求响应丢失时重新预申请同一摘要即可确认对象已存在。未完成上传不允许提交 Revision。
+上传分块最大 1 MiB，对象最大 100 MiB。offset 冲突为 409 `UPLOAD_OFFSET`，响应给出已确认偏移；客户端查询偏移后续传。暂存文件长于数据库 offset 时先截断并 `fsync`，短于 offset 或无法读取时删除损坏上传并释放预留，再返回 409 `UPLOAD_DAMAGED` 与 `restart_required=true`。完成请求响应丢失时用同一 upload ID 重试，持久回执返回原摘要且不会重复计费；重新预申请同一摘要也会确认对象已存在。未完成上传不允许提交 Revision。

 提交字段：operation_id、file_id、base_revision、path、operation (`put`/`delete`)、content_hash、size。device_id 从会话取得，客户端不能冒充。移动使用同一 file_id、新 path 及当前对象；恢复历史使用历史摘要、新 operation_id 和当前 base_revision，生成新 Revision。删除必须携带当前基线、空摘要和 size=0。

@@ -50,7 +50,7 @@ Vault 行锁内执行幂等键验证、CAS、路径检查、序列分配及历

 ## 保留与未交付边界

-当前历史和 tombstone **永久保留**，游标不主动过期；不启用 GC，以免缺少恢复演练时删除历史对象。配额包含全部历史对象，未完成上传预留额度。通知尚未实现，客户端必须主动按 cursor 拉取。上传过期清理、对象 GC、限速指标、完整备份恢复工具与生产负载验收仍未交付。`/ready` 目前只检查数据库 schema，不证明 S3 就绪。
+当前历史和 tombstone **永久保留**，游标不主动过期；不启用对象 GC，以免缺少恢复演练时删除历史对象。配额包含全部历史对象与未完成上传的预留额度。每个 Worker 每 60 秒清理已过期上传；清理与 PUT/complete 使用相同 Vault 行锁顺序，先删除暂存文件再删除预留记录，失败可在下一轮重试。通知尚未实现，客户端必须主动按 cursor 拉取。对象 GC、限速指标、完整备份恢复工具与生产负载验收仍未交付。`/ready` 会在受控缓存周期内检查数据库 schema、暂存目录写入/`fsync`/读回及 S3 临时对象写入/读回/删除，任一依赖异常返回 503。

 验证向量见 `server sync/tests/test_protocol.py`：双设备 CAS、幂等重放、移动与删除、历史恢复、稳定分页、隔离、撤销、刷新、配额、路径冲突、摘要与断点。

@@ -24,4 +24,4 @@ python scripts/phase3-production-acceptance.py `

 报告目录包含 `summary.json`、`case-manifest.json`、`junit.xml`、`cases/<ID>.json` 和脱敏的 `logs/<ID>.log`。摘要记录 commit、各锁文件 SHA-256、配置摘要与已提供安装产物摘要。日志将仓库、数据根、报告根、用户主目录和配置声明的秘密值替换为占位符，并限制为 10 MiB。报告目录必须为空，避免单例复跑覆盖原始证据。

-当前 runner 与失败闭合行为已实现，A-02/A-03 Sidecar、B-01/B-02 凭据、D-01 扩展包、S-01/S-02/S-03/S-08 Sync 客户端以及 S-04 Sync 服务 driver 已登记；其余 20 个生产验收 ID 尚未登记，运行时会生成 `NOT_IMPLEMENTED` 证据并退出 1。这用于阻止误报，不是这些用例的验收通过。
+当前 runner 与失败闭合行为已实现，A-02/A-03 Sidecar、B-01/B-02 凭据、D-01 扩展包、S-01/S-02/S-03/S-08 Sync 客户端以及 S-04/S-05 Sync 服务 driver 已登记；其余 19 个生产验收 ID 尚未登记，运行时会生成 `NOT_IMPLEMENTED` 证据并退出 1。这用于阻止误报，不是这些用例的验收通过。