字段参考

下表枚举 cr4sync.toml 所有已知字段的类型、可选性、默认值与校验规则。

`[serve]`

字段	类型	必填	默认	说明
`address`	string	否	`"127.0.0.1"`	`cr4sync serve` 监听地址。CLI 用户可全省。必须是合法 IPv4/IPv6 字面值。
`port`	u16	否	`5731`	监听端口。

`[serve.cr4]`

CLI 与 server 都强依赖的 Cloudreve 后端配置。

字段	类型	必填	默认	说明
`server_url`	string	是	—	Cloudreve 完整 URL，必须带 `http://` 或 `https://` 协议头。
`server_port`	u16	否	按协议推断（http=80 / https=443）	自定义端口时填写。
`server_api_path`	string	否	`"/api/v4"`	API 前缀。
`admin_group`	string	否	内置识别 `"Admin"` / `"管理员"`	server 模式 admin 组名覆盖。自定义 Cloudreve admin 组名时填写；填写后只认该值。

旧版本兼容：若 [serve] 段直接出现 server_url / server_port / server_api_path（旧的扁平结构），loader 会拒绝并提示迁移到嵌套的 [serve.cr4] 段。

`[credential]`

字段	类型	必填	默认	说明
`mail`	string	否	—	明文账号。仅作为 `cr4sync login` 不带 `--mail` 时的回退源。
`passwd`	string	否	—	明文密码。同上。

强烈建议留空：把账密留在配置文件里有泄露风险（备份 / 版本控制）。改用 cr4sync login --mail x --passwd y 一次性登录，凭证只落盘到 ./credential/token.json（已 .gitignore）。

`[db]`

字段	类型	必填	默认	说明
`type`	string	否	`"sqlite3"`	数据库类型，目前恒定 sqlite3，预留扩展。
`path`	path	否	`"./data"`	sync-core 数据目录；sqlite 文件落到 `<path>/sync_core/datas/.sync_db.sqlite3`。

`[conf]`

字段	类型	必填	默认	说明
`retry`	u32	否	`3`	全局重试次数。仅 `up` / `dl` 子命令使用；sync 由 sync-core 自己管。

`[sync]`

cr4sync sync / SyncEngine 编排参数。

字段	类型	必填	默认	校验 / 说明
`src`	path	是	—	本地源目录，不存在则 cr4sync 启动失败。
`target`	string	是	—	远端目标路径，`/` 自动映射为 `cloudreve://my`。
`worker`	usize	否	CPU 核数	sync-core `WorkerPool` 容量。
`parallelism`	usize	否	`3`	最大并发传输数，范围 `1..=512`。
`sync_mode`	string	否	`"single"`	`single` / `incremental` / `append` / `two_way` 之一。
`sync_conflict`	string	否	`"skip"`	`skip`(真 no-op) / `overwrite`(本地覆盖远端) 之一。中文别名 `跳过` / `覆盖` 也接受。

模式映射：

sync_mode	sync-core SyncMode	行为
`single`	`UploadOnly`	仅上传，跑完即退
`incremental`	`UploadOnly`	仅上传，初始 + 持续监听
`append`	`UploadOnly`	跳过初始，仅持续监听
`two_way`	`Full`	双向（上传 + 下载 + 冲突策略）

`[log]`

字段	类型	必填	默认	说明
`mode`	string	否	`"cr4sync"`	`cr4sync`（仅本程序 + sync_core）/ `full`（所有依赖按 level 输出，调试网络问题用）。
`level`	string	否	`"info"`	`trace/debug/info/warn/error`。运行期可热更新。
`log_path`	path	否	`"./logs/sync_core.log"`	主日志文件。
`worker_log_terminal`	bool	否	`false`	sync / `up -r` / `dl -r` 是否在终端打 worker 日志（缺省 false，避免大量小文件刷屏）。
`server_log_path`	path	否	`"./logs/server.log"`	仅 `cr4sync serve` 使用；HTTP 访问 + 审计的额外 layer 输出。

`[migrate]`

