forked from longtao.wu/droboticflow
📝 Define Rust sync client architecture
This commit is contained in:
parent
b8d9a469a5
commit
aacf075400
@ -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)。
|
||||
|
||||
@ -1,5 +1,7 @@
|
||||
# 客户端配置与运维
|
||||
|
||||
客户端使用 Rust 实现。CLI、daemon、托盘 GUI、本地状态和传输逻辑位于同一个 Rust workspace;GUI 是共享核心的薄交互壳。详见 [09-rust-implementation-design.md](09-rust-implementation-design.md)。
|
||||
|
||||
## 1. 建议命令
|
||||
|
||||
```text
|
||||
|
||||
@ -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;
|
||||
|
||||
@ -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. 待确认项答复模板
|
||||
|
||||
可直接复制填写:
|
||||
|
||||
@ -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 代码或声称工具可运行。
|
||||
@ -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. 当前结论边界
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user