Proton Drive Sync CLI 命令速查表：auth、start、pause、reconcile 全命令一次看懂-开发者社区

【免费下载链接】proton-drive-sync

Local folders, automatically synced to Proton Drive. (Unofficial Sync Client)

项目地址：https://gitcode.com/gh_mirrors/pr/proton-drive-sync

Proton Drive Sync是一款开源的非官方 Proton Drive 同步客户端，可以把本地文件夹自动同步到 Proton Drive。它通过一条proton-drive-sync命令行工具完成所有操作：登录授权（auth）、启动同步守护进程（start）、暂停/恢复同步（pause/resume）、触发全量扫描（reconcile）等。本文整理了一套完整的Proton Drive Sync CLI 命令速查表，帮助新手快速掌握每一条命令的用法与参数。

📌 为什么需要一份 CLI 命令速查表？

Proton Drive Sync 虽然内置了浏览器仪表盘（默认运行在http://localhost:4242），但绝大多数日常操作——登录、启停、暂停、查看日志——都可以直接用命令行完成，更快也更省心。

它支持 macOS（Homebrew）、Debian/Ubuntu、Fedora/RHEL、Arch（AUR）、AppImage、Flatpak、Nix 以及 Docker 等多种安装方式，安装完成后运行proton-drive-sync setup即可进入交互式向导完成首次配置。

🚀 核心命令一览（Proton Drive Sync 命令速查表）

命令	作用	常用参数
`setup`	交互式首次配置向导（推荐首跑）	—
`auth`	登录 Proton 并安全保存凭据	`--logout`
`start`	启动同步守护进程	`-n, --dry-run`、`--no-daemon`、`--no-watch`、`--paused`
`stop`	优雅停止同步进程	—
`status`	查询运行状态（JSON 输出）	—
`pause`	暂停同步（进程继续运行）	—
`resume`	恢复已暂停的同步	—
`reconcile`	触发全量文件系统扫描	—
`config`	管理配置（同步目录、排除规则等）	见下文
`logs`	查看服务日志	`-f, --follow`
`service`	管理系统服务（systemd / launchd）	`install`/`uninstall`/`load`/`unload`
`reset`	重置同步状态	`--purge`
`dashboard`	单独启动仪表盘服务	—
`--help`	查看全部可用命令	—

💡 提示：所有命令前缀均为proton-drive-sync，例如完整写法是proton-drive-sync auth。

🔐 auth 命令：如何登录 Proton 账号？

auth命令负责登录 Proton 账号，并把凭据安全地存入系统钥匙串（keychain），之后start时会自动复用，无需反复输密码。

# 交互式登录（输入用户名、密码，必要时输入 2FA 验证码） proton-drive-sync auth # 清除已保存的凭据（登出） proton-drive-sync auth --logout

几个新手常见的疑问：

支持 2FA：如果账号开启了双因素认证，会提示你输入 2FA 验证码（暂不支持 Security Key）。
双密码模式（two-password mode）：如果账号启用了双密码，还会额外提示输入 Mailbox password。
环境变量免交互：可预先设置PROTON_USERNAME、PROTON_PASSWORD（以及PROTON_MAILBOX_PASSWORD）环境变量，登录过程无需手动输入，适合脚本化场景。
已有凭据时会先验证：如果已登录过，auth会先校验现有会话是否有效，并询问是否重新认证。

实现细节可参考 src/cli/auth.ts，凭据通过 src/keychain.ts 存入系统钥匙串。

▶️ start 命令：启动同步的 4 个关键参数

start是日常使用频率最高的命令。默认行为是**派生一个后台守护进程（daemon）**并在前台打印启动进度，启动成功后即可 Ctrl+C 或关闭窗口。

# 启动同步守护进程（默认） proton-drive-sync start

start 参数详解

参数	说明
`-n, --dry-run`	演练模式：只显示将要同步的内容，不做任何实际修改，适合首次配置后验证
`--no-daemon`	在前台运行，而不是后台守护进程（调试时很实用）
`--no-watch`	只同步一次就退出（必须配合`--no-daemon`），适合脚本定时任务
`--paused`	以"已暂停"状态启动（仅 watch 模式），即启动后不立即同步，等`resume`再开始
`--dashboard`	作为仪表盘子进程运行（内部使用，一般不需要手动传）

# 演练模式：看看会同步什么 proton-drive-sync start --dry-run # 前台运行，方便看输出 proton-drive-sync start --no-daemon # 一次性同步（例如 cron 定时任务） proton-drive-sync start --no-daemon --no-watch

⚠️ 注意：start之前必须先完成auth，否则会提示No credentials found. Run proton-drive-sync auth first.；如果提示另一个实例已在运行，用proton-drive-sync stop先停掉旧进程。

⏸️ pause / resume 命令：暂停与恢复同步

当你想暂时停止同步（比如上传大量文件前想先手动整理），又不想真正关闭进程时，pause就是最佳选择——进程继续运行，只是不再处理同步任务：

# 暂停同步 proton-drive-sync pause # 恢复同步 proton-drive-sync resume

两个命令都很"聪明"：

进程没在运行时执行pause/resume，会提示No running proton-drive-sync process found.；
已经暂停时再执行pause，会提示用resume继续；未暂停时执行resume则提示Sync is not paused.。

