Proton Drive Sync Dashboard 完全指南：本地 4242 端口实时监控队列、暂停与统计

Proton Drive Sync 是一款免费的非官方同步客户端，它把本地文件夹自动、持续地同步到 Proton Drive 加密网盘。除了命令行，它还内置了一个功能强大的 Web Dashboard——启动服务后，浏览器打开http://localhost:4242即可实时监控同步队列、统计卡片、暂停/恢复同步并查看实时日志，是新手掌控同步进程的「驾驶舱」。

Dashboard 是什么？为什么默认跑在 4242 端口

Dashboard 是 Proton Drive Sync 内置的 Web 管理面板，默认监听127.0.0.1:4242（端口号 4242 定义在 src/config.ts 的DEFAULT_DASHBOARD_PORT中，默认主机为127.0.0.1）。

它的工作方式很巧妙：

• 执行proton-drive-sync start启动同步时，主进程会派生一个独立的 Dashboard 子进程（见 src/dashboard/server.ts）；
• 主进程每 1.5 秒向面板发送一次状态心跳，若 90 秒内没有心跳，面板会显示「Disconnected」（见 src/dashboard/server.ts）；
• 页面通过 SSE（Server-Sent Events）推送 HTML 片段实现秒级刷新，无需手动刷新浏览器（实现位于 src/dashboard/app.ts 的/api/events接口）。

💡 如果你在 Docker 里运行，面板默认绑定0.0.0.0:4242以便容器端口映射，官方 compose 文件同样映射了 4242 端口（docker/docker-compose.yml）。

一键打开步骤：如何快速访问 Proton Drive Sync Dashboard

只需 3 步：

1. 登录账号：proton-drive-sync auth
2. 启动同步服务：proton-drive-sync start
3. 打开浏览器：访问http://localhost:4242

首次使用时，页面会先进入/controls引导流程：添加本地同步目录、设置并发数，完成后跳转到首页。如果服务没在运行，终端执行proton-drive-sync status会返回 JSON 状态，其中port字段就是当前面板端口（src/cli/status.ts）。

首页解读：4 个统计卡片 + 5 个同步队列

首页（src/dashboard/home.html.txt）是信息密度最高的一页，自上而下依次是：

统计卡片：一眼看懂同步进度

顶部 4 张卡片实时展示：

数据由数据库单条聚合查询得出，性能开销极低（src/sync/queue.ts 的getJobCounts），UI 渲染见 src/dashboard/views/fragments/Stats.tsx。

卡片下方是Tracked Paths区域，列出每个「本地路径 → 云端根目录」的映射，方便确认哪些目录正在被追踪。

五大同步队列：Pending / Processing / Recent / Retry / Blocked

• Pending Transfers：已排队等待上传的任务；
• Active Transfers：正在传输的文件，头部带一个Pause Sync按钮（src/dashboard/views/fragments/PauseButton.tsx）；
• Recently Synced：最近成功同步的记录；
• Retry Queue：失败后按指数退避自动重试的任务，每项带倒计时，还能点Retry All Now按钮立即全部重试（src/sync/queue.ts 的retryAllNow）；
• Blocked Jobs：重试耗尽被阻塞的任务，会显示具体报错，便于定位权限、路径缺失等问题。

每个队列最多展示 100 条（src/dashboard/app.ts 的QUEUE_DISPLAY_LIMIT），避免大目录同步时页面卡顿。

一键暂停与恢复：3 种方式控制同步

暂停是新手最常问的问题，面板提供了三种方式：

1. 首页顶部按钮：点「Pause Sync」，按钮变绿「Resume Sync」，状态徽章同步变为琥珀色 Paused；
2. Controls 页：/controls路由下同样有暂停卡片和Stop（完全停止服务）按钮；
3. 命令行：proton-drive-sync pause与proton-drive-sync resume（src/cli/pause.ts、src/cli/resume.ts）。

暂停期间进程不会退出，任务只是挂起——状态切换逻辑见 src/dashboard/app.ts 的/api/toggle-pause接口。页面上方的状态徽章有三种颜色：绿色 Connected、琥珀色 Paused、红色 Disconnected，一眼判断服务是否健康。

实时日志面板：不出浏览器定位同步报错

首页底部是可折叠的Live Logs区域，通过 SSE 增量推送 sync.log 新内容，无需重启、无需翻终端：

• 支持DBG / INF / WRN / ERR四级日志过滤，排查问题时切到 DBG 即可（src/dashboard/home.html.txt）；
• 错误行红色高亮、警告行琥珀色，扫一眼就能抓到异常；
• 首次打开只回显最近 500 行，不会刷屏。

Controls 页：改并发、加同步目录、设置开机自启

/controls页是面板的「设置中心」（src/dashboard/controls.html.txt）：

• Sync Concurrency：1~16 的滑杆，控制同时传输的文件数，默认 4；
• Sync Directories：弹窗添加「本地路径 + 云端根目录」，自动写入配置文件并热加载，无需重启；
• Start on Login：一键开关开机自启服务；
• Shut Down：停止整个同步服务，之后用proton-drive-sync start重新拉起。

所有修改最终落盘到~/.config/proton-drive-sync/config.json，并发送config:check信号触发热重载（src/config.ts）。

进阶用法：JSON API 与脚本集成

面板自带一组 JSON 接口，方便写脚本做监控告警：

路由实现见 src/dashboard/app.ts。例如curl http://localhost:4242/api/stats就能拿到{"pending":3,"processing":1,"synced":12,...}，配合 cron 就能做「同步卡住报警」。

⚠️安全提示：默认绑定127.0.0.1只对本机开放。若把dashboard_host改成0.0.0.0暴露到局域网，面板可以停服务、改配置，请务必确保网络可信或配置防火墙——代码中也会主动打印安全警告（src/dashboard/app.ts）。想换端口，改config.json的dashboard_port即可。

常见问题（FAQ）

Q：打开 4242 端口显示「Disconnected」？A：说明同步主进程没在运行或已掉线。先执行proton-drive-sync status确认状态为running，否则重新proton-drive-sync start。

Q：Blocked 队列一直有任务怎么办？A：查看该任务的错误详情，常见原因是本地路径不存在、云端重名冲突或认证过期（重新proton-drive-sync auth）。网络类错误会无限退避重试，非网络类错误重试次数有限后转 Blocked。

Q：想完整体验一遍流程？A：项目自带的演示视频可以参考 readme_assets/demo.mp4。

总结

Proton Drive Sync 的 Dashboard 把「同步到哪了、卡在哪、怎么控制」三件事全部搬进了浏览器：4242 端口打开即是监控大屏，统计卡片看进度、五大队列看细节、Pause 按钮管节奏、Live Logs 查报错，再配合 JSON API 和 Controls 页，新手也能像管理专业网盘客户端一样自如操作。配合加密网盘 Proton Drive，本地备份从此既透明又安心。