forked from longtao.wu/droboticflow
对象存储同步上传助手
状态:RFC 草案。D-01~D-07、D-16 已于 2026-07-28 决定;D-08 和第二轮实施参数仍待确认。
暂定产品名:
Drobodata LocalSync。名称本身也是待确认项。
1. 为什么单独建设这个工具
客户希望跳过网页里的“选择文件并上传”,在自己的电脑或采集工作站上,把本地文件和目录持续、批量地同步到 Drobodata 已配置的对象存储。
这不只是换一个上传入口。多个用户、设备或进程同时写同一 bucket/prefix 时,还必须解决:
- 同名对象被静默覆盖;
- “检查时没有冲突,真正上传时已经被别人修改”的竞态;
- 上传一半失败后的断点续传、重试与清理;
- 谁能写哪个目录、是否能覆盖/删除/发布;
- 不把 BOS AK/SK 下发给客户;
- 每次同步的操作者、设备、源文件、目标对象、结果和冲突可追溯。
因此本工具被定义为一个独立的“工具助手”,而不是网页目录上传功能的简单命令行包装。
2. 文档地图
| 文档 | 用途 |
|---|---|
| 00-current-state-and-gaps.md | 当前仓库已经支持什么、还缺什么,以及源码依据 |
| 01-product-requirements.md | 用户、场景、功能需求、非功能需求与非目标 |
| 02-architecture-design.md | 推荐架构、组件职责、数据流和信任边界 |
| 03-concurrency-and-conflicts.md | 多人并发、租约、版本检查、冲突类型与处理策略 |
| 04-security-permissions-and-audit.md | 凭据、最小权限、配额、审计、撤销与密钥治理 |
| 05-api-and-data-model.md | 拟新增 API、状态机、数据模型和幂等约定 |
| 06-client-config-and-operations.md | CLI、守护进程、托盘 GUI、配置、运维与故障处理 |
| 07-delivery-and-acceptance-plan.md | 分阶段实施、测试矩阵、验收证据与上线策略 |
| 08-owner-decisions.md | 已确认的决定、待确认事实和后续答复模板 |
| 09-rust-implementation-design.md | Rust workspace、crate 边界、并发、GUI、构建与测试设计 |
3. 已确认的首期产品基线
- 首期只做“本地到远端”的单向增量上传,不做双向同步。
- 多人可更新共享区域的原路径,但必须通过服务端同步会话、key 级租约、fencing token 和基线 ETag 校验。
- 本地删除不传播到远端;首期不开放远端删除。
- CLI、托盘 GUI 和后台守护进程同期提供,并共享同一个同步核心与本地状态库。
- 客户端只持有 Drobodata 签发的短权限同步令牌,不持有 BOS AK/SK。
- 权限采用集中管理:
admin管空间和令牌,data_operator上传,pipeline_engineer发布,compliance_auditor审计;强制覆盖/解锁仅限admin。 - 发生远端版本或活跃写入冲突时默认自动
keep-both:原对象不被覆盖,冲突副本 key 由服务端生成。 - 文件数据通过短期预签名 URL 直传 staging;控制面负责鉴权、计划、租约、提交和审计。
- 本地用 SQLite 保存文件指纹、上传分片和上次远端版本,支持断点续传与幂等重试。
- 本地同步助手使用 Rust;现有 Droboticflow 服务端同步 API 继续使用 Go 扩展。
4. 当前结论边界
- 本目录只完成需求与设计梳理,没有实现 API、客户端、数据库表或 UI。
- 文档中的
/api/external/object-sync/*均为拟议接口,当前仓库不存在。 - 当前系统支持的浏览器目录上传仍可继续使用,但不能当作多人并发安全同步协议。
- D-08 的 BOS 直写、版本控制和条件写事实仍为空白;在确认前,不能承诺能阻止绕过平台的写入竞态。
- 进入实现前还需完成 08-owner-decisions.md 中 D-08 和第二轮规模、平台、网络及保留策略。