AutoBangumi 番剧管理（bangumi_manage）配置详解：重命名方式、剧集补全与种子治理

• 后端
• 前端
• 音视频

本文以 AutoBangumi 的「番剧管理」模块为核心，系统讲解 WebUI 与config.json中bangumi_manage配置节的每一项开关与参数：四种重命名方式、剧集补全、组标签、坏种清理与未匹配种子记录，并结合仓库源码说明每个选项背后的实际调用链与默认行为。读完本文，你将能够按自己的媒体库习惯（Plex / Jellyfin / 纯做种目录）配置出最合适的整理策略，并理解关闭某个开关后系统具体会发生什么。

番剧管理器：从“追番”到“整理”的核心枢纽

AutoBangumi 的核心链路是「RSS 订阅 → 下载器（qBittorrent 等）→ 番剧整理」三段式流水线。番剧管理器（Bangumi Manage）承担的是最后一段：它周期性地检查下载器中已完成的种子，按用户配置对文件进行重命名、剧集偏移修正、整季补全和异常种子清理，最终把下载器里混乱的发布标题整理成规范的媒体库结构。

管理器是否启用，直接决定了整个整理循环是否运行。在 checker.py 中，check_renamer()仅凭一行判断决定结果：

if settings.bangumi_manage.enable: return True

也就是说，关闭「启用」开关后，重命名与整理相关设置全部不会生效，下载器中的文件会以原始种子名保留。这一点与文档描述完全一致。

WebUI 配置选项逐一详解

WebUI 的「番剧管理」设置页（即上图中的 manager 设置界面）提供了 6 个选项，下面逐一说明其语义与源码层面的行为。

启用

布尔开关，对应配置节中的enable，默认值为true。如上文所述，它控制Checker.check_renamer()的返回值，进而决定整理循环是否启动。关闭后重命名、剧集补全等能力全部停用，适合只做“下载不动文件”的场景。

重命名方式（rename_method）

这是番剧管理器最核心的选项，共四种取值，默认pn：

需要特别说明的是pn与advance的差异：前者文件名保留发布组的标题风格，后者统一采用官方标题，更适合需要与 TMDB 等元数据服务严格对齐的媒体库。季（season）编号来自保存目录的文件夹名（如Season 01），集数则遵循两位补零格式（1→01）；对于总集篇等半集（如 12.5），源码会保留小数以避免覆盖同季的整数集。

此外，重命名还覆盖电影/剧场版场景（gen_movie_path）：电影类文件采用Title (Year).ext风格，不使用SxxExx编号；字幕文件则通过subtitle_pn/subtitle_advance方法在剧集名后追加语言后缀。

番剧补全（eps_complete）

布尔开关，默认false。开启后，管理器会检测当季缺失的集数并尝试补全下载。源码实现位于 collector.py 的eps_complete()：它查询所有未完成的番剧记录，对eps_collect标记为 False 的番剧调用SeasonCollector.collect_season()，通过搜索器或 RSS 链接批量获取整季种子并加入下载器。该函数由 loops.py 在每轮收集循环中按条件触发：

if settings.bangumi_manage.eps_complete: await eps_complete()

添加组标签（group_tag）

布尔开关，默认false。开启后，下载器中任务的名字会带上字幕组标签。源码实现位于 path.py 的rule_name()：RSS 规则名由{官方标题} S{季}变为[{字幕组}] {官方标题} S{季}。注意源码注释特别强调：组标签只影响 qBittorrent RSS 规则名，从不写进重命名后的文件名——已有做种媒体库的文件名必须保持稳定，否则升级后会触发整库批量重命名，破坏 Plex/Jellyfin 索引与硬链接。

删除坏种（remove_bad_torrent）

布尔开关，默认false。开启后，当某个种子的媒体路径无法被解析器识别（解析失败）时，管理器会直接调用下载器删除该种子。源码中出现在 renamer.py 的单文件处理与 同文件 L299-L300 的路径：解析失败时若开关开启，则执行client.delete_torrent(hashes=hash)清理异常任务。

记录未匹配种子（track_orphans）