迁移管线调优。CLI 与 server 均生效。

字段	类型	必填	默认	说明
`prefetch`	string	否	`"auto"`	预取策略: `auto`(chunk_size ≤ 100MB 自动预取) / `always`(强制) / `never`(串行)
`retry`	u32	否	`3`	单 chunk 上传/下载失败重试次数, 上限 10. 指数退避 2s→4s→8s→16s→32s→60s(cap). 仅重试可恢复错误 (网络/服务端瞬时故障 + 锁冲突); 鉴权失败 / 一致性错 / 配置错不重试.
`conflict`	string	否	`"auto"`	cloudreve 锁冲突 (错误码 40073) 处置: `auto`(强制解锁+重试→失败则跳过) / `skip`(直接跳过) / `force_unlock`(强制解锁+重试→失败则中止整个 job)
`max_concurrent_jobs`	u32	否	`10`	server 模式全局并发 job 上限，范围 `1..=512`。超出上限的 job 在后台排队等待（`status = "queued"`）。调大需注意带宽/内存。
`approve`	string	否	`"manual"`	迁移权限申请审批模式：`"auto"`（申请即生效） / `"manual"`（管理员审批）。仅 server 模式生效。
`pikpak_range_optimization`	f64	否	`0.5`	PikPak range GET 限流间隔（秒）。PikPak CDN 对同一用户的并发 range GET 返 503，限流避免瞬时并发。迁移出现 503 时可加大此值（如 `1.0`）。仅 PikPak 源生效，其他源不受限。

auto 模式: 首个 upload 拿到 cloudreve 返回的 chunk_size 后判断, ≤100MB 则 upload N 与 download N+1 并发 (双缓冲, 消除停顿); 大 chunk 不预取避免内存翻倍 (8 并发 × 100MB × 2 ≈ 1.6GB)。always 强制预取 (站长确认内存足够)。never 与改造前行为一致。

retry 退避序列: 第 1 次重试等 2s, 第 2 次等 4s, 第 3 次等 8s, 第 4 次等 16s, 第 5 次等 32s, 第 6 次及之后等 60s (cap)。max_retry=10 意味着最多 1 次首尝试 + 10 次重试 = 11 次。

conflict 三种模式:

auto(缺省): 命中锁冲突 → 调 DELETE /file/lock 强制解锁 → 退避后重试; 重试 retry 次后仍失败则标 task failed 跳过 (其他 task 继续).

skip: 命中锁冲突 → 立即标 task failed 跳过, 不解锁不重试.

force_unlock: 命中锁冲突 → 强制解锁 → 重试; 仍失败则中止整个 job (其他未跑 task 不再发起). 用于“宁可整体重跑也不允许跳过“的严格场景.

`[sources.baidu]`

仅 migrate / server 迁移端点用。

字段	类型	必填	默认	说明
`client_id`	string	否	内置 Alist 公开应用	OAuth client_id，独享配额时填。
`client_secret`	string	否	同上	OAuth client_secret。
`redirect_uri`	string	否	同上	OAuth redirect_uri。
`refresh_token`	string	否	—	一次性导入用。强烈建议留空走 `cr4sync login --baidu` 交互式粘贴。
`is_proxy`	bool	否	`false`	是否启用代理（代理在 source_credential 级，driver 凭证级）
`proxy`	string?	否	`null`	代理名（引用 `[[proxy]]` 的 name，is_proxy=true 时必填）

server 模式百度凭证写哪里：CLI 落盘到 ./credential/sources/baidu.json；server 落到 server.db 的 source_credential 表（每用户一行）。两者互不干扰。

`[sources.onedrive]`

仅 server 迁移端点用（CLI 模式 OneDrive 需通过 API 完成 OAuth，不走配置文件）。