仪表盘界面上同样提供暂停按钮，底层原理相同，都是设置/清除同一个 paused 标志文件。相关源码见 src/cli/pause.ts 和 src/cli/resume.ts。

🔍 reconcile 命令：如何触发全量文件系统扫描？

文件监听器偶尔会漏掉某些变更（例如大批量文件移动、外部程序批量写入等）。reconcile命令会向正在运行的守护进程发送信号，立即触发一次完整的全量扫描，让本地和云端状态重新对齐：

proton-drive-sync reconcile

输出提示：Reconcile signal sent to daemon. Check daemon logs for progress.，之后用proton-drive-sync logs -f观察进度即可。

⚠️reconcile要求守护进程正在运行，否则会报错并提示先执行proton-drive-sync start。源码见 src/cli/reconcile.ts。

⚙️ config 命令：同步目录与排除规则怎么配？

config是一个"命令族"，不带子命令时进入交互式菜单。常用子命令：

# 查看当前全部配置 proton-drive-sync config get proton-drive-sync config get --json # JSON 输出 # 管理同步目录（本地路径 -> Proton Drive 远端目录） proton-drive-sync config sync-dir --add ~/Documents --remote /Docs proton-drive-sync config sync-dir --list proton-drive-sync config sync-dir --remove ~/Documents # 管理文件排除规则（glob 模式） proton-drive-sync config exclude --path ~/Documents --add "*.tmp" "*.zip" proton-drive-sync config exclude --list # 仪表盘地址 / 端口 / 并发数 proton-drive-sync config dashboard-host 127.0.0.1 proton-drive-sync config dashboard-port 4242 proton-drive-sync config concurrency 8

其中sync-dir --add要求本地目录必须已存在；--remote指定该目录同步到 Proton Drive 上的哪个远端根目录（默认/）。完整实现见 src/cli/config.ts。

📊 status / stop / logs：状态、停止与排错三件套

# 查看运行状态（JSON 格式，含 running/stopped、paused、端口） proton-drive-sync status # 输出示例：{"status":"running","paused":false,"port":4242} # 优雅停止（发送 stop 信号并等待进程退出，最多等 15 秒） proton-drive-sync stop # 查看日志 / 实时跟踪日志 proton-drive-sync logs proton-drive-sync logs -f proton-drive-sync logs clear

status命令输出纯 JSON，方便脚本判断同步服务是否存活；logs -f等价于tail -f，是排错时的第一选择。源码分别位于 src/cli/status.ts、src/cli/stop.ts、src/cli/logs.ts。

🛠️ service 命令：安装开机自启系统服务

service子命令用于把 Proton Drive Sync 注册为系统服务（macOS 使用 launchd，Linux 使用 systemd），实现开机自启：

proton-drive-sync service install # 安装并启动系统服务 proton-drive-sync service install --install-scope system # Linux 可选 system 级 proton-drive-sync service load # 加载服务 proton-drive-sync service unload # 卸载加载（重启后重新加载） proton-drive-sync service uninstall # 停止并卸载服务 proton-drive-sync service uninstall -y # 跳过确认

服务模板文件可直接查看：proton-drive-sync.service（Linux systemd）与 proton-drive-sync.plist（macOS launchd）。

🧹 reset 命令：重置同步状态的两种方式

# 交互式重置菜单 proton-drive-sync reset

交互式菜单提供三个选项：

Reset sync state：清空同步状态数据库，强制所有文件像首次安装一样重新全量同步；
Clear retry delays：清除失败任务的退避延迟，让它们立即重试；
Clear signals：清空进程间信号队列。

# 彻底清除一切：卸载服务、删除凭据、配置和同步历史（不可逆！） proton-drive-sync reset --purge

⚠️--purge是"卸载前的最后一步"，执行后所有本地数据都会被删除，请务必确认。源码见 src/cli/reset.ts。

🧭 新手标准工作流（记住这 5 步就够）

安装后：proton-drive-sync setup（向导会带你在其中完成 auth 与服务安装）
加目录：proton-drive-sync config sync-dir --add ~/Documents
开同步：proton-drive-sync start
看状态：proton-drive-sync status，有问题就proton-drive-sync logs -f
临时停一下：proton-drive-sync pause，需要时再proton-drive-sync resume

❓ 常见问题 FAQ

Q：start提示 "Another instance is already running"？先执行proton-drive-sync stop停掉旧实例。

Q：reconcile报错 "No running daemon found"？说明守护进程没在跑，先proton-drive-sync start。

Q：怎么确认当前是否暂停了？proton-drive-sync status输出中的paused字段，true表示已暂停。

Q：如何调试网络或认证问题？加全局参数--debug打开调试日志；--sdk-debug还能打开 Proton SDK 层日志（必须与--debug同时使用，否则会报--sdk-debug requires --debug）。

结语

以上就是Proton Drive Sync CLI 命令速查表的全部内容：setup完成首次配置、auth登录授权、start/stop控制同步、pause/resume临时挂起、reconcile全量对齐、config管理目录与排除规则、reset重置状态。建议把本文收藏备用，配合proton-drive-sync --help随时查阅，即可流畅管理你的 Proton Drive 自动同步。