# 运行配置 — 当前客户端 1.1.1 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` | 4 | 1–128;daemon 内所有映射共享的同时处理上传文件上限。 | | `DROSYNC_PUT_CONCURRENCY` | 4 | 1–128;同一 daemon 进程内所有映射及其传输客户端共享的 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 会过滤常规 INFO 成功事件。 | | `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=4 DROSYNC_PUT_CONCURRENCY=4 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)。配置不应放在被同步的数据目录中。 ## 历史键处理 | 旧键 | 当前状态与迁移 | |---|---| | `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` 启动事件确认实际路径。清单事件包含路径、大小、MD5;同步事件包含文件、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 级别验收;提高日志阈值会过滤较低级别事件。 1.0.33 的“日志回退后旧路径阻塞同步”问题已在 1.0.34 修复;配置/凭据和采集根重叠保护保留。见 [修复与真实验收](../../doc/drosync两项缺陷修复与1.0.34验收-2026-10-16.md)。 完整的参数范围、平台差异、auth/mapping 业务配置、历史键迁移、Linux 示例和本机实际配置见 [最新配置项完整说明](../../doc/drosync最新版本配置项完整说明.md)。