字段	类型	必填	默认	说明
`client_id`	string	否	—	Azure 应用 client_id。server 模式下用户在 `login-session` 中传入，此处为全局默认。
`client_secret`	string	否	—	Azure 应用 client_secret。同上。
`redirect_uri`	string	否	—	OAuth 回调地址。同上。
`national_cloud`	string	否	`"global"`	OneDrive 云类型：`"global"`（国际版）或 `"china"`（21Vianet 世纪互联版）。
`is_proxy`	bool	否	`false`	是否启用代理（代理在 source_credential 级，driver 凭证级）
`proxy`	string?	否	`null`	代理名（引用 `[[proxy]]` 的 name，is_proxy=true 时必填）

OneDrive 无内置默认应用凭证，用户必须自备 Azure 应用。server 模式下 session 创建时传入的凭证优先级高于配置文件。

`[sources.aliyun]`

仅 server 迁移端点用。

字段	类型	必填	默认	说明
`client_id`	string	否	—	阿里云盘开放平台 app_id。server 模式下用户在 `login-session` 中传入，此处为全局默认。显式填 client_id 时走直连模式（POST `openapi.alipan.com/oauth/refresh_token`）。
`client_secret`	string	否	—	开放平台 app_secret。同上。
`redirect_uri`	string	否	—	OAuth 回调地址。同上。
`oauth_token_url`	string	否	`"https://api.alistgo.com/alist/ali_open/token"`	中转 refresh 端点（alist 官方中转）。中转模式用 GET `?refresh_ui=...&server_use=true&driver_txt=alicloud_qr` 换 token。显式填 client_id 时走直连，此字段忽略。
`refresh_token`	string	否	—	阿里云盘 refresh_token。中转模式（无 client_id）时直接填入，免自备开放平台应用。
`drive_type`	string	否	`"resource"`	仅 aliyun driver 使用。`"resource"`（资源盘，网页端默认）/ `"backup"`（备份盘）。选择访问资源盘还是备份盘。
`is_proxy`	bool	否	`false`	是否启用代理（代理在 source_credential 级，driver 凭证级）
`proxy`	string?	否	`null`	代理名（引用 `[[proxy]]` 的 name，is_proxy=true 时必填）

阿里云盘支持两种模式：中转模式（推荐，无 client_id 时走 alist 中转端点，无需自备开放平台应用，扫码页拿 refresh_token 即可）和 直连模式（显式填 client_id 时直连 openapi.alipan.com，需自备开放平台应用）。server 模式下 session 创建时传入的凭证优先级高于配置文件。中转模式扫码页：https://alistgo.com/zh/tool/aliyundrive/request.html。扫码授权后拿到 refresh_token 填入 refresh_token 字段即可。 is_proxy / proxy 可选字段同 [sources.onedrive]（代理在 source_credential 级，driver 凭证级）。

`[sources.s3]`

S3 兼容对象存储（AWS S3 / MinIO 等），无 OAuth，静态凭证。

字段	类型	必填	默认	说明
`access_key_id`	string	是	—	S3 access key ID
`secret_access_key`	string	是	—	S3 secret access key
`endpoint`	string	否	自动推断	自定义端点。AWS S3 可省（SDK 自动选）；MinIO 等必填。
`region`	string	是	—	区域（如 `us-east-1`）
`bucket`	string	是	—	存储桶名
`force_path_style`	bool	否	`false`	强制 path-style URL（MinIO 需 `true`）
`is_proxy`	bool	否	`false`	是否启用代理（代理在 source_credential 级，driver 凭证级）
`proxy`	string?	否	`null`	代理名（引用 `[[proxy]]` 的 name，is_proxy=true 时必填）

server 模式：access_key_id 明文存 source_credential.access_token；secret_access_key 经 token_crypto 加密存 refresh_token；endpoint/region/bucket/force_path_style 存 extra_config JSON 列。

`[sources.oss]`

阿里云 OSS，内部复用 S3Client，endpoint 默认从 region 自动拼接。