布尔开关，默认true。开启时，把当前没有匹配到任何规则的种子记录为「未匹配种子」（orphan）入库；关闭后，这些条目不写入数据库，但会在每轮 RSS 刷新时被重新在内存中匹配，因此后续新增规则可以立即“接住”RSS 源中仍存在的旧条目。源码依据在 engine.py：

if not settings.bangumi_manage.track_orphans: # 不记录未匹配种子：它们每轮会被 check_new 重新看到并在内存中 # 重新匹配（廉价），后补规则能立即接住仍在源里的旧集 to_persist = [t for t in to_persist if t.bangumi_id is not None]

简言之：开启适合希望保留完整“未匹配”历史记录的场景；关闭则牺牲历史记录换取后补规则的即时生效与更小的数据库体积。

config.json配置节：bangumi_manage完整参数表

config.json中对应的配置节为bangumi_manage。下表在原文档基础上，补充了当前仓库源码中实际存在的默认值与附加参数（字段模型定义见 models/config.py，默认值见 conf/const.py）：

其中revision_conflict_policy是原文档表格之外、但同属bangumi_manage配置节的参数：当同一个番剧同一集的“高版本”发布（V2/V3 等压制版本）指向已被占用的规范路径时，hold表示保留现有文件、记录冲突，replace表示通过带租约的替换流程（staging → promote → 删除旧任务）安全升级到新版本。该替换流程要求新旧任务均为单文件种子且确认为严格版本升级，判定逻辑见 revision_policy.py。

实际使用时，将以上参数写入config/config.json的bangumi_manage节即可，例如：

{ "bangumi_manage": { "enable": true, "eps_complete": true, "rename_method": "advance", "group_tag": true, "remove_bad_torrent": false, "track_orphans": true, "revision_conflict_policy": "hold" } }

环境变量覆盖（Docker 部署）

使用 Docker 部署时，bangumi_manage的配置同样可以通过环境变量覆盖，映射关系定义在 conf/const.py：

源码级原理：重命名循环与ab:renamed标记

为了让读者对「重命名方式」有更深的理解，这里补充一个源码层面的关键机制。重命名主入口是Renamer.rename()（renamer.py），其大致流程为：

1. 从下载器拉取待处理任务（已完成且未打标）；
2. 批量查询每个任务的番剧偏移量（episode_offset/season_offset/episode_type），查询顺序为 qB hash → 标签中的ab:<id>→ 标题匹配 → 保存路径匹配；
3. 按媒体文件数量分流：单文件走_process_single_torrent，多文件走rename_collection（后者完成后会把任务归入BangumiCollection分类），字幕文件紧随其后重命名；
4. 重命名成功的任务会被打上ab:renamed标签（_mark_renamed），作为“顶层媒体文件已全部就位”的终态标记，供 filebot、hlink 等外部脚本过滤已处理任务；
5. 每次重命名操作都会在rename_operation表中留下带状态机（retry/running/conflict/done等）的记录，失败操作在 5 分钟冷却后自动重试。

这套机制解释了为什么rename_method选择pn或advance后，重启或升级不会触发整库批量重命名：已完成任务都有ab:renamed标签做幂等标记，已做种媒体库的文件名保持稳定。

相关配置与 FAQ 指引

番剧管理的效果与下载路径设置紧密相关：保存路径决定了重命名时从文件夹名解析出的季号，相关说明见 FAQ 首页 中关于下载路径与文件重命名的章节。另外，番剧管理还与其他配置节协同工作：

• RSS 订阅配置：决定哪些番剧进入下载队列，是番剧管理器处理的对象来源；
• 下载器配置：保存路径、下载器类型等，直接参与保存路径生成与任务归类；
• 通知配置：重命名成功与冲突事件会通过通知中心推送。

综上，AutoBangumi 的番剧管理模块以bangumi_manage配置节为总控，覆盖了从“下载完成”到“媒体库就绪”的全过程。理解每个开关在源码中的实际作用点，就能针对自己的媒体库形态（是否使用 Plex/Jellyfin、是否保留做种、是否接受自动替换旧版本）做出最合适的取舍。

• 后端
• 前端
• 音视频