drosync:Rust 数据同步客户端
drosync 是使用 Rust 实现的、从本地采集目录单向上传到 BOS 的客户端。 它提供命令行、后台同步、断点恢复、文件级进度与日报,以及有云端证据约束的本地文件清理。它不是 Python 同步脚本,也不是双向文件同步工具。
本 README 按 2026-10-31 的 poc 源码核对。它说明当前代码如何工作,不代表对应安装包已经发布,或用户设备已经升级。
客户端与服务端的边界
| 组成 | 语言 / 位置 | 职责 |
|---|---|---|
drosync |
Rust,CLI | 用户操作入口,通过本机 IPC 调用 daemon;也提供查询、报告和只读 Web 页面。 |
drosync-daemon |
Rust,daemon | 持有 SQLite 状态库,负责扫描、调度、上传、重试、恢复及本地清理。 |
| 平台 API | Go,对象同步 API | 认证设备、接收清单、校验权限、签发上传和清理凭据。它不属于本 Rust workspace。 |
| 服务端协调器 | Go,objectsync | 规划上传、核验对象、正式提交回执及处理后台恢复任务。 |
| 发布辅助工具 | Shell / Python / PowerShell,packaging | 构建元数据、打包、签名和安装辅助,不承担客户端同步业务逻辑。 |
CLI 不直接拥有上传队列;daemon 与平台交换控制信息,文件内容经受约束的 PUT / 分片上传进入 BOS。传输进度达到 100% 不等于已正式归档,还需等待服务端提交回执。
客户端运行包包含 CLI 和 daemon,不包含独立桌面 GUI。web 是嵌入式只读报告页面,不是同步控制面板。源码交付若同时附带 Go 文件,表示包含了配套平台代码,不表示客户端改用了 Go。
版本、协议与目录
| 项目 | 当前源码约定 |
|---|---|
| 客户端版本 | 以 Cargo.toml 中 workspace.package.version 为准;本次核对为 1.1.6。 |
| Rust | rust-toolchain.toml 固定 1.89.0;workspace 声明 Rust 1.89、Edition 2024。 |
| 内容协议 | v2,文件内容及分片校验使用 MD5。 |
| 本地状态 | SQLite schema 7,由 daemon 负责迁移和写入。 |
| 软件发布安全 | 软件包签名、发布清单及制品 SHA256 校验与文件内容 MD5 是不同机制,仍然保留。 |
查看设备上的实际 CLI / 可达 daemon 版本:
drosync version
源码版本、源码提交、已发布安装包和设备已安装版本必须分别核对。 例如,partial 逐文件清理由 503a45e1 引入,1.1.5 是首个包含它的安装包;1.1.3、1.1.4 只是版本号递增,没有对应安装包。不能仅凭版本字符串认定某个包已经包含某个提交。
tools/drosync/
├── Cargo.toml workspace、统一版本与依赖
├── Cargo.lock 锁定依赖
├── rust-toolchain.toml 工具链版本
├── crates/ Rust 实现及测试
└── packaging/ Linux / macOS / Windows 打包与安装辅助
| Crate | 主要职责 |
|---|---|
core |
映射、稳定文件扫描、哈希、报告模型和隔离式文件清理。 |
protocol |
与服务端共享的状态枚举及请求/响应类型。 |
state |
SQLite WAL、扫描缓存、回执、分页和崩溃恢复。 |
transfer |
HTTP 控制请求、条件上传、分片和传输完整性验证。 |
platform |
操作系统目录、IPC 位置、运行配置和凭据存储。 |
cli |
命令解析、结果输出、报告导出和只读 Web 服务。 |
daemon |
后台任务生命周期、并发控制、认证、同步及清理编排。 |
updater |
发布清单/制品验证、安全安装与回滚;包含发布辅助签名工具。 |
协议源为 OpenAPI,状态契约由 生成脚本 更新 Go / Rust 两端,不应只修改一端的生成文件。
安装前准备
- 准备平台管理员分配的 Access Key、可访问的 Sync Space,以及本地采集目录。
mapping表示“一个本地目录对应一个云端同步空间及可选前缀”。 - 服务端 API / coordinator 与客户端必须兼容。客户端会校验协议、schema 和所需能力;缺少能力时明确拒绝,不静默退回旧协议。
- 选择与操作系统、CPU 架构匹配的安装包,先核对制品摘要和签名。源码 ZIP、preview 包、单独编译的二进制都不等价于正式签名安装包。
- CLI 与 daemon 必须使用同一发布版本、同一配置和状态命名空间;同一命名空间只运行一个 daemon。
| 平台 | 安装方式及注意事项 |
|---|---|
| Linux x86_64 / ARM64 | 签名 DEB 或经过验证的 portable systemd 包,二选一;不要同时安装两套服务。 |
| macOS arm64 | 原生 PKG,正式发布需要签名与公证。 |
| Windows x86_64 | Authenticode 签名 MSI 系统服务;用户启动脚本模式已退出支持。 |
Linux 包默认使用 ubt 服务账户;CLI 也应使用对应账户及目录。先确认状态、凭据和日志目录可写,不要让 root 的 CLI 与普通用户 daemon 意外使用两套状态。Linux x86_64 的凭据后端可能需要 libdbus-1-3,ARM64 包使用显式配置的文件凭据存储。
具体安装/升级步骤见 安装说明 和 portable systemd 说明。服务启动、停止和开机启用由对应 OS 服务管理器负责,不是 drosync 的额外子命令。
运行配置
Linux 默认配置文件为 /etc/drosync/environment;macOS 使用 OS project config 目录;Windows 使用 %PROGRAMDATA%/drosync/environment。CLI 与 daemon 都可用 -c FILE / --config FILE 显式选择配置。
配置是字面量 KEY=VALUE 文件,不是 shell 脚本:不支持 export、$HOME 展开或命令替换。这里的 DROSYNC_* 是配置文件键,不是进程环境覆盖入口。
以下为 Linux ubt 账户的示例,目录需预先准备并可由服务账户写入;其他账户必须使用实际绝对路径:
DROSYNC_SECRET_FILE=/home/ubt/.local/share/drosync/device-token
DROSYNC_LOG_PATH=/home/ubt/.local/state/drosync/drosync.log
DROSYNC_LOG_LEVEL=info
DROSYNC_FILE_CONCURRENCY=4
DROSYNC_PUT_CONCURRENCY=4
DROSYNC_PART_CONCURRENCY=4
DROSYNC_MAPPING_CONCURRENCY=4
DROSYNC_HASH_CONCURRENCY=4
auth --secret-file读取 Access Key Secret 输入文件;配置中的DROSYNC_SECRET_FILE保存认证后得到的 device token。两者不是同一个用途。DROSYNC_DATA_DIR可显式选择本地状态目录;升级时不要随意改变,否则会切换到另一个命名空间,而不是恢复原有映射和会话。- 不要把状态库、token、日志、更新目录放进采集映射根目录。
- 服务端地址、Access Key 和上传目录由
auth/mapping add管理,不使用旧的DROSYNC_SERVER_URL、DROSYNC_LOCAL_DIR、DROSYNC_BUCKET、DROSYNC_REMOTE_PREFIX等运行配置或环境变量。 - 安装器/CI 的构建参数与上述运行配置是两套不同机制。
完整键名、默认值、范围和旧配置迁移见 运行配置。
首次配置与同步
以下假设已经安装并启动 daemon,使用与服务一致的账户/配置。将示例中的域名、<...> 和绝对路径替换为真实值;不要把 Secret 直接写在命令参数或聊天记录里。
1. 认证设备
drosync auth --server https://data.example.com --access-key-id '<ACCESS_KEY_ID>' --secret-file '/absolute/path/access-key-secret' --require-https
也支持 --secret-stdin,与 --secret-file 二选一。不要把 Access Key Secret 当作 device token 手工写入状态目录。
drosync doctor
doctor 用于检查本地状态、IPC、身份和服务契约;它不是一次真实上传或云端完整性验收。暂停状态下 syncReady 为 false 是预期行为。
2. 暂停自动调度并添加映射
先暂停,避免添加映射后后台同步早于人工预览启动;暂停不会撤销已在途的上传,也不会停止采集程序。
drosync pause
drosync mapping add '/absolute/path/captures' --space '<SYNC_SPACE_ID>' --remote-prefix '<DEVICE_PREFIX>'
也可将 --space 换为 --bucket '<BUCKET>',但该 bucket 必须能唯一解析到一个当前凭据可见的 Sync Space;两参数不能同时使用。远端路径由 Sync Space 根前缀、mapping 的 remote prefix 与本地相对路径共同确定。
drosync mapping list
记录返回的 mapping ID。只有一个映射时 sync 可省略 ID;多个映射必须明确选择。
3. 预览,再正式同步
drosync sync '<MAPPING_ID>' --dry-run
sync --dry-run 会建立单独的云端预览会话并确认其关闭,但不上传文件内容,也不替换正式上传回执;暂停状态下可以执行预览。
确认映射和目标正确后恢复调度:
drosync resume
drosync sync '<MAPPING_ID>'
drosync --json status --limit 100
status 查看本地已知状态,默认一页 100 个 Session;存在 nextCursor 时需要继续分页,不能将当前一页当成所有历史记录。
扫描与归档规则
- 默认等待文件稳定 60 秒;隐藏文件、符号链接、临时文件等按扫描规则排除。
- 文件元数据(大小、mtime、ctime、inode 等)只有在最后一次变化早于该次哈希开始至少 3 秒时,才可单独证明内容未变。Linux 在同一时间戳刻度内的同尺寸快速改写可能让这些字段完全不变,因此扫描缓存、上传前检查和日报对较新的变化都会重新读取内容核对 MD5。
- 升级后首次扫描会对缓存中缺少哈希时间证据的文件各重新计算一次 MD5;之后恢复正常缓存复用。
- 只有采集流程确实生成
{file}.done标记时才启用mapping add --require-done;否则文件可能一直无法进入清单。 - mapping 本地根目录下的
daily_report/生成目录不上传;嵌套业务目录中的同名目录及普通表格文件不因此排除。 - 当前采用一次归档保护:已归档同路径内容的 MD5/大小一致可判为
unchanged;不同内容被拒绝,不静默覆盖已有云端文件。 - SHA256-only 历史归档缺少可信 MD5 时保持拒绝,不能直接把本地计算的 MD5 填成云端证据。见 MD5 切换说明。
如何理解 Session 状态
| 状态 | 含义 |
|---|---|
collecting_manifest / planning / planned / running |
会话尚未结束,不能据此删除源文件。 |
completed |
按服务端汇总规则结束;仍需逐文件核验,不能理解为“所有本地文件都可删除”。 |
partial |
本轮已结束,但存在 denied/failed 等未成功项;其中也可能有大量已成功文件。 |
conflicted |
存在保留双方等冲突结果,需要按冲突规则处理。 |
failed / aborted / expired |
会话失败、取消或过期,不具备整会话清理准入资格。 |
只要清单内仍有被拒绝的文件,反复同步仍可能得到 partial。历史会话不会通过重试被改写为 completed。需要取消任务时使用 abort;mapping remove 会先处理取消流程,但不删除源文件或已提交云端对象。
安全清理本地文件
当前源码支持从 completed 和 partial 会话逐文件清理,但不是放开整批删除。 客户端与 API 必须都包含该能力;只更新客户端,旧 API 仍会拒绝 partial 的清理凭据,客户端会保留文件。
清理前必须同时满足:
- 本地与当前云端 Session 都属于该 mapping,状态为
completed或partial,且不是 preview。 - mapping 没有活动/待处理任务、未解决的清理恢复记录或重叠的源目录。
- 文件状态为
committed或unchanged,并持有当前最新、绑定到该 Session/item 的本地回执和 source identity。 - 文件具有有效 MD5,本地内容/身份与回执一致;云端索引和实时对象 HEAD 的 MD5、大小、ETag、版本也匹配。
- 每次删除都有新鲜云端 proof 和有效短期租约。最后一次完整读取之后还会重新核对授权截止时间。
先停止外部采集/写入程序并关闭其写句柄,再做预览。 drosync pause 只暂停同步调度,不会停止外部程序写文件;最终 MD5 复核也不是对所有并发写入的原子保护。
drosync --json clean '<MAPPING_ID>' --session '<SESSION_ID>'
确认候选、保留原因和数据保留策略后,才显式执行删除:
drosync --json clean '<MAPPING_ID>' --session '<SESSION_ID>' --execute
默认不带 --execute 就只预览,不移动或删除源文件。执行时:
- 只删除本地已验证文件,不删除云端对象,也不递归删除整个采集目录。
- 缺失/非法 MD5、denied/failed/skipped/kept_both、本地或云端变化、旧回执被替换等文件逐项保留,并说明原因;其他合格文件可继续清理。
- 采用可恢复隔离目录和持久化清理账本;恢复不能覆盖同名新采集文件。需要人工恢复时会停止继续处理,保留隔离数据。
- 对有完整恢复证据的同一文件,重新核对身份、MD5 和作用域后,原子更新对应回执的 source identity;云端问题解除后可用原 Session 直接重试,不必重新 sync。每次重试仍需新的云端授权。旧日志、缺检查点、文件或回执已变化等情况不会自动追认。
- 不修改 Session 的 partial 状态、不修改失败文件状态、不自动补录历史 MD5。
| 返回字段 | 含义 |
|---|---|
candidateFiles / candidateBytes |
通过校验的候选数量 / 字节数。 |
deletedFiles / deletedBytes |
本次实际删除数量 / 字节数;预览时为 0。 |
blockedFiles |
保留项数量,具体原因见 files。 |
alreadyCleanedFiles |
已有精确清理账本、源文件仍不存在的项;不会重复删除。 |
recoveryNeeded / recovery |
是否仍有待恢复隔离数据及其位置。 |
files / filesTruncated |
逐文件结果最多 1000 项;汇总数量可能大于明细数组长度。 |
有 blocked 或 recovery-needed 项时 CLI 退出 50,但同批合格文件可能已经清理;自动化必须同时读取 JSON,不能把非零退出码理解为“整批没有发生删除”。不要删状态库、手改会话状态或用 rm -rf 绕过保护。
修复边界和测试证据见 completed/partial 逐文件清理报告。
批次、日报与排障命令
查看当天批次:
drosync episodes --mapping '<MAPPING_ID>' --date today --status all
导出报告到采集目录之外:
drosync report --mapping '<MAPPING_ID>' --date today --format xlsx --output '/absolute/path/reports'
启动只读页面(默认 127.0.0.1:8080):
drosync web --mapping '<MAPPING_ID>'
report 支持 XLSX / CSV;报告导出不会自动随同步运行。web 只能查看批次、文件状态、进度和缺失原因,不能认证、同步、清理或导出。报告依据本地文件及已保存回执,不是对当前 BOS 对象的实时完整性审计。
Unix 上,回执带有已稳定的哈希时间证据时,日报只比较 source identity,不重复读取文件。旧版本写入的回执、刚写入就上传的文件,以及清理恢复后的回执缺少这种证据,日报会读取文件核对 MD5,耗时随文件大小增加;下一次稳定扫描确认相同身份和 MD5 后恢复快速路径。Windows 始终核对 MD5。
全局 --json 适合自动化;命令列表和参数以帮助为准:
drosync --help
drosync clean --help
帮助仅使用 --help;没有 help 子命令、-h 或 --version 别名。旧的 configure/plan/retry/GUI/Web 控制入口和 clean-install/reset 类脚本已退出支持。完整命令与退出码见 CLI reference。
源码构建与测试
开发环境
- 使用 锁定工具链;以下命令显式选择
1.89.0,从 droboticflow 仓库根目录执行。 - 准备本机 C/C++ 链接工具链:Linux 编译工具和必要的 pkg-config/凭据后端开发库、macOS Command Line Tools,或 Windows MSVC Build Tools / SDK。
Cargo.lock随源码提交,构建与测试使用--locked。只有依赖已经缓存完整时才加--offline。- 如在
tools/drosync/中直接执行cargo,rustup 会读取该目录的工具链文件;从其他目录只指定--manifest-path不等于切换工具链。
编译客户端与 daemon 的开发二进制:
cargo +1.89.0 build --locked --manifest-path tools/drosync/Cargo.toml -p drosync-cli -p drosync-daemon
默认输出为 tools/drosync/target/debug/drosync 与 drosync-daemon(Windows 带 .exe 后缀;自定义 Cargo target 目录时以其配置为准)。这一步不安装服务、不认证设备、不开始上传,也不产生正式发行包。生产/性能验收应使用经过发布流程生成的 Release 构建,不能用 debug 构建评估上传性能。
开发运行仍需 daemon,CLI 与 daemon 使用同一份显式配置;采用独立开发状态目录,不要与已安装服务同时操作同一个状态库。
全量 Rust 测试:
cargo +1.89.0 test --locked --manifest-path tools/drosync/Cargo.toml --workspace -- --test-threads=1
格式检查:
cargo +1.89.0 fmt --manifest-path tools/drosync/Cargo.toml --all -- --check
静态检查:
cargo +1.89.0 clippy --locked --manifest-path tools/drosync/Cargo.toml --workspace --all-targets -- -D warnings
修改服务端同步契约时,还应在完整仓库中运行 Go 回归;Go 环境按根目录 go.mod 准备:
go test ./internal/api ./internal/objectsync ./internal/store -count=1
2026-10-30 同尺寸改写识别修复:macOS arm64 workspace 297 项、Linux arm64 workspace 300 项通过,真实清理链路 macOS 13/13、Linux 12/12 通过;本机 harness 的 pause-resume 场景修复前后同样失败。详见 修复报告。
2026-10-31 本机 harness pause-resume 已整合并补强:接收端挂起首个请求体,等待两个文件并发槽都完成预留后才暂停,避免把延迟到达的已派发请求误算为暂停后的新派发;即便客户端已把全部字节交给 socket,也以实际接收端阻塞为在途证据。超时明确失败,暂停后断言没有新增预留、重传或不完整提交。macOS arm64 与 Linux x86_64 各重复 10/10 通过,macOS 全部 26 个场景通过,另有 8 项夹具回归;没有改动 daemon 或重新发布 1.1.6 包。
2026-10-28 清理修复的既有验证记录:macOS arm64 Rust workspace 280 项通过;Linux arm64 core/state 53 + 30 项通过;Go 相关包及变更组件 Clippy 通过。该记录使用的具体工具链、测试范围与原始日志见 验证报告,不应扩展为四平台发行验收或现场真实 BOS 删除验收。
发布包不是源码 ZIP
| 入口 | 用途 |
|---|---|
| build-release.sh | Linux / macOS 正式包构建编排,需要对应构建机、版本及 CI 签名/信任配置。 |
| Windows build-msi.ps1 | 在 Windows x86_64 构建机上生成原生 MSI。 |
| build-preview.sh | 隔离验证用 preview 包,不能当作正式签名包交付。 |
| build-metadata.py | 核对 Cargo 版本、CLI/daemon 构建身份与包元数据。 |
每次为用户生成新的发行包/构建,按 项目规则 将 Cargo 版本末位加一,并保持依赖锁和构建元数据一致。DROSYNC_VERSION 必须对应已提交的 Cargo 版本,不能只改压缩包文件名。正式包需要匹配平台的更新验证公钥,以及 DEB/portable、PKG 或 MSI 对应的签名机制;签名私钥由发布环境管理,不能写入源码包;验证公钥可以随源码和客户端发布。
升级顺序为服务端 API / coordinator 及所需索引在先,客户端在后;升级过程中保留状态库、WAL/SHM、映射与恢复记录。portable 与 native 更新渠道不能混用,不得修改安装标记或跳过签名检查来强行升级。POC 发布还须遵循根目录项目指引,不混入 dev / Fanyu 基线。
公网签名自更新(Linux portable)
从 1.1.6 起,Linux portable systemd 安装支持独立的公网签名通道,不依赖 POC API 注册版本。1.1.5 及以前的设备需要先手工安装一次可信的新包,不能通过修改安装标记获得此能力。
sudo /opt/drosync/drosync update check
sudo /opt/drosync/drosync update install
CLI 校验内置 Ed25519 公钥、目标包和原版本恢复包,安装后等待 daemon 就绪;失败会尝试恢复。daemon 只检查/预下载,不会自动安装。恢复后版本会被 pin,需要解决原因后显式 update unpin。配置、映射、状态库、凭据和采集文件不重置。
正式 1.1.6 Linux x86_64 包已发布到公网,下载地址、固定 SHA256、首次安装步骤和实测结果见 1.1.6 公网自更新与验收。
完整信任模型、回退和发布操作见 公网签名便携更新。原生 DEB/PKG/MSI 继续使用原通道,不能与 portable 混装;预览包不能自动更新。
常见问题
| 现象 | 核对方式 |
|---|---|
| CLI 连接不上 daemon,或看不到原有 mapping | 核对服务是否运行、操作账户、-c 配置和 DROSYNC_DATA_DIR 是否一致,再看 doctor;不要直接重建/删除状态库。 |
| 扫描结果为 0 | 核对稳定窗口、临时/隐藏文件过滤、根级 daily_report/、是否误启用 --require-done,以及文件是否已有可跳过回执。 |
| 上传进度 100% 但未显示完成 | 核对是否仍在等待正式提交回执;不要依据传输百分比清理源文件。 |
| sync 每次都是 partial | 查看逐文件 denied/failed 原因;常见为旧归档缺 MD5 或同名内容冲突,并不表示所有文件都未上传。 |
| clean 仍提示必须 completed | 核对实际 CLI/daemon 版本与所含提交、服务端 API 是否配套更新;旧安装包不会因仓库源码更新而自动获得能力。 |
| clean 返回 50 | 同时查看 deletedFiles、blockedFiles、files[].reason 和 recoveryNeeded;可能已完成部分清理。 |
| 升级后首次扫描或日报变慢 | 正在为缺少哈希时间证据的缓存/回执重新读取内容;这是同尺寸改写识别的安全核对,不要删除状态库来跳过。 |
| 日志路径不可写 | 核对服务账户权限,配置绝对、可写的日志/回退路径;不要将日志放到采集目录或盲目改用 root。 |
日志默认 INFO,包含扫描、文件同步/校验、运行阶段及结果;run_id、Session ID、mapping ID 可用于关联排查。需要详细控制请求诊断时使用配置文件键 DROSYNC_LOG_LEVEL=debug,具体路径、轮转和安全边界见 运行配置。提交故障信息时提供版本、状态、标识和脱敏日志,不提供 Access Key Secret、device token 或完整预签名 URL。
文档导航
- CLI 参数与退出码
- 运行配置与旧键迁移
- 安装、升级与设备恢复
- 架构与状态机
- 权限与安全
- 服务端运维
- 签名更新流程
- completed/partial 安全清理修复及验证
- 详细回归、线上版本与失败恢复限制
- 受控恢复后原 Session 直接重试修复
- Linux 补充验收:清理通过与全量剩余失败
- Linux 同尺寸快速改写识别修复
- 1.1.5 发布准备与 POC 升级计划
- 历史:1.1.2 partial 回执恢复
- 历史:MD5-only 内容协议切换
历史报告中的版本、通过数量和部署结论只代表当时的验证,不覆盖当前源码或用户现场状态。