字段	类型	必填	默认	说明
`access_key_id`	string	是	—	阿里云 RAM access key ID
`secret_access_key`	string	是	—	阿里云 RAM secret access key
`region`	string	是	—	区域（如 `cn-hangzhou`）。误填 `oss-cn-hangzhou` 会被规范化去掉 `oss-` 前缀。endpoint 自动拼为 `https://oss-{region}.aliyuncs.com`
`bucket`	string	是	—	OSS bucket 名
`endpoint`	string	否	自动拼接	覆盖模板 endpoint（自建 OSS 兼容服务时用）
`is_proxy`	bool	否	`false`	是否启用代理（代理在 source_credential 级，driver 凭证级）
`proxy`	string?	否	`null`	代理名（引用 `[[proxy]]` 的 name，is_proxy=true 时必填）

force_path_style 固定 false（阿里云原生 API）。region 规范化：填 oss-cn-hangzhou 会存为 cn-hangzhou，避免 endpoint 重新推导时拼成 oss-oss-cn-hangzhou.aliyuncs.com 双前缀。

`[sources.cos]`

腾讯云 COS，内部复用 S3Client，endpoint 默认从 region 自动拼接。

字段	类型	必填	默认	说明
`access_key_id`	string	是	—	腾讯云 CAM access key ID（SecretId）
`secret_access_key`	string	是	—	腾讯云 CAM secret access key（SecretKey）
`region`	string	是	—	区域（如 `ap-guangzhou`）。误填 `cos-ap-guangzhou` 会被规范化去掉 `cos-` 前缀。endpoint 自动拼为 `https://cos.{region}.myqcloud.com`
`bucket`	string	是	—	COS bucket 名，必须含 APPID（如 `my-bucket-1250000000`）
`endpoint`	string	否	自动拼接	覆盖模板 endpoint
`force_path_style`	bool	否	`true`	COS 缺省 `true`（path-style 兼容）
`is_proxy`	bool	否	`false`	是否启用代理（代理在 source_credential 级，driver 凭证级）
`proxy`	string?	否	`null`	代理名（引用 `[[proxy]]` 的 name，is_proxy=true 时必填）

COS bucket 名格式为 <bucketname>-<APPID>，APPID 在腾讯云控制台可查。region 规范化同 OSS：填 cos-ap-guangzhou 会存为 ap-guangzhou。

`[sources.pikpak]`

PikPak driver，账密直接登录（非 OAuth），需代理访问。

字段	类型	必填	默认	说明
`email`	string	是	—	PikPak 账号邮箱
`password`	string	是	—	PikPak 密码
`refresh_token`	string?	✗	—	已持有的 refresh_token（可选，提供则跳过账密登录直接刷新）
`device_id`	string?	✗	MD5(email+password)	设备 ID，用户可覆盖
`captcha_token`	string?	✗	—	验证码 token（可选，缺省由服务端自动获取）
`is_proxy`	bool	否	`false`	是否启用代理（代理在 source_credential 级，driver 凭证级）
`proxy`	string?	否	`null`	代理名（引用 `[[proxy]]` 的 name，is_proxy=true 时必填）

PikPak 国内访问不友好，建议配置代理。PikPakAuth + PikPakClient 都接受 proxy 参数，用 build_proxied_http_client 注入。

`[sources.webdav]`

WebDAV 通用网盘兜底 driver. 支持所有 WebDAV 协议服务 (Nextcloud / Alist / 坚果云等). 匿名访问和认证访问都支持.

字段	类型	必填	默认	说明
`endpoint`	string	是	-	WebDAV 服务终结点, 如 `http://192.168.1.100:8080/dav/`
`username`	string	否	-	用户名, 匿名访问时不填
`password`	string	否	-	密码, 匿名访问时不填
`auth_scheme`	string	否	自动探测	`basic` / `digest` / `anonymous`; 缺省首次请求时自动探测
`is_proxy`	bool	否	`false`	代理配置 (source_credential 级)
`proxy`	string	否	-	引用 `[[proxy]].name`

server 模式: auth_scheme 由 credential 端点自动探测并存库; CLI 模式可手动指定, 不填则探测.

`[sources.cloudreve]`

Cloudreve 源 driver (源端 cloudreve 实例作为迁移源). 复用 sync-core ApiClient + AuthClient (登录/fs/download). download 带 Referer + User-Agent (防盗链).

