Skip to content

v2.2.3

Choose a tag to compare

View all tags
@github-actions github-actions released this 03 Sep 06:36
· 52 commits to main since this release
v2.2.3
3a423fc

BaiduPCS-Rust v2.2.3 发行说明

发布日期：2026-09-03

🎯 版本说明

v2.2.3 是在 v2.2.2 基础上的维护版本，对应 issue #156，只做两件事，都在下载侧：

  • 修复文件夹下载重复计数、永远完不成、同一批文件反复重下：完成数按每次新建任务的 UUID 去重，进度会冲过 100%，文件夹卡在 downloading 无限补任务。实测 1041 个文件数成 5337、18.4GB 数成 94.5GB，用户烧掉约 100GB 流量。建议所有用户升级。
  • 修复「部分数据」续传黏在坏链接上：CDN 每次只吐几 KB 就断时，分片会永远黏在同一条坏链接上磨；目标文件被重置时裸减法还会回绕，把零字节失败当成「有进展」，从分片头重下已下过的区间。

✅ 平滑升级：本版本不涉及任何不兼容的数据迁移，从 v2.2.2 升级无感知。仍建议升级前按惯例备份数据目录（见下方「升级说明」）。

🐛 文件夹完成计数按 task_id 去重导致无限重下（重要）

问题：文件夹下载的完成计数原本按 task_id 去重，而 task_id 是每次建任务新生成的 UUID。同一个文件只要被重新建成子任务——重启后对账失效、跳过分支没从队列摘掉、失败重入队等——就会再 +1，并把 file_size 再累加进 completed_downloaded_size。

于是：

真实情况 界面上看到的
1041 个文件 5337 个已完成
18.4 GB 94.5 GB 已下载
进度冲过 100% 文件夹永远停在 downloading

因为终态判定用的是 completed_count == total_files，一旦冲过就永远不可能相等，失败终态又要求 failed_count > 0 也进不去。文件夹于是无限补任务，同一批文件反复重下。用户实测烧掉约 100GB 流量。

同一套「按 task_id 记账」还带出另外两处症状：

  • 幽灵失败：任务 A 耗尽重试被判死，同一文件的任务 B 后来下成了，按 task_id 抵消不掉 A 的那笔失败。文件都在盘上，文件夹却以「N 个文件下载失败」收场。
  • 跳过计数膨胀：命中「跳过」的文件只从候选里挑出来、不从 pending_files 摘掉，又不建任务、等不到落盘回调，会被反复选中重复跳过，skipped_count 越算越大。

修复：去重键换成百度侧稳定的文件身份 fs_id（fs_id == 0 的异常数据退回按 task_id，宁可多计也不少计），并随文件夹快照持久化——重启后上次已下完的文件再被建成子任务也不会重新计数。老快照没有 counted_fs_ids 字段时反序列化为空集合，不阻断升级。

失败计数同样按 fs_id 记账：同一文件「任务 A 判死 → 任务 B 下成」时能抵消那笔幽灵失败。跳过分支必须从 pending_files 摘掉。终态判定从 == 改成 >=，防止虚高把文件夹永久卡死；「待办已空但子任务还在跑」时不再提前判终态，避免把正在下的任务连锅端。

去重挡住的是重复计数。如果仍有路径把已完成文件重新排进补任务队列，那一遍下载还是会烧流量——现补了可 grep 的观测日志，真出现了就照着 fs_id 追是哪条路径干的。

🐛 「部分数据」续传黏在坏链接上耗尽流量（重要）

问题：分片内断点续传把「本轮写下了部分字节」当成链接仍可用：不计重试、不换链接。正常断流后续传是对的。

但百度 CDN 抽风时每次只吐几 KB 就断，分片会以 500ms 一轮永远黏在同一条坏链接上磨，retries 永远到不了上限。用户观感是任务卡死，流量却在持续空转。

更糟的是续传安全校验：目标文件缺失或长度不足时会把 bytes_downloaded 重置为 0。本轮结束值可能小于开始时记下的 bytes_before。裸减法在 release（overflow-checks 默认关闭）下回绕成天文数字，一次零字节失败被误判成「下到了部分数据」——既不计重试也不换链接，还会从分片头重下已下过的区间。这就是 issue #156 的流量黑洞。

修复：

  1. 用 saturating_sub 算本轮净增，回绕不再发生。
  2. 进度回退也必须写回 ChunkManager（条件从 > 0 改成 !=），否则下一轮从过大的旧偏移再次重置，本轮下的字节全部作废，分片会一直从头重下直到 max_retries 耗尽。
  3. 同一条链接连续 10 轮（约 5 秒）净进展不足 256KB 就强制换链接并计入重试。分片尾巴（剩余不足 256KB）按剩余量取小，避免马上下完的尾巴被误判成「没进展」。换链接时计数器清零，不会让下一条好链接继承上一条坏链接的欠账。

正常断流后续传（一轮至少几百 KB）不受影响；限速账号每轮之间仍有 500ms 间隔，10 轮给了喘息余地。

🔧 升级说明

Docker 用户

# 升级前建议先备份挂载的 data 卷

# 拉取指定版本镜像
docker pull komorebicarry/baidupcs-rust:v2.2.3

# 或使用 latest 标签
docker pull komorebicarry/baidupcs-rust:latest

# 重启容器
docker-compose down && docker-compose up -d

二进制用户

从 Releases 页面下载对应平台的二进制文件，替换原有可执行文件后重启服务。

配置与数据

  • 本版本无破坏性数据迁移，从 v2.2.2 升级无需任何手动操作。文件夹快照新增 counted_fs_ids 字段，老快照缺该字段时按空集合处理。
  • 升级仍建议按惯例备份 backend/config/ 与 backend/wal/（Docker 用户备份挂载的 data 卷）。
  • 默认端口仍为 18888，不影响现有反向代理 / 防火墙 / 书签。
  • 若你此前有文件夹任务进度冲过 100%、一直停在「下载中」、同一批文件反复重下：升级后取消该文件夹任务再重新下载。已落盘的文件走跳过策略即可，不必整夹重来。正在跑、尚未出现重复计数的任务可以直接继续。
  • 「部分数据」续传修复对正在下载的分片即时生效，无需删任务。

📁 下载

平台 文件名
Windows (x86_64) BaiduPCS-Rust-v2.2.3-windows-x86_64.zip
Linux (x86_64) BaiduPCS-Rust-v2.2.3-linux-x86_64.tar.gz
Linux (ARM64) BaiduPCS-Rust-v2.2.3-linux-aarch64.tar.gz
macOS (x86_64) BaiduPCS-Rust-v2.2.3-macos-x86_64.tar.gz
macOS (ARM64) BaiduPCS-Rust-v2.2.3-macos-aarch64.tar.gz
Docker 镜像 BaiduPCS-Rust-v2.2.3-docker.tar.gz

完整更新日志：参见项目根目录的 CHANGELOG.md
问题反馈：欢迎通过 GitHub Issues 进行反馈

Assets 9
Loading