droboticflow/docs/drosync/runtime-configuration.md

71 lines
7.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 运行配置 — 1.0.7
CLI 与 daemon 使用同一份配置,业务配置仍由 `auth` 和 `mapping` 管理。Linux 默认读取 `/etc/drosync/environment`,可用 `drosync -c /absolute/file ...`、`drosync-daemon -c /absolute/file` 显式选择;`--config` 为同一参数的长写法。macOS 默认是 OS project config 目录下的 `environment`;Windows 为 `%PROGRAMDATA%/drosync/environment`。
默认文件不存在时使用内置默认值;显式 `-c` 文件不存在、不可读、不是普通文件、超过 64 KiB 或内容错误,均报配置错误。CLI 返回 40,daemon 不启动。修改配置后重启 daemon,并让 CLI 使用同一文件;不进行热加载,也不混用环境变量优先级。
## 文件格式与完整配置项
文件是字面量 `KEY=VALUE`,允许空行、整行 `#` 注释和成对引号。不执行 shell,不支持 `export`、变量替换、命令替换或 `$HOME`。重复、未知、已作废的键明确报错。下表是当前全部可用键;以下 `DROSYNC_*` 是**文件键**,不是环境变量。
| 文件键 | 默认值 | 范围与作用 |
|---|---|---|
| `DROSYNC_DATA_DIR` | OS project data 目录;Windows 为 ProgramData/drosync | 非空绝对路径;统一 `state.db`、Unix socket、`config/`、报告和更新恢复目录。CLI/daemon 必须一致。 |
| `DROSYNC_SECRET_FILE` | 未设;Linux 发行配置提供 `/home/ubt/.local/share/drosync/device-token` | Unix 设备 bearer token 持久化文件,绝对路径,0600;Linux ARM64 无交互服务必须配置。Windows 禁止该键,使用 OS credential store。此文件不是 Access Key Secret 输入。 |
| `DROSYNC_FILE_CONCURRENCY` | 16 | 1–128;daemon 内所有映射共享的同时处理上传文件上限。 |
| `DROSYNC_PUT_CONCURRENCY` | 16 | 1–128;所有映射/客户端实例共享的 BOS 数据 PUT 上限;直接上传和分片共同计数。 |
| `DROSYNC_PART_CONCURRENCY` | 4 | 1–32;单个文件的分片并行上限,同时受全局 PUT 上限约束。 |
| `DROSYNC_MAPPING_CONCURRENCY` | 4 | 1–16;同时同步的映射数;不会把全局文件和 PUT 上限倍增。 |
| `DROSYNC_HASH_CONCURRENCY` | 4 | 1–32;同配置的扫描共享哈希线程池,并行上限不会随映射数倍增;结果按批写入状态库。 |
| `DROSYNC_LOG_PATH` | Unix `/var/log/drosync.log`;Windows ProgramData/drosync/drosync.log | 日志首选绝对路径。 |
| `DROSYNC_LOG_FALLBACK_PATH` | `~/.local/share/drosync-ubt/drosync.log` | 首选不可写时的备选绝对路径;表中的 `~` 表示 OS 用户目录,文件内应写展开后的绝对路径。 |
| `DROSYNC_LOG_LEVEL` | `info` | `error`、`warn`、`info`、`debug`、`trace`。文件清单、同步与校验事件在正常 info/warn/error 级别可见。 |
| `DROSYNC_LOG_MAX_BYTES` | 33554432(32 MiB) | 1–1073741824;单个日志文件轮转阈值。 |
| `DROSYNC_LOG_KEEP_FILES` | 3 | 1–20;保留的轮转文件数,当前文件另计。 |
推荐从发行默认值开始,通过受控样本观察上行带宽、CPU、磁盘延迟、429/503 与提交队列后调整。并发数不是速度承诺;机械盘上提高哈希并发可能增加随机读取,BOS/控制面限流时提高 PUT 并发可能降低有效吞吐。不要同时把所有参数设为最大值。
```ini
DROSYNC_SECRET_FILE=/home/ubt/.local/share/drosync/device-token
DROSYNC_FILE_CONCURRENCY=16
DROSYNC_PUT_CONCURRENCY=16
DROSYNC_PART_CONCURRENCY=4
DROSYNC_MAPPING_CONCURRENCY=4
DROSYNC_HASH_CONCURRENCY=4
DROSYNC_LOG_PATH=/var/log/drosync.log
DROSYNC_LOG_LEVEL=info
DROSYNC_LOG_MAX_BYTES=33554432
DROSYNC_LOG_KEEP_FILES=3
```
可核对的发行样例:[packaging/linux/environment](../../tools/drosync/packaging/linux/environment)。配置不应放在被同步的数据目录中。
## 历史键处理
| 旧键 | 1.0.7 状态与迁移 |
|---|---|
| `DROSYNC_SERVER_URL`、`UBT_SERVER` | 文件中作废并报错;云端地址只用 `drosync auth --server URL` 设置。 |
| `UBT_SPACE` | 作废;用 `mapping add ROOT --space ID`。 |
| `UBT_KEY`、`DROSYNC_ACCESS_KEY_ID`、`DROSYNC_SECRET`、`DROSYNC_TOKEN` | 作废;`auth --access-key-id ID --secret-file FILE` 或 `--secret-stdin`。不把秘密写入运行配置。 |
| `UBT_LOCAL_DIR`、`DROSYNC_LOCAL_DIR` | 作废;用 `mapping add ROOT ...`。 |
| `DROSYNC_REMOTE_PREFIX` | 作废;用 `mapping add ... --remote-prefix PREFIX`。 |
| `DROSYNC_BUCKET` | 作废;用 `mapping add ROOT --bucket NAME` 解析唯一获授权 Sync Space,或显式 `--space ID`。 |
| `DROSYNC_SECRET_FILE` | 保留为**配置文件键**;仅存储登录后 device token,不能代替 `auth --secret-file` 的 Access Key Secret。 |
| `HOME`、`XDG_DATA_HOME`、`XDG_CONFIG_HOME` | 不是配置文件键,写入会报错;它们仍是 OS 用户目录解析输入。显式命名空间用 `DROSYNC_DATA_DIR` 文件键。 |
`DROSYNC_REMOTE_PREFIX` 与 `mapping add ... --remote-prefix PREFIX` 表达同一业务配置:相对 Sync Space 根的远端路径前缀。当前版本已作废 `DROSYNC_REMOTE_PREFIX`,它出现在配置文件或进程环境中都会报错;唯一配置入口是 `mapping add ... --remote-prefix PREFIX`,其值保存到对应映射,未指定时使用空前缀。旧键不参与默认值、拼接、覆盖或优先级判断。
`DROSYNC_BUCKET` 则是存储桶维度,其旧配置键同样已作废;实际 bucket 由映射选定的获授权 Sync Space 决定,与远端路径前缀分开管理。
进程检测到旧 DROSYNC/UBT 运行环境变量会明确拒绝启动;移除 shell export、旧 systemd `Environment`/`EnvironmentFile`、LaunchAgent 环境设置中的这些项,再写入受支持的文件键。OS 的 HOME/XDG/PROGRAMDATA 目录发现和构建期签名公钥不属于运行配置覆盖入口。安装包保留已存在的配置文件,不会替用户静默猜测和转换旧业务设置。
## 日志与故障处理
daemon 启动时先打开首选路径;失败则尝试备选;两者都失败时启动失败。日志由有界队列批量写入,约每 250 ms flush,按大小轮转;队列满时施加背压,避免无限内存或静默丢失关键文件事件。文件日志不是网卡流量计,正常退出会排空队列,强杀仍可能丢失最后未落盘的批次。
查看 `log_path` 启动事件确认实际路径。清单事件包含路径、大小、SHA256;同步事件包含文件、Session、状态和错误;校验事件区分通过、文件改变和丢失。不会逐网络 chunk 落盘;进度在内存累加后采样保存。预签名 URL query 会脱敏,凭据不应出现在日志。
相关操作:[CLI](cli-reference.md);完整 V1.1 需求验收:[逐项记录](../../doc/drosync每日数据上传V1.1需求审查与实现-2026-10-08.md)。
1.0.8 补齐运行中的日志故障回退:首选路径写入、flush 或轮转失败时,切换备用路径并重放有界的未确认日志批次;部分写入不确定时可能重复。备用也失败则明确诊断并输出 stderr,直到 daemon 重启。正常文件事件完整性以默认 info 级别验收;提高日志阈值会过滤较低级别事件。