droboticflow-new/docs/tool-assistants/object-storage-sync-uploader

对象存储同步上传助手

状态: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. 已确认的首期产品基线

  1. 首期只做“本地到远端”的单向增量上传,不做双向同步。
  2. 多人可更新共享区域的原路径,但必须通过服务端同步会话、key 级租约、fencing token 和基线 ETag 校验。
  3. 本地删除不传播到远端;首期不开放远端删除。
  4. CLI、托盘 GUI 和后台守护进程同期提供,并共享同一个同步核心与本地状态库。
  5. 客户端只持有 Drobodata 签发的短权限同步令牌,不持有 BOS AK/SK。
  6. 权限采用集中管理:admin 管空间和令牌,data_operator 上传,pipeline_engineer 发布,compliance_auditor 审计;强制覆盖/解锁仅限 admin。
  7. 发生远端版本或活跃写入冲突时默认自动 keep-both:原对象不被覆盖,冲突副本 key 由服务端生成。
  8. 文件数据通过短期预签名 URL 直传 staging;控制面负责鉴权、计划、租约、提交和审计。
  9. 本地用 SQLite 保存文件指纹、上传分片和上次远端版本,支持断点续传与幂等重试。
  10. 本地同步助手使用 Rust;现有 Droboticflow 服务端同步 API 继续使用 Go 扩展。

4. 当前结论边界

  • 本目录只完成需求与设计梳理,没有实现 API、客户端、数据库表或 UI。
  • 文档中的 /api/external/object-sync/* 均为拟议接口,当前仓库不存在。
  • 当前系统支持的浏览器目录上传仍可继续使用,但不能当作多人并发安全同步协议。
  • D-08 的 BOS 直写、版本控制和条件写事实仍为空白;在确认前,不能承诺能阻止绕过平台的写入竞态。
  • 进入实现前还需完成 08-owner-decisions.md 中 D-08 和第二轮规模、平台、网络及保留策略。