📝 Define Rust sync client architecture

This commit is contained in:
eust-w 2026-07-28 17:23:15 +08:00
parent b8d9a469a5
commit aacf075400
6 changed files with 266 additions and 4 deletions

View File

@ -225,6 +225,7 @@ incoming/customer-a/dataset-x/camera-01/000001.mcap
### 客户端
- 客户端使用 Rust workspace 实现;
- CLI、daemon 与托盘 GUI 同期交付;
- 三种入口共享同一个同步核心库;
- CLI/daemon 优先提供单一静态二进制,GUI 作为薄交互壳;
@ -232,3 +233,5 @@ incoming/customer-a/dataset-x/camera-01/000001.mcap
- 配置与状态分离;
- 支持无管理员权限安装或便携模式;
- 制品签名、SHA-256、SBOM 和版本升级通道纳入交付。
具体 crate 和并发边界见 [09-rust-implementation-design.md](09-rust-implementation-design.md)。

View File

@ -1,5 +1,7 @@
# 客户端配置与运维
客户端使用 Rust 实现。CLI、daemon、托盘 GUI、本地状态和传输逻辑位于同一个 Rust workspace;GUI 是共享核心的薄交互壳。详见 [09-rust-implementation-design.md](09-rust-implementation-design.md)。
## 1. 建议命令
```text

View File

@ -6,7 +6,7 @@
输出:
- 固化已完成的 D-01~D-07 决策,并补齐 D-08;
- 固化已完成的 D-01~D-07、D-16 决策,并补齐 D-08;
- 确认 BOS 对条件写、版本控制、multipart ETag 和 server-side copy 的实际语义;
- 用两个并发客户端验证 lease + version check 原型;
- 确认客户目标 OS、规模、网络和是否有平台外写入者;
@ -176,7 +176,10 @@
### 代码
- Go 单元/集成测试;
- 客户端单元/集成测试;
- `cargo fmt --all -- --check`;
- `cargo clippy --workspace --all-targets -- -D warnings`;
- `cargo test --workspace` 和 Rust 客户端集成测试;
- Rust/Go protocol JSON fixture 合同测试;
- race detector 覆盖 lease/并发核心;
- lint、format、build;
- API schema/contract test;

View File

@ -1,6 +1,6 @@
# 负责人决策记录与待确认清单
> D-01~D-07 已由负责人于 2026-07-28 决定。D-08 未提供事实,保持待确认;空白不解释为“否”。
> D-01~D-07、D-16 已于 2026-07-28 决定。D-08 未提供事实,保持待确认;空白不解释为“否”。
## 1. 第一轮决策结果
@ -14,6 +14,7 @@
| D-06 | A:集中权限管理 |
| D-07 | B:发生冲突时自动 keep-both |
| D-08 | **待确认**:BOS 直写者、版本控制和条件写事实未提供 |
| D-16 | Rust:本地助手使用 Rust;现有 Droboticflow 服务端保持 Go |
### D-01 首期同步方向
@ -180,6 +181,15 @@
- 指定中文名;
- 指定英文名和命令名。
### D-16 实现语言
> **已选择 Rust。**
- Rust 实现本地同步核心、CLI、daemon、托盘 GUI、SQLite 状态和传输。
- 现有 Droboticflow API/控制面继续在当前 Go 服务内扩展。
- 不在首期新建独立 Rust 服务端,避免复制 organization、role、storage connection 和审计能力。
- 如果负责人希望“客户端和服务端全部 Rust”,需要重新决策服务拆分与迁移边界。
## 3. 待确认项答复模板
可直接复制填写:

View File

@ -0,0 +1,242 @@
# Rust 实现设计
> 决策:本地同步助手采用 Rust。现有 Droboticflow API/控制面继续在当前 Go 服务内扩展,不在首期拆出第二套 Rust 服务。
## 1. 选择边界
Rust 覆盖:
- 同步核心;
- CLI;
- 后台 daemon/service;
- 托盘 GUI;
- 本地 SQLite 状态;
- 文件扫描、hash、目录监听;
- direct/multipart 传输;
- session、lease、重试和 `keep-both` 客户端状态机;
- 客户端安装包和升级工具。
Go 继续覆盖:
- sync space/token 管理;
- 外部 Object Sync API;
- organization/role/scope 校验;
- server-side plan、lease、fencing token;
- 预签名 URL;
- commit、version、audit;
- staging/multipart 清理和 reconcile。
这样保留现有控制面中的租户、权限和 storage connection 复用,同时让单独分发给客户的工具使用 Rust。
## 2. Rust workspace
建议未来代码目录:
```text
tools/drosync/
├── Cargo.toml
├── crates/
│ ├── drosync-core/
│ ├── drosync-protocol/
│ ├── drosync-state/
│ ├── drosync-transfer/
│ ├── drosync-platform/
│ ├── drosync-cli/
│ ├── drosync-daemon/
│ └── drosync-gui/
├── packaging/
├── tests/
└── README.md
```
### `drosync-core`
- mapping 和 policy;
- 文件规范化与 ignore;
- 扫描、稳定文件判断和 SHA-256;
- manifest 生成;
- plan/item/session 状态机;
- 冲突决策;
- 与 UI、CLI 无关的领域错误。
核心不能依赖托盘窗口或命令行输出,避免三种入口产生不同语义。
### `drosync-protocol`
- API DTO;
- protocol/schema version;
- 稳定错误码;
- 幂等 key;
- session/item/lease/version 类型;
- JSON 序列化合同测试。
服务端 Go DTO 与 Rust DTO 通过 OpenAPI/固定 fixture 做双向合同测试,不能只依赖人工保持一致。
### `drosync-state`
- SQLite schema 与 migration;
- mapping、local file、session、item、multipart 和 part;
- WAL、事务和恢复;
- 单实例写入约束;
- 不保存 token、BOS AK/SK 或预签名 URL。
### `drosync-transfer`
- TLS HTTP client;
- 控制面请求;
- direct PUT;
- multipart initiate/part/complete/abort;
- 并发、限速、重试和进度;
- URL 过期续签;
- commit 超时后的状态查询与幂等恢复。
### `drosync-platform`
- OS 凭据库;
- 文件监听;
- 系统服务注册;
- 进程锁;
- 路径、大小写和 Unicode 平台差异;
- 系统代理、证书和诊断信息。
### `drosync-cli`
- `configure/plan/sync/status/conflicts/retry/abort/doctor/version`;
- 人类可读和 `--json` 输出;
- 稳定退出码;
- 无人值守模式。
### `drosync-daemon`
- 定时扫描和 watcher 纠偏;
- 断网恢复;
- mapping 调度;
- 与 GUI/CLI 的本地 IPC;
- 优雅停止和升级协调。
### `drosync-gui`
- Rust 原生托盘和窗口;
- 配置、dry-run、开始/暂停、进度;
- 冲突副本与失败重试;
- 登录状态和 doctor;
- 只调用共享核心/daemon IPC,不复制同步算法。
## 3. 建议技术组件
不在 RFC 阶段固定具体版本。建议方向:
| 能力 | Rust 组件方向 |
| --- | --- |
| async/runtime | Tokio |
| HTTP/TLS | Reqwest + rustls |
| JSON/schema | Serde |
| CLI | Clap |
| SQLite | rusqlite 或 SQLx SQLite,原型后选定一个 |
| hash | sha2 |
| 文件监听 | notify |
| 日志 | tracing |
| secret | keyring/平台凭据库适配 |
| GUI | egui/eframe + tray-icon,先验证目标 OS |
| 错误 | thiserror;应用边界可用 anyhow |
GUI 不采用 Electron。若目标 OS 的托盘、安装器、企业签名或无障碍要求无法由当前 Rust 原生组合满足,再单独评审 GUI 框架,不改变同步核心。
## 4. 并发模型
- Tokio 管理网络、heartbeat、进度和调度。
- 文件 hash 使用受限 blocking worker pool,不能占满 async runtime。
- 每个 mapping 同时只有一个调度 owner。
- 文件并发与 multipart part 并发分别限流。
- SQLite 写入集中串行化或使用短事务。
- 取消通过显式 cancellation token 传播。
- GUI 关闭不取消 daemon 中的上传。
- 进程重启后从 SQLite 和服务端状态共同恢复,不能只信任本地 `uploading` 标志。
## 5. 类型与安全约束
新类型避免混用:
- `SessionId`
- `ItemId`
- `LeaseId`
- `FencingToken`
- `LogicalTargetKey`
- `ServerGeneratedTargetKey`
- `RemoteETag`
- `PlatformVersion`
- `Sha256Digest`
- `RelativePath`
要求:
- 最终 key 不接受普通 `String` 直接构造;
- 只有服务端响应能产生 `ServerGeneratedTargetKey`;
- secret 类型禁止 `Debug/Display/Serialize`;
- 字节数使用有界整数并检查转换;
- 所有路径规范化结果显式区分本地路径与远端相对路径;
- `unsafe` 默认禁止;确需使用必须集中、说明不变量并单独评审。
## 6. 本地 IPC
CLI、GUI 和 daemon 同期交付时,推荐 daemon 持有 mapping 调度和 SQLite 主要写权限:
- GUI/CLI 通过本地 IPC 查询和发命令;
- IPC 只监听本机;
- 使用当前用户权限或随机本地认证 secret;
- 命令带 request ID 和幂等语义;
- daemon 未运行时,CLI 可选择启动它或在明确的单次模式取得本地锁;
- IPC schema 同样带版本。
具体使用 Unix domain socket、Windows named pipe 或跨平台抽象,取决于 D-09 目标系统。
## 7. 构建与测试
基础门禁:
```text
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo test --workspace --doc
```
还应包括:
- protocol JSON fixture 与 Go API 合同测试;
- SQLite migration/recovery;
- 属性测试:路径规范化、状态机和幂等 key;
- 并发竞态:同 mapping 多入口、取消、重试;
- 模糊测试:路径和 manifest 解析;
- 依赖许可证、漏洞、供应链策略;
- 目标 OS 安装、服务、托盘、凭据库与升级测试;
- 真实 BOS direct/multipart/断点恢复。
## 8. 制品
每个目标 OS/架构输出:
- CLI/daemon;
- 托盘 GUI;
- 安装包;
- SHA-256;
- 签名信息;
- SBOM;
- license notice;
- protocol compatibility;
- 安装、升级、回滚和卸载说明。
具体 target triple、签名方式和安装包格式等待 D-09 确认。
## 9. 首个代码里程碑
在 D-08、D-09 和最小规模参数确认后:
1. 创建 `tools/drosync` Rust workspace。
2. 先实现 protocol/core/state 的可测试骨架。
3. 用 fake API 完成 plan → staging upload → commit → keep-both 状态机。
4. 与 Go API 建立合同 fixture。
5. 再接真实 BOS POC。
6. 最后接 daemon、CLI 和 GUI,三者复用同一核心。
当前文档决定了语言与边界,但尚未创建 Rust 代码或声称工具可运行。

View File

@ -1,6 +1,6 @@
# 对象存储同步上传助手
> 状态:RFC 草案。D-01~D-07 已于 2026-07-28 决定;D-08 和第二轮实施参数仍待确认。
> 状态:RFC 草案。D-01~D-07、D-16 已于 2026-07-28 决定;D-08 和第二轮实施参数仍待确认。
>
> 暂定产品名:`Drobodata LocalSync`。名称本身也是待确认项。
@ -32,6 +32,7 @@
| [06-client-config-and-operations.md](06-client-config-and-operations.md) | CLI、守护进程、托盘 GUI、配置、运维与故障处理 |
| [07-delivery-and-acceptance-plan.md](07-delivery-and-acceptance-plan.md) | 分阶段实施、测试矩阵、验收证据与上线策略 |
| [08-owner-decisions.md](08-owner-decisions.md) | 已确认的决定、待确认事实和后续答复模板 |
| [09-rust-implementation-design.md](09-rust-implementation-design.md) | Rust workspace、crate 边界、并发、GUI、构建与测试设计 |
## 3. 已确认的首期产品基线
@ -44,6 +45,7 @@
7. 发生远端版本或活跃写入冲突时默认自动 `keep-both`:原对象不被覆盖,冲突副本 key 由服务端生成。
8. 文件数据通过短期预签名 URL 直传 staging;控制面负责鉴权、计划、租约、提交和审计。
9. 本地用 SQLite 保存文件指纹、上传分片和上次远端版本,支持断点续传与幂等重试。
10. 本地同步助手使用 Rust;现有 Droboticflow 服务端同步 API 继续使用 Go 扩展。
## 4. 当前结论边界