字段	类型	必填	默认	说明
`server_url`	string	是	-	cloudreve 服务地址, 如 `https://demo.cloudreve.org` (不带 `/api/v4`)
`username`	string	否	-	邮箱 (CLI 登录用 `cr4sync login --cloudreve`); serve 模式 webui 登录
`password`	string	否	-	密码 (CLI 登录用); serve 模式不持久化密码 (仅 token)
`referer`	string	否	`server_url`	download / login 的 Referer; 缺省 = `server_url`
`user_agent`	string	否	浏览器 UA	User-Agent; 缺省 pikpak web UA; 前端可填 `navigator.userAgent`
`is_proxy`	bool	否	`false`	代理配置 (source_credential 级)
`proxy`	string	否	-	引用 `[[proxy]].name`

CLI 登录: cr4sync login --cloudreve 探测验证码, 开启则报错“cli 不支持, 用 serve 模式“; 2FA 支持. serve 模式 webui 登录复用 CaptchaWidget (去二维码, 支持验证码/2FA). token 存 credential/sources/cloudreve.json.

`[[storage]]`（数组段，可多个）

仅 CLI migrate 用。server 忽略此段，server 的 storage 在 server.db 里。

字段	类型	必填	默认	校验 / 说明
`name`	string	是	—	实例名，全局唯一，仅 ASCII 字母数字 / `_` / `-`。
`driver`	string	是	—	`"baidu"` / `"onedrive"` / `"aliyun"` / `"pikpak"` / `"webdav"` / `"cloudreve"` / `"s3"` / `"oss"` / `"cos"`。
`root_path`	string	否	`"/"`	源端起点路径。
`target_path`	string	是	—	目标 cloudreve URI（如 `cloudreve://my/x`）。
`parallelism`	u32	否	`1`	单实例并发，上限 `8`。
`rate_limit`	u32	否	`3`	源端 API QPS 上限，范围 `1..=20`。
`extra_config`	string	否	—	driver 特定 JSON 配置。aliyun 存 `{“drive_type”:“resource”
`is_proxy`	bool	否	`false`	已废弃，请在 `[sources.xxx]` 配置代理；保留字段兼容旧配置
`proxy`	string?	否	`null`	已废弃，请在 `[sources.xxx]` 配置代理；保留字段兼容旧配置

`[[proxy]]`（数组段，可多个）

通用代理配置，为第三方网盘 driver 访问提供代理出站能力。代理在 source_credential 级（driver 登录时绑定），通过 [sources.xxx] 的 is_proxy / proxy 字段引用。

字段	类型	必填	默认	校验 / 说明
`name`	string	是	—	实例名，用户内唯一，仅 ASCII 字母数字 / `_` / `-`。
`scheme`	string	是	—	`"http"` / `"https"` / `"socks5"` / `"socks5h"`。
`host`	string	是	—	代理主机地址（IP 或域名）。
`port`	u16	是	—	代理端口，范围 `1..=65535`。
`username`	string	否	—	代理认证用户名（可选）。
`password`	string	否	—	代理认证密码（可选）。

配置校验汇总

config/loader.rs 在解析时强制以下规则：

[serve.cr4].server_url 必填且必须以 http:// 或 https:// 开头。
旧格式扁平 [serve].server_url 等字段拒绝并提示迁移。
[serve].address 必须是合法 IP 字面值。
[sync].src 必须存在（fs check）。
[sync].worker >= 1。
[sync].parallelism in 1..=512。
[sync].sync_mode 在 {single, incremental, append, two_way} 内。
[sync].sync_conflict 在 {skip, overwrite, 跳过, 覆盖} 内。
[log].mode 在 {cr4sync, full} 内。

任何一条不满足，启动即报错，不会写回默认值。

`[license]`

License 文件路径配置. license 本身是签名后的二进制文件 (.lic), 由 @ReAxis 签发.

字段	类型	必填	默认	说明
`path`	string	否	`./credential/license.lic`	license 文件默认/指定路径

Keyboard shortcuts

cr4sync 使用文档