Releases: komorebiCarry/BaiduPCS-Rust
Release list
v2.2.0
BaiduPCS-Rust v2.2.0 发行说明
发布日期：2026-08-10
🎯 版本说明
v2.2.0 是在 v2.1.6 基础上的功能版本，核心是支持百度网盘企业版（apaas）分享转存，并围绕文件夹下载与分享同步做了一轮系统性修复。
- 核心新功能：企业版（apaas）分享转存 ——
pan.baidu.com/apaas/share?surl=...这类链接终于能转存了 - 下载体验：速度与预计剩余时间不再乱跳（感谢 @wlbksy PR #145）；文件夹「跳过」的文件在详情里可见
- 下载正确性：设置页的冲突策略对内部发起的下载真正生效；重启不再重复下载已完成的文件；失败子任务自动重试而不是把整个文件夹卡死
- 分享同步：多个订阅同时跑不再互相抢槽位；重启后接着跑而不是推倒重来
- 转存：网盘空间不足不再被误判成文件数超限空转；普通转存补上分批，超过 500 文件的目录不再直接失败
✅ 平滑升级：本版本不涉及破坏性数据迁移，从
v2.1.x升级无感知。新增的数据库列会在启动时自动补齐（ALTER TABLE ... ADD COLUMN），老数据按默认值兼容。仍建议升级前按惯例备份数据目录（见下方「升级说明」）。
⚠️ 由于本版本新增了数据库列，不建议直接用升级后的数据目录回退到v2.1.x；如需回退请先恢复升级前的备份。
✨ 企业版（apaas）分享转存
百度网盘的企业版分享与个人版是两套互不兼容的体系，端点、鉴权令牌、参数格式全不相同：
| 个人版 | 企业版（apaas） | |
|---|---|---|
| 链接 | pan.baidu.com/s/1xxxx |
pan.baidu.com/apaas/share?surl=xxxx |
| 短链 | surl 要补 1 前缀 |
surl 原样，不能补前缀 |
| 分享页 | HTML 里刨 yunData 片段 |
window.yunData = {...} 干净 JSON |
| 验证提取码 | /share/verify → randsk |
/apaas/api/share/getspwd → spwd |
| 列目录 | /share/list |
/apaas/1.0/share/list |
| 转存 | /share/transfer |
/apaas/1.0/share/transfer |
此前的现象：拿企业版链接去调个人版接口，/s/1<surl> 会命中一个「链接不存在」的错误页，而该错误页里仍嵌着一个无关的 shareid，于是解析看起来「成功」了，后续 /share/verify 却稳定返回 errno=-12——用户看到的是「提取码错误」，怎么试都过不去。
本版本的做法：新增 netdisk::share 策略层，把两套体系的差异收敛到 ShareProvider 的 6 个方法上，公共部分（文件项解析、异步任务轮询节奏、结果提取）复用同一份实现。
- 自动识别：解析链接时判定
ShareKind（personal/apaas），后续走哪套接口由它决定，用户无需做任何选择。 - 凭据通道复用：企业版的
spwd与个人版的randsk语义相同（都是校验提取码后换来的、后续请求要带的凭据），直接复用现有randsk通道，上层无需感知差异。 - 三条路径全覆盖：普通转存、分享直下、分享同步订阅均自动适配。
- 向后兼容：老任务持久化的 JSON 里没有
kind字段，反序列化时退化为个人版，行为与升级前一致。 - 前端：预览接口回包带
kind与token，子目录导航原样回传（企业版的spwd不在 Cookie 里，翻子目录必须带上）。
✨ 更平稳的速度与预计剩余时间
此前的现象：下载速度在 0 / 285 KB/s / 5.2 MB/s 之间反复横跳，ETA 跟着一起跳，完全没法参考。
根因：旧算法是「窗口内字节数 ÷ (now − 最早样本时间)」，分子分母口径不一致。下载按分片落盘，进度回调并非匀速触发——实测出现过「连续 5 秒已下载不动，然后一次跳 256KB」，那一刻窗口里只剩一两个间隔几十毫秒的样本，算出 256KB / 0.05s ≈ 5.2 MB/s，而真实速率只有约 65 KB/s。
改动：
- 存累计值而非增量：速度直接由「两个快照的字节差 ÷ 两个快照的时间差」得出，分子分母取自同一对时间点，天然自洽。
- 固定间隔采样：快照按 500ms 落点，窗口内样本数量有上界，速度不再随回调疏密漂移。
- 跨度不足一秒宁可报 0：不拿几十毫秒的样本外推——那正是分母塌缩的来源。
- 空闲时间参与平均：即使没有新字节也定期落快照，否则下载停滞时最老的快照永远滚不出窗口，速度会一直停在最后那个值不动（实测见过卡在 5.33 MB/s 好几秒）。
- 保留窗口外的基准点：只要第二个快照还在窗口内，第一个就得留着当左端点，否则没法算差值。
合并后做了一轮取舍调整（cfd412c）：独立下载模式不经过分片调度器、没有它的刷新循环兜底，补了一个自带的刷新协程；同时恢复了进度回调里的事件发布路径（文件夹子任务聚合、备份任务通知），避免统一采样把这两条通知漏掉。
✨ 文件夹「跳过」可见
命中冲突策略被跳过的文件不会创建子任务，此前既不出现在下载详情里、也不产生任何事件，用户看到的是「已完成 + 空列表」，甚至无法判断队列是卡住了还是在正常跳过。
- 新增
skipped事件：带group_id，前端据此把跳过归到对应文件夹，实时证明队列在推进。 - 新增聚合字段：
skipped_files/skipped_size与completed_count分开统计，但共同参与终态判定。 - 明细可查：跳过的文件级明细持久化，通过
GET /downloads/folder/:id/skipped单独取回（不塞进列表接口，避免大文件夹响应膨胀），前端合成「跳过」状态行并入详情列表。 - 进度口径修正：整体进度改用
(已下载 + 已跳过) / 总大小——此前一个「全部跳过」的文件夹会显示 0% 却又是「已完成」状态，用户无从判断发生了什么。
🐛 下载·正确性修复
内部发起的下载忽略设置页冲突策略（重要）
问题：用户在设置页选了「跳过」，但离线下载完成后转本地下载、转存完成后自动下载这两条路径照样覆盖本地已有文件，表现为「跳过时灵时不灵」。
根因：HTTP handler 会自己读配置后把策略传进来，但这两条内部路径一直传 None，此前被硬编码兜底成 Overwrite。
修复：策略解析改为三级回退——调用方显式指定 > 设置页全局默认 > Overwrite；配置存引用而非快照，设置页改动即时生效。
重启后重复下载 / 跳过策略失效 / 进度虚高（重要）
三个问题同源于文件夹快照落盘不全：
- 重复下载：已完成的子任务归档后会从活跃集合移走，重启时待处理队列里仍留着它们，于是已下完的文件被重新下载一遍。现按
group_id从历史库查回已成功完成的相对路径集合做对账，剔除后再补任务。 - 跳过策略失效：文件夹的
conflict_strategy未持久化，重启后回落到默认值。现随快照一起落盘。 - 进度虚高：
已下载用max()保证单调性，一旦「已完成子任务之和」与「活跃任务之和」有一次重复累加，虚高值就被永久锁死——实测出现过 30.78 GB / 31.35 GB = 98.2%，而真实下载量只有 17 GB。现封顶到total_size并打告警，把静默的数据损坏变成可定位的信号（total_size == 0表示扫描未完成，此时不封顶）。
跳过统计与明细同时补进已完成文件夹的归档表，重启后不再丢失。
失败重试无上限导致文件夹永不终态（重要）
问题：子任务耗尽分片级 / 链接级 / 调度级重试后直接判死并计入 failed_count，而「恢复文件夹」只接受 Paused/Failed 状态——用户在下载途中对单个失败文件无法做任何操作，只能删掉整个文件夹任务重来。
修复：增加第四层——文件夹层的自动重试（默认上限 3 次）。
- 立即重新入队：放在「释放槽位 + 拉起等待任务」之后，此刻空出的槽位已被排在前面的子任务抢走，本任务只能进等待队列——即「回到队尾」，不会插队。
- 复用原任务（Failed → Pending）而非重建：已下载的分片全部保留，大文件在 90% 处失败不会前功尽弃。
- 刻意不做延迟重试：定时器只存在于内存，服务在退避窗口内重启会把重试整个吞掉（任务永远停在 Failed 无人再管）；立即入队则任务以 Pending 落进 WAL，重启后能正常恢复。
- 重试期间不计入
failed_count：否则已完成 + 已跳过 + 已失败会提前凑满总文件数，重试还没跑文件夹就被判成终态。
同时补齐了重启时失败子任务的恢复路径。
403/404/410 被当成网络抖动反复轰炸
问题：一个 CDN 节点对某文件持续返回 403 时，任务会以 100ms 退避反复重试同一个坏链接，直到连续 6 次分片失败才触发换链接——实测因此卡了 8 分钟才自愈。
根因：错误分类只看「链接是否用尽」，没用尽就一律判 Transient。
修复：永久性 HTTP 错误（403/404/410）直接判 Fatal，并立刻把该链接打入指数退避冷却（10s→40s，复用探测失败那套），链接选择器随即跳过它。
🐛 分享同步
多个订阅同时执行时互相抢槽位（重要）
问题：多个分享同步都显示「在下载」，但交替推进、谁也不快。
根因：发放「文件夹固定任务位」时只校验了「固定位是否已被别的子任务占用」，漏掉了「文件夹自己是否确实持有一个固定位」。文件夹创建时若抢不到槽位（例如只有 1 个任务槽、且已被另一个文件夹以 Normal 优先级持有——Normal 抢不动 Normal），fixed_slot_id 会是 None 且没有任何重试补偿；此时子任务仍带着 uses_folder_fixed_slot=true 被拉起，却不占用任务槽池的任何槽位——直接绕过任务槽上限进入活跃集合。实测日志（1 个任务槽、3 个目录分享同步）：
文件夹 4803c7cd 无法获得固定任务位
→ 分配文件夹固定槽位: folder=4803c7cd, folder_fixed_slot_id=None
→ ⚠️ 活跃任务数 2 超过任务槽上限 1
两个任务随后在分片调度器里 round-robin 瓜分唯一的下载线程，于是谁都很慢。
修复：补上「文件夹自己持有固定位」这一条件，这类子任务会回落到全局槽位分配路径，拿不到就正常进等待队列，等持有者释放后按序拉起。
顺带修正槽位优先级：文件夹下载此前无条件用 Normal，两个后果——① 后台同步占住槽位后用户临时想下载别的文件会被挡住；② 分享同步的文件夹会把同一个订阅里正在跑的单文件下载（Backup）踢下槽位。现在自动备份与分享同步的内部下载归为 Backup（只用空闲槽、不抢占任何在跑的任务、自身可被用户手动下载抢占），只有用户手动发起的文件夹下载才是 Normal。
重启后接着跑，而不是推倒重来（重要）
问题：进程重启后，run 永远停在 Interrupted、基线永远不推进、下一轮全部重做。
根因：等待转存任务的 future 跑在执行栈里，进程一重启就没了。转存任务本身会被恢复、下载监控也会重建，但没有任何东西在等它、给 run 收尾。
修复：新增「续跑接管」。判定能否续跑要三个条件缺一不可——
- 候选快照还在：没有它就无法在收尾时推进基线，续跑的活儿等于白干；
run_items里记着transfer_task_id：这是找回「上一轮在做什么」的唯一线索；- 该订阅还有没下完的下载：注意看的是下载而不是转存任务——转存任务一旦启动了自动下载就会被落盘成 completed 并移入历史库，重启后根本不会被恢复成活跃任务，拿它当判据永远判不出「可续跑」。
接管后唤醒残留下载（重启后都是暂停态，没人拉起就永远不动）、等转存跑完、正常收尾并推进基线。几个细节：
- 接管即把 run 标回
running：启动时只收编running的 run，若留在interrupted，进程再被杀一次这批活儿就成孤儿（实测踩到过：接管跑到一半被杀，重启后一条续跑日志都没有，前端全是暂停）。 - 硬上限兜底：waiter 期间占着该订阅的 in-flight 标记，调度器无法再起新一轮；万一转存任务永远不到终态，没有上限就意味着这个订阅永久停摆。复用与正常 run 相同的 7 天上限（
BAIDUPCS_SHARE_SYNC_TASK_HARD_TIMEOUT_SECS）。
转存记账时机导致续跑判据丢失
transfer_task_id 原来是「等待完成后」才写进 run_items，进程若在下载途中被杀，那个正在跑的任务压根没进 run_items——续跑判据找不到它，只能退化成清理重跑，已下载的进度全部作废。现改为提交成功就先记账（在途状态），成功/失败分支再覆盖成终态。
续跑期间速度不动
正常 run 会启动每秒一帧的 item_progress 广播器，续跑接管路径漏掉了——前端在整个续跑期间收不到任何推送，界面停在接管那一刻不动，只能靠切页面触发 REST 兜底拉取（表现就是「速度不动，切菜单回来才刷新」）。现已补齐，并保证任一退出分支都停掉广播器。
🐛 转存
网盘空间不足被误判为文件数超限（重要）
问题：网盘空间满了以后，分享同步会一路对半拆批重试，每批都因空间不足失败——实测刷出 347 次 errno=-32 仍在原地空转。
根因：百度返回 errno=12 + info[0].errno=-32（剩余空间不足）的这条响应里不带 target_file_nums_limit 字段，旧代码 unwrap_or(0) 后判定「转存文件数 32 超过上限 0」——文案离谱，更糟的是分享同步按「超过上限」把它归类成可二分重试。
修复：-32 在文件数检查之前拦截，归类为 quota_full（资源类错误，拆多小都没用），走早停并提示用户清理空间后手动触发；同时只有响应确实带了 target_file_nums_limit（>0）才做超限判定，避免字段缺失时把任意错误都算成「超过上限 0」。
超过 500 文件的目录直接 errno=12 失败（重要）
问题：百度单次转存有目标文件数上限（默认 500），且按「递归展开后的文件总数」判定，不是按提交的 fs_id 个数——选中一个含 800 个文件的目录只有 1 个 fs_id，照样撞 errno=12。此前只有分享同步侧有拆批，普通转存完全没有。
修复：普通转存补上分批，采用「零请求预拆 + 惰性下钻」两段式：
- 预拆（零请求）：先按父目录分组还原目录结构，再按上限把每组切成多批。只按选中项个数切，一个组里塞了 1200 个文件时必然超限，不用问百度也知道要拆。
- 惰性下钻：选中项是目录时无从判断（1 个
fs_id底下可能有上万文件），真撞上超限了才去爬那一批的子树，用与分享同步同一套拆分函数精确拆分后重提。没超限的转存一路零额外请求。 - 为什么不做主动预扫：要知道一个目录底下有多少文件就得递归列目录，而绝大多数转存根本不到 500——实测选中 99 项含目录时预扫要跑十分钟。
- 共享上下文：目录缓存让多个批次下钻到同一目录时不重复列；限速器让「列目录 + 转存提交」合计受同一个全局 RPS 约束，防
errno=132。 - 临时错误退避重试：
errno=4「请求超时，请稍后再试」这类重试同一批就能过，不该让一次抖动废掉整批（实测批次 2/3 就是这么挂的）。 - 进度分母跟随：下钻把目录展开成子项后分母随之增长，不再出现「转存 34 / 共 8」这种分子大于分母的显示。
混合虚拟根前缀导致目标多一层 /sharelink…/
前端在分享内导航时，不同目录可能拿到不同的 uk（取不到时为 0），于是同一次选择里会混进 /sharelink0-<shareid>/ 和 /sharelink<真实uk>-<shareid>/ 两种前缀——整体剥离随即失效，虚拟根被当成目录名转存出来（用户看到目标位置多出一层 /sharelink…/，实测日志里出现过两次）。现改为逐项各剥各的，混合前缀也能归到同一命名空间；同时以根目录响应里的 uk/shareid 为权威值（分享页常常提取不到 uk，而超限后下钻列子目录必须带正确的 uk）。
跨账号聚合把部分成功显示成全部成功
历史库是全局共享的，非归属账号的 manager 也会从里面捞到同一条任务并重建，而那份重建副本的 transferred_count 是按「全部成功」伪造的；「先到先得」的去重会让伪造副本盖掉真实进度（实测部分成功的任务被显示成 7/7）。现在聚合时先收集内存里的活跃任务。
🔧 工程
- 修复两个既有失败用例：分片测试的构造尺寸必须大于小文件单分片阈值（10MB），否则永远只得到 1 个分片；槽位回收测试改用
checked_sub构造过去时刻，避免开机不足 31 分钟时Instant::now() - 31min直接 panic（overflow when subtracting duration from instant）。
🔧 升级说明
Docker 用户
# 升级前建议先备份挂载的 data 卷
# 拉取指定版本镜像
docker pull komorebicarry/baidupcs-rust:v2.2.0
# 或使用 latest 标签
docker pull komorebicarry/baidupcs-rust:latest
# 重启容器
docker-compose down && docker-compose up -d二进制用户
从 Releases 页面下载对应平台的二进制文件，替换原有可执行文件后重启服务。
配置与数据
- 本版本无破坏性数据迁移，从
v2.1.x升级无需任何手动操作。启动时会自动补齐新增的数据库列（文件夹历史的跳过统计与明细、分享同步快照的run_id），老数据按默认值兼容。 - 由于新增了数据库列，不建议直接用升级后的数据目录回退到
v2.1.x；如需回退请先恢复升级前的备份。 - 升级仍建议按惯例备份
backend/config/与backend/wal/（Docker 用户备份挂载的data卷）。 - 默认端口仍为
18888，不影响现有反向代理 / 防火墙 / 书签。 - 企业版分享无需任何配置，直接粘贴
pan.baidu.com/apaas/share?surl=...链接即可，与个人版分享同一套操作流程。 - 冲突策略：若你此前发现「设置页选了跳过但没生效」，升级后离线下载转本地、转存后自动下载这两条路径会正确遵循设置页的默认策略——如果你原先是靠这个 bug 让内部下载始终覆盖的，请留意行为变化。
- 文件夹子任务自动重试默认 3 次，耗尽才计入失败；升级后此前那些「卡在失败、只能删掉整个文件夹重来」的场景会自动重试恢复。
📁 下载
| 平台 | 文件名 |
|---|---|
| Windows (x86_64) | BaiduPCS-Rust-v2.2.0-windows-x86_64.zip |
| Linux (x86_64) | BaiduPCS-Rust-v2.2.0-linux-x86_64.tar.gz |
| Linux (ARM64) | BaiduPCS-Rust-v2.2.0-linux-aarch64.tar.gz |
| macOS (x86_64) | BaiduPCS-Rust-v2.2.0-macos-x86_64.tar.gz |
| macOS (ARM64) | BaiduPCS-Rust-v2.2.0-macos-aarch64.tar.gz |
| Docker 镜像 | BaiduPCS-Rust-v2.2.0-docker.tar.gz |
🙏 致谢
完整更新日志：参见项目根目录的 CHANGELOG.md
问题反馈：欢迎通过 GitHub Issues 进行反馈
Contributors
Assets 9
v2.1.6
BaiduPCS-Rust v2.1.6 发行说明
发布日期：2026-07-28
🎯 版本说明
v2.1.6 是在 v2.1.5 基础上的小版本更新，聚焦下载与文件操作的稳定性，修复两个「重要」问题：
- 多域双 STOKEN 导致删除等操作报 errno=-6（重要）：
v2.1.5已让 REST 接口一律携带 STOKEN，但扫码登录的多域账号可能在不同域下保存了两个不同值的 STOKEN，全部发出反而命中错误的那个，删除等操作仍报errno=-6（issue #130 追加反馈）。 - 限速/低带宽下载被「24h 绝对超时」误杀（重要）：把「下载慢但仍在推进」的任务误判为失败并清理临时目录，本版本改为进度驱动的停滞判定，正常慢速下载不再被误杀。
✅ 平滑升级：本版本不涉及任何不兼容的数据迁移，从
v2.1.x升级无感知。新增的下载停滞阈值有合理默认值（30 分钟），无需任何手动配置。仍建议升级前按惯例备份数据目录（见下方「升级说明」）。
🐛 问题修复
账号·多域双 STOKEN 导致删除报 errno=-6（重要）
问题：v2.1.5 已让所有 REST 接口的 Cookie 头携带 STOKEN，但部分扫码登录的多域账号仍在删除文件等操作上报 errno=-6。
根因：这类账号在 passport（.baidu.com）与 pan（pan.baidu.com）两个域下各自保存了一份 STOKEN，两者的值可能不同。此前收集 Cookie 时按「整条 k=v 去重」，会把两个域的 STOKEN 一并发出；百度 filemanager 命中了错误的那一个，于是仍返回 errno=-6（对照：BaiduPCS-Go 只发单个 stoken 故正常，见 issue #130）。
修复：
- 按名称去重：收集各域 Cookie 时改为按 cookie 名称去重（保留首次出现），避免多域同名 Cookie 同时进入 Cookie 头。
- 强制 STOKEN 唯一：以登录时保存、已验证可用的
user_auth.stoken为准，清除 jar 中混入的另一域 STOKEN，确保只发出一个正确的 STOKEN。 - PANPSC 覆盖：
PANPSC同样以最新预热值覆盖 jar 中可能存在的多域旧值。 - 可观测：检测到 jar 里出现多个 STOKEN（正是本问题的触发条件）时打印
warn日志，便于上线后从用户日志确认修复路径生效。
下载·限速/低带宽任务被绝对超时误杀（重要）
问题：下载慢（低带宽或被百度限速）但仍在持续推进的任务会被误判为失败，且清理临时目录还会连带导致同批其余「在下」文件报 31066。
根因：旧逻辑是「从下载开始算满 24h 就一刀切判失败」的绝对超时，它只看时间、不看是否仍有字节进展，于是把「慢但正常」的下载也一并杀掉。
修复：改为进度驱动的停滞判定——
- 只认「零进展」：维护「上次观察到的已下载字节总量」与「上次有进展的时刻」；只要字节总和仍在变化就把计时器归零，只有连续
stall_timeout_secs完全无进展才判「停滞」。正常下载即使很慢也会持续有字节增长，永远不会触发；只有真正 0 KB/s 卡死才会被清掉，防卡死能力不丢。 - 用户暂停不计时：只有「有活跃下载」时停滞时钟才累积；用户主动暂停的任务不算活跃，不会被误判为停滞。
- 先取消 worker 再清理：判定停滞后先取消底层下载 worker，再清理临时目录，避免 worker 继续对着即将被清理的临时目录刷
Locate、刷出满屏31066。 - 中性文案：失败提示改为「下载长时间无进展，已判定为停滞并停止；可稍后重试」，只陈述现象与下一步，不臆测会员/带宽等原因。
- 可调阈值：默认停滞阈值 30 分钟，可用环境变量
BAIDUPCS_DOWNLOAD_STALL_TIMEOUT_MINS（取值 > 0）覆盖。
🔧 升级说明
Docker 用户
# 升级前建议先备份挂载的 data 卷
# 拉取指定版本镜像
docker pull komorebicarry/baidupcs-rust:v2.1.6
# 或使用 latest 标签
docker pull komorebicarry/baidupcs-rust:latest
# 重启容器
docker-compose down && docker-compose up -d二进制用户
从 Releases 页面下载对应平台的二进制文件，替换原有可执行文件后重启服务。
配置与数据
- 本版本无破坏性数据迁移，从
v2.1.x升级无需任何手动操作。 - 升级仍建议按惯例备份
backend/config/与backend/wal/（Docker 用户备份挂载的data卷）。 - 默认端口仍为
18888，不影响现有反向代理 / 防火墙 / 书签。 - 若你此前遇到多域账号删除报
errno=-6：升级后直接重试即可；如仍异常，可为该账号重新扫码登录以刷新凭证。 - 下载停滞阈值默认 30 分钟，如你的网络环境正常但有超长时间零进展的场景，可用
BAIDUPCS_DOWNLOAD_STALL_TIMEOUT_MINS调大。
📁 下载
| 平台 | 文件名 |
|---|---|
| Windows (x86_64) | BaiduPCS-Rust-v2.1.6-windows-x86_64.zip |
| Linux (x86_64) | BaiduPCS-Rust-v2.1.6-linux-x86_64.tar.gz |
| Linux (ARM64) | BaiduPCS-Rust-v2.1.6-linux-aarch64.tar.gz |
| macOS (x86_64) | BaiduPCS-Rust-v2.1.6-macos-x86_64.tar.gz |
| macOS (ARM64) | BaiduPCS-Rust-v2.1.6-macos-aarch64.tar.gz |
| Docker 镜像 | BaiduPCS-Rust-v2.1.6-docker.tar.gz |
完整更新日志：参见项目根目录的 CHANGELOG.md
问题反馈：欢迎通过 GitHub Issues 进行反馈
v2.1.5
BaiduPCS-Rust v2.1.5 发行说明
发布日期：2026-07-24
🎯 版本说明
v2.1.5 是在 v2.1.4 基础上的小版本更新，主要解决两个「重要」问题，并完善分享同步排除规则的使用体验：
- 部分账号文件操作报 errno=-6（重要）：修复部分账号登录成功、却在列目录 / 转存 / 上传等一切文件操作上全部
errno=-6的问题——根因是这些账号百度强制 BDUSS + STOKEN 双凭证，而 REST 接口此前只带了 BDUSS。 - 分享同步·include 目录下多层级排除规则失效（重要）：修复用
include圈选目录、再对其深层内容配exclude时排除不生效的问题。 - 排除规则更好用：新增常用词表点选、批量输入（每行一条 / 粘贴多行）与内嵌使用说明。
✅ 平滑升级：本版本不涉及任何不兼容的数据迁移，从
v2.1.x升级无感知。新增的分享同步「常用词表」配置默认为空（老配置文件缺失该段自动视为空），无需手动操作。仍建议升级前按惯例备份数据目录（见下方「升级说明」）。
🐛 问题修复
账号·部分账号文件操作报 errno=-6（重要）
问题：部分账号登录（扫码 / Cookie 导入）成功，随后任何网盘文件操作——列目录、转存、上传、分享同步——都返回 errno=-6（身份校验失败），而 BDUSS 本身经 passport 校验是有效的。
根因：这些账号百度要求 BDUSS + STOKEN 双凭证，pan（REST/xpan）接口只带 BDUSS 时一律返回 errno=-6（见 issue #130）；而此前所有 REST 请求的 Cookie 头都只写了 BDUSS=xxx。
修复：
- Cookie 头统一带 STOKEN：REST 接口的 Cookie 头改由统一构造，只要账号有 STOKEN 就一律带上（
BDUSS=xxx; STOKEN=yyy）；老账号即便多带 STOKEN 也无副作用，因此无差别附加。 - errno=-6 自愈：获取文件列表遇到
errno=-6时，自动触发一次「预热刷新会话」后重试，尽量在用户无感知的情况下恢复。 - 可操作提示：预热重试后仍未恢复的（多为纯 BDUSS 导入、缺少 STOKEN 且无法自动预热出 STOKEN 的账号），如实返回可操作提示——请通过「添加账号」重新扫码登录，或重新导入包含 STOKEN 的完整 Cookie 后重试。
分享同步·include 目录下多层级排除规则失效（重要）
问题：当订阅用 include 圈选某个目录、再对该目录下的深层子内容配置 exclude 排除规则时，排除不生效——被排除的深层内容仍被转存 / 下载。
根因：抓取阶段的 BFS 在判断「某目录是否需要继续深入」时，只认「该目录是某个 include_path 自身或其祖先」，漏掉了「该目录是某个 include 目录的后代」这一支。于是 BFS 在 include 目录下一层就截断，深层内容从未被扫描，exclude 过滤与 subtree_pruned 标记都无从发生；后续整目录 fs_id 直传时，百度服务端又把被排除的深层内容原样递归复制回来。
修复：把「dir 是某个 include 目录的后代 → 用户圈选的是整棵子树，必须继续深入」这一判断补齐到抓取阶段的三处同款逻辑（dir_allowed / item_allowed / dir_needs_more_pages），使三者语义一致，多层级排除规则恢复生效（issue #128 追加反馈）。已补充单元测试覆盖。
✨ 新功能
分享同步·排除规则常用词表
创建 / 编辑订阅时，排除规则不必每次重复手输：
- 点选快速添加：维护一份排除规则「常用词表」，编辑订阅时点一下即可加入当前规则。
- 存为常用：把当前订阅正在用的规则一键存入词表，方便下次复用。
- 在系统设置维护：词表的增删在系统设置 → 分享同步中进行。默认为空、不做任何预置，完全由用户自行配置（老配置文件缺失该段自动视为空词表）。
分享同步·排除规则批量输入
排除规则输入框支持一次添加多条：每行一条（输入一条按回车，或直接粘贴多行文本后添加）。逗号、空格等标点不作分隔——它们可能是文件名 / 路径的一部分。
分享同步·排除规则使用说明
内嵌可展开的「使用说明」帮助面板（订阅编辑器与系统设置页共用同一份文案，避免两处漂移），讲清规则要点：
- 规则匹配的是完整路径（相对分享根目录），不只是文件名，且区分大小写；
- 通配符
*匹配任意字符（可跨目录层级），?匹配单个字符； - 文件夹路径命中规则时，该文件夹及其中全部内容一起排除；
- 按关键词
*关键词*、按扩展名*.格式（如*.nfo）；大小写不同的写法需各加一条（如*.mkv与*.MKV）。
🔧 升级说明
Docker 用户
# 升级前建议先备份挂载的 data 卷
# 拉取指定版本镜像
docker pull komorebicarry/baidupcs-rust:v2.1.5
# 或使用 latest 标签
docker pull komorebicarry/baidupcs-rust:latest
# 重启容器
docker-compose down && docker-compose up -d二进制用户
从 Releases 页面下载对应平台的二进制文件，替换原有可执行文件后重启服务。
配置与数据
- 本版本无破坏性数据迁移，从
v2.1.x升级无需任何手动操作（分享同步「常用词表」配置默认为空，老配置文件自动兼容）。 - 升级仍建议按惯例备份
backend/config/与backend/wal/（Docker 用户备份挂载的data卷）。 - 默认端口仍为
18888，不影响现有反向代理 / 防火墙 / 书签。 - 若你此前遇到部分账号
errno=-6：升级后请为受影响账号重新扫码登录、或重新导入包含 STOKEN 的完整 Cookie，以便新逻辑携带双凭证。
📁 下载
| 平台 | 文件名 |
|---|---|
| Windows (x86_64) | BaiduPCS-Rust-v2.1.5-windows-x86_64.zip |
| Linux (x86_64) | BaiduPCS-Rust-v2.1.5-linux-x86_64.tar.gz |
| Linux (ARM64) | BaiduPCS-Rust-v2.1.5-linux-aarch64.tar.gz |
| macOS (x86_64) | BaiduPCS-Rust-v2.1.5-macos-x86_64.tar.gz |
| macOS (ARM64) | BaiduPCS-Rust-v2.1.5-macos-aarch64.tar.gz |
| Docker 镜像 | BaiduPCS-Rust-v2.1.5-docker.tar.gz |
完整更新日志：参见项目根目录的 CHANGELOG.md
问题反馈：欢迎通过 GitHub Issues 进行反馈
v2.1.4
BaiduPCS-Rust v2.1.4 发行说明
发布日期：2026-07-22
🎯 版本说明
v2.1.4 是在 v2.1.3 基础上的小版本更新，聚焦分享同步「抓取阶段」（递归列目录）的健壮性、可观测性与过滤正确性：
- 抓取进度可观测：分享同步耗时最长的递归列目录阶段不再是「黑盒」，前端实时显示扫描进度与重试提示
- 抓取更抗抖动：新增建连超时、单请求退避重试、跨整轮重试「续爬」，网络抖动 / 百度限流下更稳更快
- 过滤失效修复（重要）：修复带
include/exclude过滤的目录被整目录直传时，被过滤子项仍被连带搬运的问题
✅ 平滑升级：本版本不涉及任何不兼容的数据迁移，从
v2.1.x升级无感知。run 记录新增phase列由程序自动补齐（老库首次启动自动ALTER TABLE），无需手动操作。仍建议升级前按惯例备份数据目录（见下方「升级说明」）。
✨ 新功能
分享同步·抓取进度可观测
抓取（递归列目录）是分享同步中耗时最长的一段，大分享动辄数百个目录、上百秒。此前这段时间前端只显示「运行中」，用户无法区分「正在爬目录」与「程序卡死」。
- 实时扫描进度：新增
scan_progressWebSocket 事件（后端约 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 进行反馈
v2.1.3
BaiduPCS-Rust v2.1.3 发行说明
发布日期：2026-07-10
🎯 版本说明
v2.1.3 是在 v2.1.2 基础上的小版本更新：新增文件与下载列表排序能力，并修复了快速切换目录时文件夹偶发无法打开的问题。
- 列表排序：网盘 / 本地文件列表点击表头排序（
name/time/size，升 / 降序），下载页新增排序控件与状态筛选栏（含各状态计数） - 文件管理修复：快速切换目录时的并发竞态，过期响应不再覆盖当前目录、文件夹偶发无法打开
✅ 平滑升级：本版本不涉及任何不兼容的数据迁移，从
v2.1.x升级无感知。仍建议升级前按惯例备份数据目录（见下方「升级说明」）。
✨ 新功能：文件与下载列表排序
- 网盘 / 本地文件排序：文件管理页与本地文件页支持点击表头对 文件名 / 修改时间 / 大小 排序，排序字段（
name/time/size）与升降序透传后端，配合分页在大目录下也能拿到全局有序结果，而非仅对当前页排序。 - 下载列表排序 + 状态筛选：下载管理页新增排序控件与状态筛选栏——可按状态（下载中 / 等待 / 已完成 / 失败 / 暂停等）过滤，筛选栏内联显示各状态任务计数，在任务量大时快速定位目标任务。
🐛 问题修复
- 文件管理·目录切换偶发打不开：快速切换目录时，目录切换与分页加载两条异步链路并发，较晚返回的过期响应可能覆盖当前目录内容，表现为文件夹偶发无法打开。现在对返回结果按当前路径 / 请求序号校验，过期响应直接丢弃。
🔧 升级说明
Docker 用户
# 升级前建议先备份挂载的 data 卷
# 拉取指定版本镜像
docker pull komorebicarry/baidupcs-rust:v2.1.3
# 或使用 latest 标签
docker pull komorebicarry/baidupcs-rust:latest
# 重启容器
docker-compose down && docker-compose up -d二进制用户
从 Releases 页面下载对应平台的二进制文件，替换原有可执行文件后重启服务。
配置与数据
- 本版本无破坏性数据迁移，从
v2.1.x升级无需任何手动操作。 - 升级仍建议按惯例备份
backend/config/与backend/wal/（Docker 用户备份挂载的data卷）。 - 默认端口仍为
18888，不影响现有反向代理 / 防火墙 / 书签。
📁 下载
| 平台 | 文件名 |
|---|---|
| Windows (x86_64) | BaiduPCS-Rust-v2.1.3-windows-x86_64.zip |
| Linux (x86_64) | BaiduPCS-Rust-v2.1.3-linux-x86_64.tar.gz |
| Linux (ARM64) | BaiduPCS-Rust-v2.1.3-linux-aarch64.tar.gz |
| macOS (x86_64) | BaiduPCS-Rust-v2.1.3-macos-x86_64.tar.gz |
| macOS (ARM64) | BaiduPCS-Rust-v2.1.3-macos-aarch64.tar.gz |
| Docker 镜像 | BaiduPCS-Rust-v2.1.3-docker.tar.gz |
完整更新日志：参见项目根目录的 CHANGELOG.md
问题反馈：欢迎通过 GitHub Issues 进行反馈
v2.1.2
BaiduPCS-Rust v2.1.2 发行说明
发布日期：2026-06-30
🎯 版本说明
v2.1.2 是在 v2.1.1 基础上的维护版本，内容以分享同步批量下载可靠性与下载引擎收尾/续传修复为主：大目录分享同步支持整批 submit 合并任务、本地目标自动补同步，并修复断点续传在文件被截断时写出稀疏空洞、以及任务 100% 后双 finalize 竞争导致误报与文件损坏等问题。
- 分享同步·批量下载：≥2 文件走整批 submit（N→1 任务），batch 失败退化为逐文件；同步前校验本地缺失/大小不一致文件并自动补下载
- 下载·续传安全：恢复时目标文件缺失或截断则重置分片进度，避免损坏文件被误标完成
- 下载·收尾竞争：修复 100% 后双 finalize 抢同一临时文件；收尾窗口暂停也作废旧 epoch；明文文件不再误报「解密失败」
- 错误提示：分享链接
errno=-9明确为「分享链接失效或提取码错误」
✅ 平滑升级：本版本不涉及任何不兼容的数据迁移，从
v2.1.1升级无感知。仍建议升级前按惯例备份数据目录（见下方「升级说明」）。
✨ 分享同步·批量下载可靠性
- 整批 submit 合并任务：组内文件数 ≥2 时走
submit_transfer_batch/submit_download_batch，将 N 次转存/下载任务合并为 1 次（transfer 内部按父目录分 batch），大目录场景显著减少任务数与鉴权开销；batch 提交失败时自动退化为逐文件 submit，quota / 本地磁盘满等边界场景不误伤整组。 - 本地目标自动补同步：同步前扫描本地目标目录，将「快照未变但本地文件缺失或大小不一致」的条目纳入
modifieddiff 重新下载，避免上次中断留下的半成品被误判为已同步。 - 分片下载兜底：大批量文件夹下载中，失败清理/重试竞态可能删掉半成品文件或其父目录；分片线程在写入前自动
create_dir_all父目录，避免单个缺失目录拖垮整批分享同步。 - 错误分类增强：临时性服务端超时等关键字纳入
Transient分类，分享同步可正确自动重试；errno=-9提示改为「分享链接失效或提取码错误」，便于用户区分链接问题与网络抖动。
🐛 下载引擎修复
- 断点续传安全校验：恢复下载时，若分片已记录进度但目标文件缺失或长度不足（常见于大批量下载中失败清理/重试竞态），现重置该分片进度从头重下——避免
create(true)+seek续传在文件前段写出全 0 稀疏空洞，却被仅按文件大小判定的完成校验误标为成功。 - 双 finalize 竞争（任务 100% 后）：
- 引入
finalize_spawned原子门闩，防止两个收尾协程并发 rename/解密同一临时文件导致误报失败或产出损坏文件。 - 文件夹恢复时「无可用槽位」早退分支也复位
finalize_spawned，避免状态残留阻塞后续调度。 - 收尾窗口（
finalize_spawned=true但尚未进入Decrypting）内暂停也递增decrypt_epoch作废旧协程，与cancel_tasks_by_group的 epoch 失效逻辑对齐。
- 引入
- 明文误报文案：明文文件收尾阶段只有 rename、不走解密，统一拼成「解密失败」会误导用户；现仅加密文件报「解密失败」，明文一律报「文件收尾失败」。
🔧 工程
- 新增分享同步诊断脚本（
scripts/目录）：share_sync_probe.py— 探测分享链接可达性与快照抓取share_sync_status.py— 查看订阅/运行状态share_sync_restore_snapshot.py— 快照恢复工具
🔧 升级说明
Docker 用户
# 升级前建议先备份挂载的 data 卷
# 拉取指定版本镜像
docker pull komorebicarry/baidupcs-rust:v2.1.2
# 或使用 latest 标签
docker pull komorebicarry/baidupcs-rust:latest
# 重启容器
docker-compose down && docker-compose up -d二进制用户
从 Releases 页面下载对应平台的二进制文件，替换原有可执行文件后重启服务。
配置与数据
- 本版本无破坏性数据迁移，从
v2.1.1升级无需任何手动操作。 - 升级仍建议按惯例备份
backend/config/与backend/wal/（Docker 用户备份挂载的data卷）。 - 默认端口仍为
18888，不影响现有反向代理 / 防火墙 / 书签。
📁 下载
| 平台 | 文件名 |
|---|---|
| Windows (x86_64) | BaiduPCS-Rust-v2.1.2-windows-x86_64.zip |
| Linux (x86_64) | BaiduPCS-Rust-v2.1.2-linux-x86_64.tar.gz |
| Linux (ARM64) | BaiduPCS-Rust-v2.1.2-linux-aarch64.tar.gz |
| macOS (x86_64) | BaiduPCS-Rust-v2.1.2-macos-x86_64.tar.gz |
| macOS (ARM64) | BaiduPCS-Rust-v2.1.2-macos-aarch64.tar.gz |
| Docker 镜像 | BaiduPCS-Rust-v2.1.2-docker.tar.gz |
完整更新日志：参见项目根目录的 CHANGELOG.md
问题反馈：欢迎通过 GitHub Issues 进行反馈
v2.1.1
BaiduPCS-Rust v2.1.1 发行说明
发布日期：2026-06-24
🎯 版本说明
v2.1.1 是在 v2.1.0（分享同步）基础上的维护版本，内容以优化与 Bug 修复为主：修复扫码登录在确认环节失败时被降级成假「临时用户」、系统设置页导航把顶部保存栏顶出可视区，并完善了分享同步的稳定性（手动触发、调度器、下载等待、历史数据归属），同时新增分享同步的运行明细分页与下载停滞自动重试两项增强。
- 登录修复：扫码登录确认失败不再伪造
uid=0「临时用户」，避免假登录导致后续网盘 API 全部errno=-6 - 界面修复：系统设置左侧导航点击不再把顶部「保存设置」栏顶出可视区
- 分享同步·稳定性：手动触发返回真实
run_id（不再假成功）、调度器不再静默吞错、下载等待改「空闲超时 + 硬上限」、owner_uid=0历史数据启动期迁移 - 分享同步·增强：运行明细分页接口（大 run 不再截断到 100 条）、下载停滞自动重试（
pause→冷却→resume）
✅ 平滑升级：本版本不涉及任何不兼容的数据迁移，从
v2.1.0升级无感知。仍建议升级前按惯例备份数据目录（见下方「升级说明」）。
🐛 登录与界面修复
- 扫码登录·不再伪造临时用户：扫码登录在「确认环节」失败或拿不到真实 uid 时，过去会被降级成
uid=0、用户名「临时用户」的假「成功」，导致前端显示已登录、但实际会话不完整，调用任意网盘 API 都返回errno=-6。现改为如实返回失败并提示重新扫码；同时增加uid=0守卫，杜绝假登录账号落库。 - 系统设置·导航不再顶出保存栏：点击左侧锚点导航（如「下载」）时改为只滚动内容容器，不再连带滚动外层把顶部「保存设置」栏顶出可视区。
✨ 分享同步·稳定性与增强
- 手动触发：触发前做前置校验并返回真实
run_id，不再「假成功」；前端可凭run_id立即定位本次运行。 - 调度器不吞错：定时
on_tick改为返回Result，失败落warn日志便于排查，不再静默丢弃错误。 - 下载等待：等待逻辑改为「空闲超时 + 硬上限」双闸——空闲超时按「有无进展」判定（避免大文件下到一半被误杀），硬上限兜底；文件夹聚合速度改用「活跃下载状态」判断，修复进行中速度恒显示 0。
- 历史数据归属：启动期对
owner_uid=0的历史脏数据按当前活跃账号迁移归属。
- 运行明细分页：新增
GET /share-sync/runs/:id/items分页接口（count+ 分页查询），前端运行详情弹窗接入分页，避免大 run 明细被截断到 100 条。 - 下载停滞自动重试：检测到下载长时间无进展时，自动
pause →冷却→ resume重启该下载（限次数 + 冷却，可经环境变量调参），减少卡死需人工干预的情况。
下游补充修复：
- 修复为「立即返回
run_id」预建 run 的设计所引入的孤儿 run——并发去重命中、链接失效、账号未就绪等早退路径在绑定run_id前返回、未收尾，导致 run 永久卡running；现各早退路径均收尾为失败。 - 修复
resume_link_invalid的状态不一致——恢复链接失效后「立即触发一次」失败时不再影响恢复接口返回（降级为只记日志）。
🔧 工程 / CI
- 统一 Rust 工具链版本为
1.87（本地 / Docker / CI 一致）。 - 增加 Conventional Commits 校验（PR 标题 + 逐 commit）。
🔧 升级说明
Docker 用户
# 升级前建议先备份挂载的 data 卷
# 拉取指定版本镜像
docker pull komorebicarry/baidupcs-rust:v2.1.1
# 或使用 latest 标签
docker pull komorebicarry/baidupcs-rust:latest
# 重启容器
docker-compose down && docker-compose up -d二进制用户
从 Releases 页面下载对应平台的二进制文件，替换原有可执行文件后重启服务。
配置与数据
- 本版本无破坏性数据迁移，从
v2.1.0升级无需任何手动操作。 - 升级仍建议按惯例备份
backend/config/与backend/wal/（Docker 用户备份挂载的data卷）。 - 默认端口仍为
18888，不影响现有反向代理 / 防火墙 / 书签。
📁 下载
| 平台 | 文件名 |
|---|---|
| Windows (x86_64) | BaiduPCS-Rust-v2.1.1-windows-x86_64.zip |
| Linux (x86_64) | BaiduPCS-Rust-v2.1.1-linux-x86_64.tar.gz |
| Linux (ARM64) | BaiduPCS-Rust-v2.1.1-linux-aarch64.tar.gz |
| macOS (x86_64) | BaiduPCS-Rust-v2.1.1-macos-x86_64.tar.gz |
| macOS (ARM64) | BaiduPCS-Rust-v2.1.1-macos-aarch64.tar.gz |
| Docker 镜像 | BaiduPCS-Rust-v2.1.1-docker.tar.gz |
完整更新日志：参见项目根目录的 CHANGELOG.md
问题反馈：欢迎通过 GitHub Issues 进行反馈
Contributors
Assets 9
v2.1.0
BaiduPCS-Rust v2.1.0 发行说明
发布日期：2026-06-15
🎯 版本说明
v2.1.0 是在 v2.0.0（多账号）基础上的功能版本，核心是引入全新的**分享同步（Share Sync）**能力，并带来一批围绕分享同步的稳定性、进度显示与风控修复，以及 Windows 控制台日志乱码修复。
- 核心新功能：分享同步（Share Sync）——订阅分享链接，周期 / 定时拉取并与上次快照对比差异，自动转存到网盘和 / 或下载到本地
- 稳定性：增量同步只同步变动文件、转存撞同名继续下载、重启自动续跑被中断的 run、删除订阅清理孤儿任务
- 进度显示：修复文件夹下载已下载翻倍（200%）与上传超过 100%，全站进度条统一钳到
[0,100] - 风控：列目录 / 拆批接入全局限速器，
errno=132大目录分块、errno=4超时退避，链接连续失效自动暂停轮询 - 体验：Windows 控制台日志不再出现
[2m、[32m等乱码
✅ 平滑升级：本版本不涉及
v2.0.0那样的不兼容数据迁移，从v2.0.x升级到v2.1.0无感知。分享同步会新建自己的数据表，与既有数据兼容。仍建议升级前按惯例备份数据目录（见下方「升级说明」）。
✨ 分享同步（Share Sync）
订阅第三方分享链接，按固定间隔（≥10 分钟）或每日定时拉取文件列表，与上次快照对比差异，自动把变更应用到网盘目录（转存）和 / 或本地目录（下载）。只同步变动的文件，不会整目录重复处理。
功能要点：
- 多账号隔离：订阅按
owner_uid归属与解析，多账号互不干扰，事件携带owner_uid。 - 双目标并行：单条订阅可同时配置「网盘 + 本地」两个目标；支持
include/exclude路径过滤，精确控制同步范围。 - 三种冲突策略：
overwrite（覆盖）：直接覆盖目标中的同名文件versioned（新版本）：保留旧文件为name(YYYYMMDD-HHMMSS).ext，写入新文件skip（跳过）：目标已存在则不处理
- 删除行为可控：默认保留目标中的旧文件；可开启「分享者删除 → 目标也删除」。
- 实时进度与审计：子任务实时进度（速度 / 预计剩余时间），每次运行记录
added/modified/removed/failed计数与文件级run_item；通过 WebSocket 实时推送，断线 / 切页用 REST 轮询兜底。 - Web UI：
/share-sync页面，订阅列表 + 创建（复用转存对话框与 include/exclude 编辑器）+ 运行历史弹窗 + 内联子任务进度。
🐛 分享同步·稳定性与正确性修复
- 增量只同步变动文件：已同步目录里改动 / 新增单个文件时，只同步该文件，不再整目录重转存 + 重下载。
- 转存撞同名继续下载：目标已存在同名目录 / 文件时视为「已存在」并继续进入下载阶段，不再整批判失败。
- 增量单文件修复：修复增量新增单个文件被误判失败、以及网盘目录名翻倍（落到
/目标/目标/...）的问题。 - 进行中子任务列表：完成的文件夹不再被回包成「进行中」，切页 / 断线重连后状态一致。
- 重启自动续跑：后端重启后自动续跑被中断的 run，不再粗暴标失败。
- 删除订阅清理：删除订阅时清理名下内部转存 / 下载任务，避免孤儿脏数据。
🐛 风控与限速
- 全局限速器：列目录抓快照 / 拆批接入账号级全局限速器（leaky bucket），降低并发探测触发风控的概率。
- 大目录分块：删除大目录、整批转存自动分块以规避
errno=132；整批转存临时超时（errno=4）按退避自动重试。 - 轮询节奏：轮询抖动后强制不低于最小间隔，与自动备份对齐降低风控。
- 链接失效熔断：分享链接确定性失效连续 2 次自动暂停轮询，并在前端提供「恢复」按钮。
🐛 进度显示修复
- 文件夹下载不再翻倍：修复文件夹下载完成时「已下载」翻倍（200%）的聚合竞态——已完成子任务不再被重复计入活跃和。
- 上传不再超过 100%：上传「已上传」改用已完成分片之和（幂等），同一分片重传 /
upload_id过期重传不会重复累加，根治进度 >100%（如 142%）。 - 全站钳制：前端各进度条与后端
progress()统一钳到[0,100]，作为防御兜底。
🐛 其他修复
- 转存任务归属：重启恢复转存任务时还原
is_internal，分享同步内部转存任务不再漏进转存管理列表。 - Windows 控制台日志乱码：Windows 下默认关闭控制台 ANSI 彩色输出，避免出现
[2m、[32m等转义字符；非 Windows 平台保留终端彩色，文件日志始终为纯文本。（感谢 @YYQHH PR #103） - 前端：文件列表滚动加载在请求失败后不再无限翻页；修复路由切换后
el-table列宽错位；修复npm run lint（ESLint v9 flat config）并清理零风险静态告警。
🔧 升级说明
Docker 用户
# 升级前建议先备份挂载的 data 卷
# 拉取指定版本镜像
docker pull komorebicarry/baidupcs-rust:v2.1.0
# 或使用 latest 标签
docker pull komorebicarry/baidupcs-rust:latest
# 重启容器
docker-compose down && docker-compose up -d二进制用户
从 Releases 页面下载对应平台的二进制文件，替换原有可执行文件后重启服务。
配置与数据
- 本版本无破坏性数据迁移，从
v2.0.x升级无需任何手动操作；分享同步会自动创建所需数据表。 - 升级仍建议按惯例备份
backend/config/与backend/wal/（Docker 用户备份挂载的data卷）。 - 默认端口仍为
18888，不影响现有反向代理 / 防火墙 / 书签。
📁 下载
| 平台 | 文件名 |
|---|---|
| Windows (x86_64) | BaiduPCS-Rust-v2.1.0-windows-x86_64.zip |
| Linux (x86_64) | BaiduPCS-Rust-v2.1.0-linux-x86_64.tar.gz |
| Linux (ARM64) | BaiduPCS-Rust-v2.1.0-linux-aarch64.tar.gz |
| macOS (x86_64) | BaiduPCS-Rust-v2.1.0-macos-x86_64.tar.gz |
| macOS (ARM64) | BaiduPCS-Rust-v2.1.0-macos-aarch64.tar.gz |
| Docker 镜像 | BaiduPCS-Rust-v2.1.0-docker.tar.gz |
完整更新日志：参见项目根目录的 CHANGELOG.md
问题反馈：欢迎通过 GitHub Issues 进行反馈
v2.0.1
BaiduPCS-Rust v2.0.1 发行说明
发布日期： 2026-06-10
🎯 版本说明
v2.0.1 是在 v2.0.0 多账号版本基础上的补丁版本，主要修复多账号添加流程与设置页 UI 显示问题。本版本不涉及数据结构变更，从 v2.0.0 升级无需额外备份或迁移操作，直接替换二进制 / 拉取镜像后重启即可。
本版本修复：
- 添加账号时尚未扫码就误报「账号添加成功」
- 设置页滑到底部时「关于」卡片下边框被横向滚动条遮挡
🐛 问题修复
🐛 修复添加账号尚未扫码就误报「账号添加成功」
现象： 在已登录状态下通过「添加账号」扫码登录时，用户尚未完成扫码，界面就提示「账号添加成功」。
原因： 扫码状态轮询接口在检测到「已有活跃账号」时会短路返回成功；添加账号模式下用户本就已有活跃账号，导致轮询一开始就用旧账号判定为登录成功。
修复：
- 前端：添加账号模式的扫码轮询附带
add=true参数 - 后端：
/auth/qrcode/status在add=true时跳过「已有活跃账号即视为登录成功」的短路逻辑，必须真正扫码新账号后才返回成功
🐛 修复设置页「关于」卡片下边框被横向滚动条遮挡
现象： 设置页滚动到底部时，「关于」卡片下边框被横向滚动条盖住，视觉不完整。
原因： 设置内容区同时开启纵向滚动时，浏览器会将 overflow-x 计算为 auto；子项略超宽时出现横向滚动条，遮挡底部卡片边框。
修复： 设置内容区显式设置 overflow-x: hidden，仅保留纵向滚动，子项正常换行显示。
🔧 升级说明
本版本为补丁升级，无数据结构变更，从 v2.0.0 升级可直接覆盖，无需备份或迁移。
Docker 用户
# 拉取指定版本镜像
docker pull komorebicarry/baidupcs-rust:v2.0.1
# 或使用 latest 标签
docker pull komorebicarry/baidupcs-rust:latest
# 重启容器
docker-compose down && docker-compose up -d二进制用户
从 发行版 页面下载对应平台文件，替换可执行文件后重启服务即可。
配置与数据
- 无需修改配置文件
- 无需数据迁移
- 默认端口仍为 18888
📁 下载
| 平台 | 文件名 |
|---|---|
| Windows (x86_64) | BaiduPCS-Rust-v2.0.1-windows-x86_64.zip |
| Linux (x86_64) | BaiduPCS-Rust-v2.0.1-linux-x86_64.tar.gz |
| Linux (ARM64) | BaiduPCS-Rust-v2.0.1-linux-aarch64.tar.gz |
| macOS (x86_64) | BaiduPCS-Rust-v2.0.1-macos-x86_64.tar.gz |
| macOS (ARM64) | BaiduPCS-Rust-v2.0.1-macos-aarch64.tar.gz |
| Docker 镜像 | BaiduPCS-Rust-v2.0.1-docker.tar.gz |
完整更新日志： 参见项目根目录的 CHANGELOG.md
问题反馈： 欢迎通过 GitHub Issues 反馈
v2.0.0
BaiduPCS-Rust v2.0.0 发行说明
发布日期：2026-06-08
🎯 版本说明
v2.0.0 是引入多账号支持的重大版本，版本号从 v1.14.1 跃升至 v2.0.0。多账号涉及任务归属、数据隔离与资源调度的架构级改动，按语义化版本属于不兼容的大版本升级，升级风险高于以往小版本，请务必先阅读「升级前必读」。
- 核心新功能：多账号独立管理（添加 / 切换 / 删除）、按
owner_uid的任务归属与数据隔离、实时资源配额调度（BudgetScheduler） - 稳定性：启动期自动修复 + 迁移前完整备份（任何破坏性操作之前）、全局只读保护兜底、断线自适应退避重连
- 通用修复：下载取链
errno=8002临时风控阶梯重试、filemetas按路径解析fs_id、创建即持久化下载任务
⚠️ 本版本会改动后端数据（SQLite 新增owner_uid列、.meta/ 历史回填、session.json改名迁移）。升级前请务必备份，详见下方说明。
⚠️ 升级前必读
升级前请先备份后端数据目录
升级到 v2.0.0 前，请先手动备份后端数据目录：
backend/config/（含baidu-pcs.db、accounts.json、session.json、autobackup_configs.json）backend/wal/（任务状态.meta）
Docker 用户备份挂载的 data 卷即可。万一升级异常，恢复这两个目录即可回到升级前状态。
除手动备份外，后端在首次启动 2.0.0 且检测到既有数据时，会在任何破坏性迁移之前自动做一份完整备份到
config/backups/pre_migration_<时间戳>/（详见「启动期自动修复 + 迁移前完整备份」一节），作为额外保险。
降级提示
如需回退到旧版本，请先恢复升级前备份的 config/ 与 wal/ 目录，再启动旧版本；不建议直接用 2.0.0 升级后的数据目录启动旧版本。
原因：2.0.0 会改动数据（SQLite 新增 owner_uid 列、.meta / 历史回填、session.json 改名迁移），旧版本对这些改动的兼容性无法保证；且旧版本为单账号，会把多账号历史混在一起显示。若已无升级前备份，回退后至少需要重新登录。
📌 自定义 DB 路径用户注意：若你在
config/app.toml的[persistence].db_path把数据库放到了config/之外，则备份 / 还原config/与wal/并不包含该数据库文件——请额外备份 / 还原该真实 DB 文件（含其-wal/-shm边车文件）。系统的自动迁移前备份会按db_path复制真实 DB 到备份目录，但手动恢复时需把它放回原自定义位置。
✨ 多账号独立任务管理
支持添加 / 切换 / 删除多个百度账号，每个账号拥有独立的客户端实例（BDUSS / Cookie / 会话）与任务队列。下载 / 上传 / 转存 / 自动备份 / 离线下载任务均按 owner_uid 归属与隔离。
实现要点：
- 数据隔离与归属：所有任务按
owner_uid归属；删除账号时按owner_uid精确清理该账号的本地任务与历史，不误伤其他账号。 - 跨账号聚合：聚合列表按 id 去重；历史回退路由按
owner_uid+task_type精确匹配，避免跨账号 / 跨类型误删。 - 并发安全收口：修复账号切换 / 操作备份任务后的死锁，以及父任务永久卡在
Transferring的问题；统一收口 uploader 跨await持有 DashMap 锁的写法，消除多账号并发下的死锁。 - 持久化迁移：单账号（
session.json）→ 多账号（accounts.json）自动迁移，配套 SQLite schema 升级与.meta/ 历史回填（见下方迁移与备份说明）。
✨ 账号切换器与账号管理面板
- 顶部新增账号切换器，一键在已登录账号间切换。
- 设置页新增账号管理面板，集中管理（添加 / 切换 / 删除）账号。
✨ 实时资源配额（BudgetScheduler）
多账号同时下载时，机器总线程数有限，需要在账号之间公平分配。新增 BudgetScheduler 负责实时配额调度：
- 按会员权重分配：机器总线程 M 按会员权重（普通 : VIP : SVIP =
1 : 3 : 5）在账号间分配，每个账号实时展示「保底 base / 上限 vip_cap」两条水位。 - 自动按等级推荐：按 VIP 等级取线程上限（普通会员
10/ 超级会员15），并同时受机器总线程与会员权重共同约束——推荐值是天花板，实际可用线程由总线程 + 权重共同决定。 - 配额面板真实值：资源配额面板显示后端真实生效值与实际可用线程（不再写死推荐值），界面与实际调度一致。
- 公平调度：优先级信号量（priority semaphore）公平调度各账号的分片并发。
✨ 启动期自动修复 + 迁移前完整备份
为了让单账号 → 多账号的迁移对普通用户无感，后端启动时按以下流程自动处理，只有在确实无法自动恢复时才进入只读保护：
启动
↓
迁移前完整备份（首次 2.0.0 启动且有既有数据时，做且仅做一次）
↓
运行迁移矩阵（session.json→accounts.json / SQLite ALTER / .meta 回填）
↓
失败？
├─ 临时锁 / 占用（database is locked/busy）→ 短退避自动重试（200ms→1s，最多 3 次）
└─ 不可判定 / 高风险（DB 损坏 / 无权限 / 磁盘满）→ 进入全局只读保护
↓
成功则正常启动（用户无感知）
迁移前完整备份
- 时机：备份发生在任何破坏性操作之前——早于
session.json → session.json.migrated改名、accounts.json写入、SQLite ALTER TABLE、.meta回写、历史owner_uid回填。备份调用置于服务初始化的最前面，先于任何会写库的组件初始化，确保备份到的是升级前的原始数据。 - 目标目录：
config/backups/pre_migration_<时间戳>/ - 备份内容（存在才复制）：
app.toml、session.json、session.json.migrated、accounts.json、accounts.json.bak、autobackup_configs.json- 真实数据库文件：按
AppConfig.persistence.db_path取真实路径（不写死config/baidu-pcs.db），并一并复制-wal/-shm边车文件 - 整个
wal/目录（任务状态.meta）
- 触发判据：仅当
config/backups/下尚无任何有效pre_migration_*备份（即本数据目录首次在 2.0.0 启动）且存在既有数据（db/session.json/accounts.json任一存在）时备份一次；之后每次启动因已存在有效备份而跳过，不会堆积。全新安装无既有数据则不备份。 - 完成标记（manifest）：备份成功复制内容后，会在备份目录写入
backup_manifest.json（记录完成时间、真实 DB / WAL 路径、实际复制清单copied，以及关键文件清单required）。只有带该 manifest 的目录才被认作有效备份——若仅创建了目录但复制失败 / 不完整（未写 manifest），下次启动不会误以为已备份，而会重新备份，避免「空壳备份」。 - 关键文件校验（
required）：manifest 的required记录本次按既有数据应当包含的关键项（源端存在才计入）：真实 DB 及其-wal/-shm边车（-wal可能含尚未 checkpoint 的数据）、session.json、accounts.json、以及wal/任务目录。启动判定有效备份时不仅看 manifest 存在，还会逐项确认这些项真实存在于备份目录；任一缺失即视为无效备份并重做。损坏 / 半写入的 manifest（读取或 JSON 解析失败）一律判为无效；旧版备份（manifest 无required字段）按「存在即有效」向后兼容、不会失效。 wal/内容完整性：wal/目录必须完整复制——复制时若有任一文件复制 / 读取 / 遍历失败，整次迁移前备份即视为失败（不写 manifest、下次启动重做），不会留下「目录在但内容残缺」的假备份。manifest 另记wal_files（wal/下各文件的相对路径清单），启动校验时逐项核对备份目录内对应文件是否存在，既能识别「数量被删少」也能识别「具体文件被删 / 替换但数量不变」。- 失败处理：单个文件复制失败仅告警、跳过；若一项都没复制成功或 manifest 写入失败则视为备份失败（不写标记）。备份失败不阻塞启动；若随后真实破坏性写入失败，会进入只读保护，用户仍可用升级前的手动备份还原。
临时错误自动重试
迁移命中临时性的 database is locked / database is busy（含 SQLITE_BUSY / SQLITE_LOCKED）时，按 200ms → 1s 退避自动重试，最多 3 次；缺列 / 重复列 / 表不存在 / 单账号 owner_uid 回填等情况已由迁移矩阵的幂等守卫吸收，不会误触发只读。
✨ 数据安全兜底·全局只读保护模式
只读模式是最后兜底，正常运行（迁移成功）时用户完全感知不到它，不会影响任何账号的下载 / 上传 / 转存。
-
触发条件：仅当启动期「单账号 → 多账号」迁移在自动修复 + 重试都失败后，或关键持久化出现不可判定 / 高风险错误（DB 损坏 / 无权限 / 磁盘满）时，才自动置位。
-
行为：全局拦截所有写操作（POST/PUT/DELETE/PATCH），读取 / 历史照常可用，避免数据已可能损坏时继续写入扩大不一致。
-
诊断：进入只读前记录明确原因（
failed_step/last_error/suggestion），以info级日志打印，供后端运维排查（不向用户暴露 migration / owner_uid / SQLite 等术语）。 -
用户提示（自助恢复，无需联系开发者）：
服务端检测到数据异常，已进入只读保护模式以避免数据损坏。请先重启后端再次尝试自动修复；若重启后仍未恢复，请还原升级前备份的
config/与wal/目录后重启；系统也会在升级迁移前自动备份到config/backups/pre_migration_<时间戳>/。
文案只承诺「再次尝试自动修复」，不承诺一定修复成功——遇到 DB 真损坏等持久问题时，用户可按提示还原升级前备份并回退版本。
✨ 断线自适应退避重连
后端临时不可达时，下载 / 上传页按阶梯退避重试轮询，0 B/s 显示「计算中」，避免一次轮询失败就清空任务列表、进而把自适应轮询直接停掉。下载页与上传页行为对齐：失败时保留现有列表，维持 active 状态以便退避重试继续。
🐛 问题修复（与多账号无关的通用项）
- 🐛 下载取链
errno=8002临时风控：命中风控时按阶梯式重试，提升弱网 / 风控下的成功率。 - 🐛
filemetas按路径查询：改用xpan/file list解析fs_id，规避按路径查filemetas的不稳定。 - 🐛 创建即持久化下载任务：任务创建时即落盘，重启后保留终态失败任务（不再丢失失败记录）。
🔧 升级说明
Docker 用户
# 升级前先备份挂载的 data 卷（强烈建议）
# 拉取指定版本镜像
docker pull komorebicarry/baidupcs-rust:v2.0.0
# 或使用 latest 标签
docker pull komorebicarry/baidupcs-rust:latest
# 重启容器
docker-compose down && docker-compose up -d二进制用户
升级前先备份 backend/config/ 与 backend/wal/，再从 Releases 页面下载对应平台的二进制文件，替换原有可执行文件后重启服务。
配置与数据
- 升级时后端会自动完成单账号 → 多账号的数据迁移（
session.json→accounts.json、SQLite 新增owner_uid列、.meta/ 历史回填），并在迁移前自动备份到config/backups/pre_migration_<时间戳>/，正常情况下用户无感知。 - 迁移成功后无需任何手动操作。若启动后界面提示「只读保护模式」，请按提示先重启后端再次尝试自动修复；仍未恢复时还原升级前备份的
config/与wal/目录后重启。 - 默认端口仍为
18888，不影响现有反向代理 / 防火墙 / 书签。
📁 下载
| 平台 | 文件名 |
|---|---|
| Windows (x86_64) | BaiduPCS-Rust-v2.0.0-windows-x86_64.zip |
| Linux (x86_64) | BaiduPCS-Rust-v2.0.0-linux-x86_64.tar.gz |
| Linux (ARM64) | BaiduPCS-Rust-v2.0.0-linux-aarch64.tar.gz |
| macOS (x86_64) | BaiduPCS-Rust-v2.0.0-macos-x86_64.tar.gz |
| macOS (ARM64) | BaiduPCS-Rust-v2.0.0-macos-aarch64.tar.gz |
| Docker 镜像 | BaiduPCS-Rust-v2.0.0-docker.tar.gz |
完整更新日志：参见项目根目录的 CHANGELOG.md
问题反馈：欢迎通过 GitHub Issues 进行反馈