Skip to content

v2.1.4

Choose a tag to compare

View all tags
@github-actions github-actions released this 22 Jul 08:40
· 41 commits to main since this release
v2.1.4
e14fc97

BaiduPCS-Rust v2.1.4 发行说明

发布日期：2026-07-22

🎯 版本说明

v2.1.4 是在 v2.1.3 基础上的小版本更新，聚焦分享同步「抓取阶段」（递归列目录）的健壮性、可观测性与过滤正确性：

  • 抓取进度可观测：分享同步耗时最长的递归列目录阶段不再是「黑盒」，前端实时显示扫描进度与重试提示
  • 抓取更抗抖动：新增建连超时、单请求退避重试、跨整轮重试「续爬」，网络抖动 / 百度限流下更稳更快
  • 过滤失效修复（重要）：修复带 include / exclude 过滤的目录被整目录直传时，被过滤子项仍被连带搬运的问题

✅ 平滑升级：本版本不涉及任何不兼容的数据迁移，从 v2.1.x 升级无感知。run 记录新增 phase 列由程序自动补齐（老库首次启动自动 ALTER TABLE），无需手动操作。仍建议升级前按惯例备份数据目录（见下方「升级说明」）。

✨ 新功能

分享同步·抓取进度可观测

抓取（递归列目录）是分享同步中耗时最长的一段，大分享动辄数百个目录、上百秒。此前这段时间前端只显示「运行中」，用户无法区分「正在爬目录」与「程序卡死」。

  • 实时扫描进度：新增 scan_progress WebSocket 事件（后端约 500ms 节流广播），前端显示「扫描目录中（已扫描 N 个目录 · 待扫描 N · 发现 N 个文件 · 当前目录 …）」。刻意采用计数式文案而非百分比——BFS 待扫描目录数会边爬边增长，百分比只会倒退。
  • 重试可见：整轮抓取因网络异常重试时，明确提示「网络异常，正在第 N 次重试」，并说明已扫描过的目录会直接复用、不会重爬，让用户明白是网络在抖而非程序卡死。

分享同步·运行阶段落库

scan_progress 是瞬时的 WS 事件，页面刷新或 WS 断线重连后即丢失。为此 run 记录新增 phase 字段（scanning / diffing / executing），落库持久化，REST 轮询即可兜底展示细化状态，用户始终能看到「扫描目录中 / 计算差异中 / 转存下载中」而非裸的「运行中」。run 结束后 phase 置空，终态记录不会被误显示为「扫描中」。

🐛 问题修复

分享同步·过滤失效（重要）

问题：当一个目录内部有子项被 include / exclude 过滤规则剔除时，若转存阶段仍把该目录当作单个 fs_id 整目录直传，百度服务端会按 fs_id 递归复制整个目录，连带把本应被过滤掉的子项也一并搬运过去——过滤形同虚设。

修复：抓取阶段标记「有后代被过滤剔除」的存活目录（subtree_pruned），转存阶段拒绝对其整目录直传，改为展开到子节点逐层提交，真正跳过被过滤的分支；而不含被过滤分支的干净兄弟子目录仍保持整目录高效转存。已补充回归测试覆盖。

分享同步·抓取健壮性

  • 建连超时：reqwest 此前未设 connect_timeout，建连阶段沿用系统级 TCP 超时（Windows 上约 21s，失败报 os error 10060）。网络抖动 / 限流时每个失败请求都要白等 21s，递归列目录被整体拖垮。现统一收紧到 8s（可经 BAIDUPCS_CONNECT_TIMEOUT_SECS 覆盖，取值 1~60），连不上即快速失败交给上层重试。
  • 单请求退避重试 + 续爬：单个列目录请求自带退避重试（可经 BAIDUPCS_SHARE_SYNC_LIST_RETRIES / ..._LIST_BACKOFF_MS 调参）；跨「整轮重试」引入目录缓存，把重试从「整棵树重爬」退化为「续爬」剩余目录——大分享既加快重试，又避免请求量翻倍再次撞限流。
  • 错误分类修正：分享页 / 分享列表 / 提取码校验的 send/read 网络层失败（超时 / 连接抖动 / 限流）正确归类为可重试的临时错误，不再误计入「链接确定性失效」自动暂停；真正的链接失效（分享被删 / 提取码错）仍按原逻辑触发暂停。
  • 排障友好：抓取错误保留完整错误链（含底层超时与百度 errno + errmsg），不再只剩最外层笼统文案。

🔧 升级说明

Docker 用户

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

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

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

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

二进制用户

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

配置与数据

  • 本版本无破坏性数据迁移，从 v2.1.x 升级无需任何手动操作（run 记录 phase 列由程序启动时自动补齐）。
  • 升级仍建议按惯例备份 backend/config/ 与 backend/wal/（Docker 用户备份挂载的 data 卷）。
  • 默认端口仍为 18888，不影响现有反向代理 / 防火墙 / 书签。

可选环境变量（本版本新增 / 相关）

变量 默认 说明
BAIDUPCS_CONNECT_TIMEOUT_SECS 8 HTTP 建连超时（秒，取值 1~60，越界回退默认值）
BAIDUPCS_SHARE_SYNC_LIST_RETRIES 3 单个列目录请求的重试次数（设 0 关闭）
BAIDUPCS_SHARE_SYNC_LIST_BACKOFF_MS 800 单请求重试的基础退避（毫秒，第 n 次等待 = base × 2ⁿ）

📁 下载

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

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

Assets 9
Loading