docs(4.0): 新增插件设置参考,修正下载器、番剧管理、通知等配置页与代码不符之处

This commit is contained in:
Estrella Pan
2026-10-08 17:36:53 +02:00
parent 2a500362f3
commit f6bca2be60
19 changed files with 360 additions and 31 deletions

View File

@@ -70,10 +70,13 @@ AB 中的下载路径用于生成保存位置和后续整理路径。请填写**
}
```
3.3 的 `downloader` 配置节在升级到 4.0 后第一次启动时自动迁移到 `default` 实例,原文件备份为 `config.json.v3.bak`。环境变量 `AB_DOWNLOADER_HOST`、`AB_DOWNLOADER_USERNAME`、`AB_DOWNLOADER_PASSWORD`、`AB_DOWNLOAD_PATH` 照常生效,写入默认实例。
3.3 的 `downloader` 配置节在升级到 4.0 后第一次启动时自动迁移到 `default` 实例,原文件备份为 `config.json.v3.bak`。迁移失败时 AB 恢复原文件并拒绝启动,见 [插件设置](/config/plugins#从-3-3-升级)。
环境变量 `AB_DOWNLOADER_HOST`、`AB_DOWNLOADER_USERNAME`、`AB_DOWNLOADER_PASSWORD`、`AB_DOWNLOAD_PATH` 只在首次启动、还没有配置文件时读取,写入默认实例。`host`、`username`、`password` 的值可以写成 `$VAR` 形式的环境变量引用,使用时展开。
| 参数 | 说明 | 类型 | WebUI 选项 | 默认值 |
| --- | --- | --- | --- | --- |
| `id` | 实例 id | 字符串 | 新下载器 id | `default` |
| `provider` | 下载器类型 | 字符串 | 下载器类型 | `qbittorrent` |
| `host` | 下载器地址 | 字符串 | 下载器地址 | `172.17.0.1:8080` |
| `username` | 下载器用户名 | 字符串 | 用户名 | `admin` |

View File

@@ -48,6 +48,6 @@ LLM 调用会使用应用的 [代理设置](/config/proxy)。
| `max_concurrency` | 最大并发 | 整数 | 高级设置 | `2` |
| `failure_threshold` | 熔断失败次数 | 整数 | 高级设置 | `3` |
| `failure_backoff` | 熔断暂停时长 | 整数(秒) | 高级设置 | `300` |
| `providers` | 非内置 provider 的覆盖配置 | 对象 | 按 provider 保存 | `{}` |
| `providers` | 按 provider id 保存的覆盖配置(`api_key`、`model`、`base_url`),存在时取代扁平字段 | 对象 | 按 provider 保存 | `{}` |
旧版 `experimental_openai` 配置已在 4.0 移除,见[旧版实验性功能](/config/experimental)。

View File

@@ -14,6 +14,7 @@
- **番剧补全**:检测当季缺失集数并尝试补全下载。
- **添加组标签**:为下载器中的任务添加字幕组相关标签。
- **删除坏种**:移除下载器中状态异常的种子。
- **修订版冲突处理**:更高修订版的种子指向已有剧集时,选择「保留现有文件」或「替换为更高修订版」。启用替换后,仅在更高修订版成功就位后删除旧种子及其数据。
- **记录未匹配种子**:把当前没有匹配到规则的种子记录为“未匹配种子”。关闭后,后续新增规则可以立即接住 RSS 中仍存在的旧条目,但这些旧条目会在每轮 RSS 刷新时重新尝试匹配。
- [关于文件路径][1]
- [关于重命名][2]
@@ -30,7 +31,7 @@
| `remove_bad_torrent` | 删除错误种子 | 布尔值 | 删除坏种 | `false` |
| `track_orphans` | 记录未匹配种子 | 布尔值 | 记录未匹配种子 | `true` |
重命名方式与版本冲突策略是 Provider 选择,保存在 `plugins.slots`:`rename_strategy`(重命名方式,默认 `pn`)与 `conflict_policy`(`hold` / `replace`,默认 `hold`)。3.3 的 `bangumi_manage.rename_method` 与 `revision_conflict_policy` 在升级到 4.0 后第一次启动时自动迁移。
重命名方式与版本冲突策略是 Provider 选择,保存在 `plugins.slots`:`rename_strategy`(重命名方式,默认 `pn`)与 `conflict_policy`(`hold` / `replace`,默认 `hold`)。3.3 的 `bangumi_manage.rename_method` 与 `revision_conflict_policy` 在升级到 4.0 后第一次启动时自动迁移。完整说明见 [插件设置](/config/plugins#slots)。
## 模板重命名
@@ -41,7 +42,7 @@
{{ title }} S{{ season|pad(2) }}E{{ episode|pad(2) }}
```
默认模板与 `pn` 的结果相同。模板使用 [Jinja2](https://jinja.palletsprojects.com/) 语法(沙箱模式),可用变量:
默认模板对普通剧集与 `pn` 的结果相同;剧场版 `pn` 不加 `SxxExx`,默认模板会加。模板使用 [Jinja2](https://jinja.palletsprojects.com/) 语法(沙箱模式),可用变量:
| 变量 | 含义 | 示例 |
| --- | --- | --- |
@@ -81,8 +82,8 @@
- 媒体库中已有同名文件、但不是本插件创建的:跳过,**绝不覆盖**,并发送「硬链接未完成」通知。
- 版本升级(新版本种子替换旧种子,文件名不变)后,本插件之前创建的链接会被原子替换为指向新文件的链接。
- 删除种子不会删除媒体库中的链接。
- 启用前已经下载的文件不会自动处理,需要按需补链:调用 `POST /api/v1/plugins/hardlink/backfill`(设置页按钮将在后续版本提供)。
- `path_map` 目前的设置表单还不能编辑,请在 `config/config.json` 的 `plugins.options.hardlink.path_map` 中填写,例如 `[{"from": "/downloads", "to": "/media/downloads"}]`。
- 启用前已经下载的文件不会自动处理。启用插件后,设置页出现「硬链接补链」分区,点击 **链接已有文件** 把下载根目录下已有的正片与字幕补链到媒体库,已链接的文件跳过。该按钮调用 `POST /api/v1/plugins/hardlink/backfill`。
- `path_map` 在插件配置表单中按行编辑(**添加一行**)。在 `config/config.json` 中对应 `plugins.options.hardlink.path_map`,例如 `[{"downloader": "default", "from": "/downloads", "to": "/media/downloads"}]`。
::: tip Docker
硬链接不能跨文件系统。在 Docker 中,请把下载目录与媒体库放在同一块盘上,并以**同一个挂载点**映射进 AB 容器(例如把 `/mnt/media` 整体挂载为 `/media`,下载目录与媒体库都在其下)。两个分别挂载的目录即使在同一块盘上,也会被视为不同的文件系统,此时按 `cross_device` 处理(默认复制,占用双倍空间)。下载器运行在另一个容器里、看到的路径与 AB 不同时,用 `path_map` 映射。

View File

@@ -22,7 +22,8 @@
不同 provider 需要的字段不同:
- Telegram:`Bot Token`、`Chat ID`
- Discord / WeCom:Webhook URL
- Discord:Webhook URL
- WeCom:Webhook URL、Key
- Bark:Device Key,可选 Server URL
- Server Chan:SendKey
- Gotify:Server URL、App Token
@@ -31,6 +32,8 @@
Webhook 模板可以使用 `{{title}}`、`{{season}}`、`{{episode}}`、`{{poster_url}}` 等占位符。非 Webhook provider 会把模板渲染为普通文本。
已启用的插件也可以提供通知渠道,它们以「插件提供」标注出现在类型列表中。设置页不显示插件渠道的专用字段;需要时请在 `config.json` 中该 provider 对象里填写,AB 原样保存并传给插件。
## `config.json` 配置选项
配置节:`notification`
@@ -45,12 +48,15 @@ Webhook 模板可以使用 `{{title}}`、`{{season}}`、`{{episode}}`、`{{poste
| 参数 | 说明 |
| --- | --- |
| `type` | provider 类型,例如 `telegram`、`discord`、`webhook` |
| `type` | provider 类型:`telegram`、`discord`、`bark`、`server-chan`、`wecom`、`gotify`、`pushover`、`webhook`,或插件提供的渠道 id |
| `enabled` | 是否启用该 provider |
| `token` / `chat_id` | Telegram、Server Chan 等 provider 使用 |
| `webhook_url` / `url` | Discord、WeCom、Webhook 使用 |
| `server_url` / `device_key` | Bark、Gotify 使用 |
| `token` | Telegram(Bot Token)、Server Chan(SendKey)、WeCom(Key)、Gotify(App Token)使用 |
| `chat_id` | Telegram 使用 |
| `webhook_url` | Discord、WeCom 使用 |
| `url` | Webhook 使用 |
| `server_url` | Bark(可选)、Gotify 使用 |
| `device_key` | Bark 使用 |
| `user_key` / `api_token` | Pushover 使用 |
| `template` | 自定义通知模板 |
旧版 `type`、`token`、`chat_id` 单 provider 配置仍可读取,启动时会迁移为 `providers` 列表。
升级到 4.0 后第一次启动时,Bark 的旧字段 `token` 迁移到 `device_key`,WeCom 的旧字段 `chat_id` 迁移到 `webhook_url`。

92
docs/config/plugins.md Normal file
View File

@@ -0,0 +1,92 @@
# 插件设置
4.0 起,下载器、重命名、通知渠道、搜索站点等功能都通过插件扩展点接入。插件的启停、配置与 Provider 选择保存在 `config.json` 的 `plugins` 配置节。
## WebUI 配置
在 **设置 → 插件** 中管理插件:
- **允许未签名插件**:本地目录(`config/plugins/local/`)与 pip 安装的插件未经签名,开启后才会加载。插件与 AutoBangumi 在同一进程中运行,拥有完整权限,只启用你信任的插件。
- **启用**:每个插件卡片上的开关。
- **配置**:展开后按插件声明的配置表单填写,点击 **保存配置**。
以上三项保存后立即生效,不需要点击底部 **保存并重启**。
插件卡片显示来源(内置、本地、pip)、运行状态(运行中、未启用、错误)与声明的权限。插件加载失败、或连续失败 5 次被自动停用时,卡片显示原因;修改该插件的配置后会重新尝试加载。
以下设置不在插件页,而在对应功能的设置分区中,随全局配置一起保存(**保存并重启**):
- 下载器实例与默认下载器:[下载器设置](/config/downloader#多个下载器)
- 重命名方式与版本冲突策略:[番剧管理设置](/config/manager)
## 内置插件
| id | 默认 | 作用 | 说明 |
| --- | --- | --- | --- |
| `rename` | 启用 | 重命名方式 `pn`、`advance`、`template` | [番剧管理设置](/config/manager#模板重命名) |
| `ingest-filters` | 启用 | 包含过滤:配置一组正则(忽略大小写)后,只下载名称匹配任一表达式的种子;留空不过滤,对所有订阅生效 | 见下文 |
| `media-server-refresh` | 启用 | 整理完成后刷新 Jellyfin / Emby / Plex,未填写地址与 API Key 时什么也不做 | [番剧管理设置](/config/manager#媒体库刷新) |
| `hardlink` | 停用 | 把整理好的文件硬链接到媒体库 | [番剧管理设置](/config/manager#硬链接到媒体库) |
`ingest-filters` 的「包含过滤」(`include`)补充规则自带的「排除过滤」。非法正则按字面匹配。
开发插件见 [插件开发](/dev/plugins)。
## `config.json` 配置选项
配置节:`plugins`
| 参数 | 说明 | 类型 | WebUI 选项 | 默认值 |
| --- | --- | --- | --- | --- |
| `allow_unsigned` | 加载未签名(本地目录、pip)插件 | 布尔值 | 允许未签名插件 | `false` |
| `dev_mode` | 本地插件文件变更后自动重新加载 | 布尔值 | 暂无 WebUI 项 | `false` |
| `enabled` | 按插件 id 保存的启用开关 | 对象 | 插件卡片的启用开关 | `{}` |
| `options` | 按插件 id 保存的插件配置 | 对象 | 插件卡片的配置 | `{}` |
| `hook_order` | 按扩展点指定钩子执行顺序 | 对象 | 暂无 WebUI 项 | `{}` |
| `slots` | 各扩展点选用的 Provider | 对象 | 见下表 | 见下表 |
| `instances` | 多实例扩展点的实例列表(目前只有下载器) | 数组 | 下载器设置 | 一个 id 为 `default` 的 qBittorrent 实例 |
- `enabled` 中没有出现的插件:内置插件按清单默认启用(`hardlink` 默认停用),其它来源的插件默认停用。
- `options` 中保存的值必须通过插件配置模型的校验;在 WebUI 中保存时,不合法的配置被拒绝。密码类字段在接口返回时被掩码。
- `hook_order` 的键是钩子扩展点:`torrent.filter`、`title.parsed`、`torrent.adding`、`http.request`、`message_template`;值是插件 id 列表。列出的插件按列出的顺序最先执行,其余插件按优先级、再按插件 id 排序。
### `slots`
| 参数 | 说明 | WebUI 选项 | 默认值 |
| --- | --- | --- | --- |
| `downloader` | 默认下载器实例 id,必须是 `instances` 中的下载器实例 | 下载器设置的 **设为默认** | `default` |
| `rename_strategy` | 重命名方式:`none`(宿主自带),`pn`、`advance`、`template`(内置插件 `rename`),或其它插件提供的方式 | 番剧管理设置的重命名方式 | `pn` |
| `conflict_policy` | 更高修订版的种子指向已有剧集时:`hold` 保留现有文件,`replace` 替换为更高修订版 | 番剧管理设置的修订版冲突处理 | `hold` |
| `media_files` | 判断种子内文件是正片还是字幕的实现,宿主自带的实现按扩展名判断 | 暂无 WebUI 项 | `default` |
选中的 Provider 没有登记(例如提供它的插件被停用或被熔断)时,`rename_strategy` 按 `none` 处理,`conflict_policy` 与 `media_files` 退回宿主自带的实现。
### `instances`
```json
"instances": [
{
"id": "default",
"point": "downloader",
"provider": "qbittorrent",
"options": { "host": "172.17.0.1:8080", "username": "admin", "password": "adminadmin", "path": "/downloads/Bangumi", "ssl": false }
}
]
```
| 参数 | 说明 |
| --- | --- |
| `id` | 实例 id,不能重复 |
| `point` | 扩展点,目前只有 `downloader` |
| `provider` | 实现该扩展点的 Provider id,例如 `qbittorrent`、`aria2` 或插件提供的下载器 |
| `options` | 该实例的配置,下载器的字段见 [下载器设置](/config/downloader#config-json-配置选项) |
## 从 3.3 升级
升级到 4.0 后第一次启动时,AB 把 3.3 的配置迁移到 `plugins` 配置节:
- `downloader` → `plugins.instances` 中 id 为 `default` 的下载器实例,`plugins.slots.downloader` 设为 `default`。
- `bangumi_manage.rename_method` → `plugins.slots.rename_strategy`(已废弃的 `normal` 改为 `none`)。
- `bangumi_manage.revision_conflict_policy` → `plugins.slots.conflict_policy`。
迁移前原文件备份为 `config.json.v3.bak`;已有同名备份时不覆盖,改用 `config.json.v3.bak.1`、`config.json.v3.bak.2` 等。迁移失败时(例如迁移后的配置未通过校验),AB 从备份恢复原文件并**拒绝启动**,日志写明出错的字段。修正该字段后重新启动即可。

View File

@@ -2,7 +2,7 @@
![search provider](/image/config/search-provider.png){width=700}{class=ab-shadow-card}
搜索源用于 WebUI 的种子搜索与订阅。内置源包括 `mikan`、`nyaa` 和 `dmhy`;默认源不能删除,但可以编辑 URL 模板。
搜索源用于 WebUI 的种子搜索与订阅。内置源包括 `mikan`、`anibt`、`nyaa` 和 `dmhy`;默认源不能删除,但可以编辑 URL 模板。
搜索源设置是即时保存项,添加、编辑或删除后会立即写入 `config/search_provider.json`,不需要点击底部 **保存并重启**。

View File

@@ -17,7 +17,7 @@
| --- | --- | --- | --- | --- |
| `login_whitelist` | 登录 IP 白名单 | 字符串数组 | 登录 IP 白名单 | `[]` |
| `login_tokens` | 登录 API 令牌 | 字符串数组 | 登录 API 令牌 | `[]` |
| `mcp_whitelist` | MCP IP 白名单 | 字符串数组 | MCP IP 白名单 | 局域网与本机 CIDR 或 `[]` |
| `mcp_whitelist` | MCP IP 白名单 | 字符串数组 | MCP IP 白名单 | `[]` |
| `mcp_tokens` | MCP API 令牌 | 字符串数组 | MCP API 令牌 | `[]` |
| `webauthn_rp_id` | Passkey RP ID | 字符串 | 暂无 WebUI 项 | `""` |
| `webauthn_origin` | Passkey Origin | 字符串 | 暂无 WebUI 项 | `""` |

View File

@@ -62,10 +62,13 @@ A downloader is an entry in `plugins.instances` whose `point` is `downloader`. `
}
```
On the first start after an upgrade to 4.0, the 3.3 `downloader` section moves to the `default` instance automatically. The original file is kept as `config.json.v3.bak`. The environment variables `AB_DOWNLOADER_HOST`, `AB_DOWNLOADER_USERNAME`, `AB_DOWNLOADER_PASSWORD` and `AB_DOWNLOAD_PATH` still work and set the default instance.
On the first start after an upgrade to 4.0, the 3.3 `downloader` section moves to the `default` instance automatically. The original file is kept as `config.json.v3.bak`. If the migration fails, AutoBangumi restores the original file and does not start. See [Plugin Settings](/en/config/plugins#upgrade-from-3-3).
AutoBangumi reads the environment variables `AB_DOWNLOADER_HOST`, `AB_DOWNLOADER_USERNAME`, `AB_DOWNLOADER_PASSWORD` and `AB_DOWNLOAD_PATH` only on the first start, when no config file exists. They set the default instance. The values of `host`, `username` and `password` can contain environment variable references in the form `$VAR`. AutoBangumi expands them when it uses the values.
| Key | Description | Type | WebUI field | Default |
| --- | --- | --- | --- | --- |
| `id` | Instance id | string | New downloader id | `default` |
| `provider` | Downloader type | string | Downloader Type | `qbittorrent` |
| `host` | Downloader address | string | Host | `172.17.0.1:8080` |
| `username` | Downloader username | string | Username | `admin` |

View File

@@ -14,6 +14,7 @@
- **EPS complete**: tries to backfill missing episodes in the current season.
- **Add Group Tag**: adds subgroup-related tags to downloader tasks.
- **Delete Bad Torrent**: removes errored downloader tasks.
- **Revision Conflict Policy**: when a torrent with a higher revision targets an existing episode, select **Keep Existing File** or **Replace with Higher Revision**. With replacement, the old torrent and its data are deleted only after the higher revision is in place.
- **Track Unmatched Torrents**: stores torrents that do not match any rule as orphan records. Disable it if you want newly added rules to catch old feed items immediately, at the cost of rechecking those old items on each RSS refresh.
## Template rename
@@ -25,7 +26,7 @@ With `template`, file names come from the template of the built-in `rename` plug
{{ title }} S{{ season|pad(2) }}E{{ episode|pad(2) }}
```
The default produces the same names as `pn`. Templates use sandboxed [Jinja2](https://jinja.palletsprojects.com/) syntax with these variables:
For normal episodes the default produces the same names as `pn`. For movies, `pn` adds no `SxxExx`, but the default template does. Templates use sandboxed [Jinja2](https://jinja.palletsprojects.com/) syntax with these variables:
| Variable | Meaning | Example |
| --- | --- | --- |
@@ -65,8 +66,8 @@ The built-in `hardlink` plugin is **disabled by default**. Enable it under **Set
- If the library already has a file with that name that the plugin did not create, the plugin skips it, **never overwrites it**, and sends a notification.
- After a revision upgrade (a new release replaces the old torrent under the same file name), the link the plugin made earlier is atomically replaced with a link to the new file.
- Deleting a torrent does not delete its links in the library.
- Files downloaded before you enabled the plugin are not linked automatically. To link them, call `POST /api/v1/plugins/hardlink/backfill` (a settings button follows in a later release).
- The settings form cannot edit `path_map` yet. Set it in `config/config.json` under `plugins.options.hardlink.path_map`, for example `[{"from": "/downloads", "to": "/media/downloads"}]`.
- Files downloaded before you enabled the plugin are not linked automatically. When the plugin is enabled, the settings page shows a "Hardlink backfill" section. Click **Link existing files** to link the videos and subtitles already in the download root into the library. Files that are already linked are skipped. The button calls `POST /api/v1/plugins/hardlink/backfill`.
- Edit `path_map` in the plugin options form, one row per entry (**Add row**). In `config/config.json` it is `plugins.options.hardlink.path_map`, for example `[{"downloader": "default", "from": "/downloads", "to": "/media/downloads"}]`.
::: tip Docker
Hard links cannot cross file systems. In Docker, keep the download folder and the library on the same disk and mount them into the AutoBangumi container through **one** mount (for example, mount `/mnt/media` as `/media` with both folders below it). Two separate mounts count as different file systems even on the same disk; the plugin then follows `cross_device` (by default it copies, which uses twice the space). If the downloader runs in another container and sees different paths, use `path_map`.
@@ -88,4 +89,4 @@ Section: `bangumi_manage`
| `remove_bad_torrent` | Delete errored torrents | boolean | Delete Bad Torrent | `false` |
| `track_orphans` | Track unmatched torrents | boolean | Track Unmatched Torrents | `true` |
The rename method and the revision conflict policy are provider choices. They are stored in `plugins.slots`: `rename_strategy` (rename method, default `pn`) and `conflict_policy` (`hold` / `replace`, default `hold`). On the first start after an upgrade to 4.0, the 3.3 keys `bangumi_manage.rename_method` and `revision_conflict_policy` move there automatically.
The rename method and the revision conflict policy are provider choices. They are stored in `plugins.slots`: `rename_strategy` (rename method, default `pn`) and `conflict_policy` (`hold` / `replace`, default `hold`). On the first start after an upgrade to 4.0, the 3.3 keys `bangumi_manage.rename_method` and `revision_conflict_policy` move there automatically. For details, see [Plugin Settings](/en/config/plugins#slots).

View File

@@ -22,7 +22,8 @@ Supported providers:
Provider-specific fields include:
- Telegram: `Bot Token`, `Chat ID`
- Discord / WeCom: Webhook URL
- Discord: Webhook URL
- WeCom: Webhook URL and Key
- Bark: Device Key and optional Server URL
- Server Chan: SendKey
- Gotify: Server URL and App Token
@@ -31,6 +32,8 @@ Provider-specific fields include:
Webhook templates can use placeholders such as `{{title}}`, `{{season}}`, `{{episode}}` and `{{poster_url}}`.
Enabled plugins can also add notification channels. They appear in the type list with the label "From plugin". The settings page does not show fields that only a plugin channel uses. If the channel needs them, add them to the provider object in `config.json`. AutoBangumi keeps them and gives them to the plugin.
## `config.json`
Section: `notification`
@@ -41,4 +44,19 @@ Section: `notification`
| `providers` | Notification provider list | array | Provider list | `[]` |
| `base_url` | Public base URL for absolute poster URLs | string | config only | `""` |
Legacy `type`, `token` and `chat_id` single-provider configs are still read and migrated into `providers`.
Each object in `providers` usually contains:
| Key | Description |
| --- | --- |
| `type` | Provider type: `telegram`, `discord`, `bark`, `server-chan`, `wecom`, `gotify`, `pushover`, `webhook`, or the channel id from a plugin |
| `enabled` | Enable this provider |
| `token` | Used by Telegram (Bot Token), Server Chan (SendKey), WeCom (Key) and Gotify (App Token) |
| `chat_id` | Used by Telegram |
| `webhook_url` | Used by Discord and WeCom |
| `url` | Used by Webhook |
| `server_url` | Used by Bark (optional) and Gotify |
| `device_key` | Used by Bark |
| `user_key` / `api_token` | Used by Pushover |
| `template` | Custom message template |
On the first start after an upgrade to 4.0, the old Bark key `token` moves to `device_key`, and the old WeCom key `chat_id` moves to `webhook_url`.

92
docs/en/config/plugins.md Normal file
View File

@@ -0,0 +1,92 @@
# Plugin Settings
From 4.0, downloaders, rename methods, notification channels, search sites and other functions connect through plugin extension points. The `plugins` section of `config.json` keeps the enable switches, the plugin options and the provider choices.
## WebUI
Manage plugins under **Settings → Plugins**:
- **Allow unsigned plugins**: plugins from the local directory (`config/plugins/local/`) or from pip are unsigned. They load only when this switch is on. Plugins run inside the AutoBangumi process with full privileges. Enable only plugins that you trust.
- **Enabled**: the switch on each plugin card.
- **Options**: expand the card, fill in the form that the plugin declares, then click **Save options**.
These three settings apply immediately. You do not need to click **Save & restart**.
Each plugin card shows the source (built-in, local, pip), the state (running, disabled, error) and the declared permissions. If a plugin fails to load, or is disabled automatically after 5 failures in sequence, the card shows the reason. When you change the options of that plugin, AutoBangumi tries to load it again.
These settings are not on the plugin page. They are in the related settings sections and are saved with the global configuration (**Save & restart**):
- Downloader instances and the default downloader: [Downloader Settings](/en/config/downloader#multiple-downloaders)
- Rename method and revision conflict policy: [Bangumi Manager](/en/config/manager)
## Built-in plugins
| id | Default | Function | Details |
| --- | --- | --- | --- |
| `rename` | enabled | rename methods `pn`, `advance`, `template` | [Bangumi Manager](/en/config/manager#template-rename) |
| `ingest-filters` | enabled | include filter: when you set a list of regular expressions (case-insensitive), only torrents whose name matches one of them are downloaded. Empty means no filter. It applies to all subscriptions | see below |
| `media-server-refresh` | enabled | refreshes Jellyfin / Emby / Plex after organizing. Without a server URL and an API key it does nothing | [Bangumi Manager](/en/config/manager#media-server-refresh) |
| `hardlink` | disabled | hard-links organized files into a media library | [Bangumi Manager](/en/config/manager#hard-links-to-a-media-library) |
The include filter of `ingest-filters` (`include`) adds to the exclude filter of each rule. An invalid regular expression is matched as literal text.
To write plugins, see [Plugin development](/en/dev/plugins).
## `config.json`
Section: `plugins`
| Key | Description | Type | WebUI field | Default |
| --- | --- | --- | --- | --- |
| `allow_unsigned` | Load unsigned plugins (local directory, pip) | boolean | Allow unsigned plugins | `false` |
| `dev_mode` | Reload local plugins when their files change | boolean | config only | `false` |
| `enabled` | Enable switch per plugin id | object | Enabled switch on the plugin card | `{}` |
| `options` | Options per plugin id | object | Options on the plugin card | `{}` |
| `hook_order` | Hook order per extension point | object | config only | `{}` |
| `slots` | Provider selected for each extension point | object | see below | see below |
| `instances` | Instances of multi-instance extension points (now only downloaders) | array | Downloader Settings | one qBittorrent instance with id `default` |
- A plugin that is not in `enabled`: a built-in plugin follows its manifest (enabled, except `hardlink`). A plugin from another source is disabled.
- Values in `options` must pass the validation of the plugin's config model. The WebUI rejects invalid options on save. The API masks password-type fields in its responses.
- The keys of `hook_order` are hook extension points: `torrent.filter`, `title.parsed`, `torrent.adding`, `http.request`, `message_template`. The values are lists of plugin ids. Listed plugins run first, in the listed order. The other plugins follow, sorted by priority and then by plugin id.
### `slots`
| Key | Description | WebUI field | Default |
| --- | --- | --- | --- |
| `downloader` | Id of the default downloader instance. It must be a downloader instance in `instances` | **Set default** in Downloader Settings | `default` |
| `rename_strategy` | Rename method: `none` (host), `pn`, `advance`, `template` (built-in `rename` plugin), or a method from another plugin | Rename Method in Bangumi Manager | `pn` |
| `conflict_policy` | What to do when a higher revision targets an existing episode: `hold` keeps the existing file, `replace` replaces it with the higher revision | Revision Conflict Policy in Bangumi Manager | `hold` |
| `media_files` | Classifies the files in a torrent as video or subtitle. The host implementation uses the file extension | config only | `default` |
If the selected provider is not registered (for example, its plugin is disabled or was stopped after failures), `rename_strategy` is handled as `none`, and `conflict_policy` and `media_files` use the host implementation.
### `instances`
```json
"instances": [
{
"id": "default",
"point": "downloader",
"provider": "qbittorrent",
"options": { "host": "172.17.0.1:8080", "username": "admin", "password": "adminadmin", "path": "/downloads/Bangumi", "ssl": false }
}
]
```
| Key | Description |
| --- | --- |
| `id` | Instance id. It must be unique |
| `point` | Extension point. Now only `downloader` |
| `provider` | Provider id that implements the extension point, for example `qbittorrent`, `aria2` or a downloader from a plugin |
| `options` | Options of the instance. For downloader fields, see [Downloader Settings](/en/config/downloader#config-json) |
## Upgrade from 3.3
On the first start after an upgrade to 4.0, AutoBangumi moves 3.3 settings into the `plugins` section:
- `downloader` → the downloader instance with id `default` in `plugins.instances`. `plugins.slots.downloader` is set to `default`.
- `bangumi_manage.rename_method` → `plugins.slots.rename_strategy` (the removed method `normal` becomes `none`).
- `bangumi_manage.revision_conflict_policy` → `plugins.slots.conflict_policy`.
Before the migration, AutoBangumi copies the original file to `config.json.v3.bak`. It does not overwrite an existing backup. It uses `config.json.v3.bak.1`, `config.json.v3.bak.2` and so on. If the migration fails (for example, the migrated configuration does not pass validation), AutoBangumi restores the original file from the backup and **does not start**. The log names the field that failed. Correct that field, then start again.

View File

@@ -2,7 +2,7 @@
![search provider](/image/config/search-provider.png){width=700}{class=ab-shadow-card}
Search providers power WebUI torrent search and search-based subscription. Built-in providers are `mikan`, `nyaa` and `dmhy`; default providers cannot be deleted, but their URL templates can be edited.
Search providers power WebUI torrent search and search-based subscription. Built-in providers are `mikan`, `anibt`, `nyaa` and `dmhy`; default providers cannot be deleted, but their URL templates can be edited.
Search provider changes are saved immediately to `config/search_provider.json`; they do not use the bottom **Save & restart** button.

View File

@@ -17,7 +17,7 @@ Section: `security`
| --- | --- | --- | --- | --- |
| `login_whitelist` | Login IP whitelist | string array | Login IP Whitelist | `[]` |
| `login_tokens` | Login API tokens | string array | Login API Tokens | `[]` |
| `mcp_whitelist` | MCP IP whitelist | string array | MCP IP Whitelist | local-network CIDRs or `[]` |
| `mcp_whitelist` | MCP IP whitelist | string array | MCP IP Whitelist | `[]` |
| `mcp_tokens` | MCP API tokens | string array | MCP API Tokens | `[]` |
| `webauthn_rp_id` | Passkey RP ID | string | config only | `""` |
| `webauthn_origin` | Passkey origin | string | config only | `""` |

View File

@@ -54,10 +54,13 @@ Docker Bridgeモードでは、ダウンローダーとAutoBangumiが同じネ
}
```
3.3 の `downloader` セクションは、4.0 へのアップグレード後の初回起動時に `default` インスタンスへ自動で移行され、元のファイルは `config.json.v3.bak` として保存されます。環境変数 `AB_DOWNLOADER_HOST`、`AB_DOWNLOADER_USERNAME`、`AB_DOWNLOADER_PASSWORD`、`AB_DOWNLOAD_PATH` は引き続き既定インスタンスに反映されます。
3.3 の `downloader` セクションは、4.0 へのアップグレード後の初回起動時に `default` インスタンスへ自動で移行され、元のファイルは `config.json.v3.bak` として保存されます。移行に失敗した場合は元のファイルを復元して起動を中止します。詳しくは [プラグイン設定](/ja/config/plugins) を参照してください。
環境変数 `AB_DOWNLOADER_HOST`、`AB_DOWNLOADER_USERNAME`、`AB_DOWNLOADER_PASSWORD`、`AB_DOWNLOAD_PATH` は、設定ファイルがまだない初回起動時にだけ読み込まれ、既定インスタンスに反映されます。`host`、`username`、`password` の値には `$VAR` 形式の環境変数参照を書けます。使用時に展開されます。
| キー | 説明 | 型 | WebUI項目 | 既定値 |
| --- | --- | --- | --- | --- |
| `id` | インスタンス id | 文字列 | 新しいダウンローダー id | `default` |
| `provider` | ダウンローダー種類 | 文字列 | ダウンローダー種類 | `qbittorrent` |
| `host` | ダウンローダーアドレス | 文字列 | ホスト | `172.17.0.1:8080` |
| `username` | ユーザー名 | 文字列 | ユーザー名 | `admin` |

View File

@@ -14,6 +14,7 @@
- **話数補完**:不足している話数を補完ダウンロードします。
- **グループタグ追加**:字幕組関連タグをダウンローダータスクに追加します。
- **不良Torrent削除**:エラー状態のタスクを削除します。
- **リビジョン競合ポリシー**:より高いリビジョンのトレントが既存の話数を対象にするとき、「既存ファイルを保持」または「より高いリビジョンに置き換え」を選びます。置き換えを有効にすると、高いリビジョンが配置に成功した後でだけ古いトレントとそのデータを削除します。
- **未一致Torrentを記録**:ルールに一致しないTorrentを孤児レコードとして保存します。
## テンプレートリネーム
@@ -25,7 +26,7 @@
{{ title }} S{{ season|pad(2) }}E{{ episode|pad(2) }}
```
既定値は `pn` と同じ結果になります。サンドボックス化された [Jinja2](https://jinja.palletsprojects.com/) 構文で、次の変数が使えます。
通常のエピソードでは既定値は `pn` と同じ結果になります。劇場版では `pn` は `SxxExx` を付けませんが、既定のテンプレートは付けます。サンドボックス化された [Jinja2](https://jinja.palletsprojects.com/) 構文で、次の変数が使えます。
| 変数 | 意味 | 例 |
| --- | --- | --- |
@@ -63,8 +64,8 @@
- プラグインが作成していない同名ファイルがライブラリにある場合はスキップし、**上書きしません**。通知が送られます。
- リビジョン更新(新しいリリースが同じファイル名で古い Torrent を置き換える)の後、プラグインが以前作成したリンクは新しいファイルへのリンクにアトミックに置き換えられます。
- Torrent を削除しても、ライブラリのリンクは削除されません。
- 有効化する前にダウンロード済みのファイルは自動ではリンクされません。`POST /api/v1/plugins/hardlink/backfill` を呼び出すとリンクします(設定画面のボタンは今後のリリースで提供予定)。
- `path_map` は設定フォームでまだ編集できません。`config/config.json` の `plugins.options.hardlink.path_map` に記入してください(例:`[{"from": "/downloads", "to": "/media/downloads"}]`)。
- 有効化する前にダウンロード済みのファイルは自動ではリンクされません。プラグインを有効にすると設定画面に「Hardlink backfill」セクションが表示されます。**Link existing files** をクリックすると、ダウンロードルートにある本編と字幕をライブラリにリンクします。リンク済みのファイルはスキップされます。このボタンは `POST /api/v1/plugins/hardlink/backfill` を呼び出します。
- `path_map` はプラグインの設定フォームで 1 行ずつ編集できます(**Add row**)。`config/config.json` では `plugins.options.hardlink.path_map` です(例:`[{"downloader": "default", "from": "/downloads", "to": "/media/downloads"}]`)。
::: tip Docker
ハードリンクはファイルシステムをまたげません。Docker では、ダウンロードフォルダーとライブラリを同じディスクに置き、**1 つのマウント**で AutoBangumi コンテナに渡してください(例:`/mnt/media` を `/media` としてまとめてマウントし、両方をその下に置く)。別々にマウントしたフォルダーは同じディスク上でも別のファイルシステムとして扱われ、`cross_device` の設定に従います(既定はコピーで、容量を 2 倍使います)。ダウンローダーが別のコンテナで動作し、見えるパスが異なる場合は `path_map` を使います。
@@ -86,4 +87,4 @@
| `remove_bad_torrent` | エラーTorrent削除 | 真偽値 | 不良Torrent削除 | `false` |
| `track_orphans` | 未一致Torrentを記録 | 真偽値 | 未一致Torrentを記録 | `true` |
リネーム方式とリビジョン競合ポリシーは Provider の選択として `plugins.slots` に保存されます:`rename_strategy`(リネーム方式、既定値 `pn`)と `conflict_policy`(`hold` / `replace`、既定値 `hold`)。3.3 の `bangumi_manage.rename_method` と `revision_conflict_policy` は、4.0 へのアップグレード後の初回起動時に自動で移行されます。
リネーム方式とリビジョン競合ポリシーは Provider の選択として `plugins.slots` に保存されます:`rename_strategy`(リネーム方式、既定値 `pn`)と `conflict_policy`(`hold` / `replace`、既定値 `hold`)。3.3 の `bangumi_manage.rename_method` と `revision_conflict_policy` は、4.0 へのアップグレード後の初回起動時に自動で移行されます。詳しくは [プラグイン設定](/ja/config/plugins#slots) を参照してください。

View File

@@ -21,6 +21,8 @@
Webhookテンプレートでは `{{title}}`、`{{season}}`、`{{episode}}`、`{{poster_url}}` などのプレースホルダーを使えます。
有効なプラグインも通知チャンネルを追加できます。種類の一覧に「From plugin」のラベル付きで表示されます。プラグインチャンネル固有の項目は設定画面に表示されません。必要な場合は `config.json` の該当 provider オブジェクトに記入してください。AutoBangumi はそのまま保存してプラグインに渡します。
## `config.json`
セクション:`notification`
@@ -31,4 +33,19 @@ Webhookテンプレートでは `{{title}}`、`{{season}}`、`{{episode}}`、`{{
| `providers` | 通知provider一覧 | 配列 | provider一覧 | `[]` |
| `base_url` | ポスターURLを絶対URLにする公開URL | 文字列 | 設定ファイルのみ | `""` |
旧形式の `type`、`token`、`chat_id` は読み込み時に `providers` へ移行されます。
`providers` の各オブジェクトには通常次の項目があります。
| キー | 説明 |
| --- | --- |
| `type` | provider の種類:`telegram`、`discord`、`bark`、`server-chan`、`wecom`、`gotify`、`pushover`、`webhook`、またはプラグインのチャンネル id |
| `enabled` | この provider を有効にする |
| `token` | Telegram(Bot Token)、Server Chan(SendKey)、WeCom(Key)、Gotify(App Token)で使用 |
| `chat_id` | Telegram で使用 |
| `webhook_url` | Discord、WeCom で使用 |
| `url` | Webhook で使用 |
| `server_url` | Bark(任意)、Gotify で使用 |
| `device_key` | Bark で使用 |
| `user_key` / `api_token` | Pushover で使用 |
| `template` | カスタム通知テンプレート |
4.0 へのアップグレード後の初回起動時に、Bark の旧項目 `token` は `device_key` へ、WeCom の旧項目 `chat_id` は `webhook_url` へ移行されます。

92
docs/ja/config/plugins.md Normal file
View File

@@ -0,0 +1,92 @@
# プラグイン設定
4.0 から、ダウンローダー、リネーム、通知チャンネル、検索サイトなどの機能はプラグインの拡張ポイントを通じて接続されます。プラグインの有効/無効、設定、Provider の選択は `config.json` の `plugins` セクションに保存されます。
## WebUI
**設定 → プラグイン** でプラグインを管理します。
- **未署名プラグインを許可**:ローカルディレクトリ(`config/plugins/local/`)と pip でインストールしたプラグインは署名されていません。オンにしたときだけ読み込まれます。プラグインは AutoBangumi と同じプロセスで完全な権限を持って動作します。信頼できるプラグインだけを有効にしてください。
- **有効**:各プラグインカードのスイッチです。
- **設定**:カードを開き、プラグインが宣言したフォームに入力して **設定を保存** をクリックします。
この 3 つは保存するとすぐに反映されます。**保存して再起動** をクリックする必要はありません。
プラグインカードには、ソース(内蔵、ローカル、pip)、状態(実行中、無効、エラー)、宣言された権限が表示されます。読み込みに失敗したプラグインや、連続 5 回失敗して自動で無効になったプラグインは、カードに理由が表示されます。そのプラグインの設定を変更すると、再度読み込みを試みます。
次の設定はプラグインページではなく、各機能の設定セクションにあり、全体の設定と一緒に保存されます(**保存して再起動**)。
- ダウンローダーインスタンスと既定のダウンローダー:[ダウンローダー設定](/ja/config/downloader#複数のダウンローダー)
- リネーム方式とリビジョン競合ポリシー:[アニメ管理設定](/ja/config/manager)
## 内蔵プラグイン
| id | 既定 | 機能 | 詳細 |
| --- | --- | --- | --- |
| `rename` | 有効 | リネーム方式 `pn`、`advance`、`template` | [アニメ管理設定](/ja/config/manager#テンプレートリネーム) |
| `ingest-filters` | 有効 | 包含フィルター:正規表現(大文字小文字を区別しない)を設定すると、いずれかに一致する名前のトレントだけをダウンロードします。空欄ならフィルターしません。すべての購読に適用されます | 下記参照 |
| `media-server-refresh` | 有効 | 整理完了後に Jellyfin / Emby / Plex を更新します。サーバーアドレスと API Key が未入力なら何もしません | [アニメ管理設定](/ja/config/manager#メディアサーバーの更新) |
| `hardlink` | 無効 | 整理済みファイルをメディアライブラリにハードリンクします | [アニメ管理設定](/ja/config/manager#メディアライブラリへのハードリンク) |
`ingest-filters` の包含フィルター(`include`)は、ルールの除外フィルターを補います。不正な正規表現は文字どおりに照合されます。
プラグインの開発は [プラグイン開発](/ja/dev/plugins) を参照してください。
## `config.json`
セクション:`plugins`
| キー | 説明 | 型 | WebUI項目 | 既定値 |
| --- | --- | --- | --- | --- |
| `allow_unsigned` | 未署名(ローカルディレクトリ、pip)のプラグインを読み込む | 真偽値 | 未署名プラグインを許可 | `false` |
| `dev_mode` | ローカルプラグインのファイル変更時に自動で再読み込み | 真偽値 | 設定ファイルのみ | `false` |
| `enabled` | プラグイン id ごとの有効スイッチ | オブジェクト | プラグインカードの有効スイッチ | `{}` |
| `options` | プラグイン id ごとの設定 | オブジェクト | プラグインカードの設定 | `{}` |
| `hook_order` | 拡張ポイントごとのフック実行順 | オブジェクト | 設定ファイルのみ | `{}` |
| `slots` | 各拡張ポイントで選ぶ Provider | オブジェクト | 下表参照 | 下表参照 |
| `instances` | 複数インスタンスの拡張ポイントのインスタンス一覧(現在はダウンローダーのみ) | 配列 | ダウンローダー設定 | id が `default` の qBittorrent インスタンス 1 つ |
- `enabled` にないプラグイン:内蔵プラグインはマニフェストに従います(`hardlink` 以外は有効)。それ以外のソースのプラグインは無効です。
- `options` の値はプラグインの設定モデルの検証に合格する必要があります。WebUI で保存するとき、不正な設定は拒否されます。パスワード系の項目は API の応答でマスクされます。
- `hook_order` のキーはフック拡張ポイント(`torrent.filter`、`title.parsed`、`torrent.adding`、`http.request`、`message_template`)、値はプラグイン id のリストです。リストにあるプラグインがその順で最初に実行され、残りは優先度、次にプラグイン id の順です。
### `slots`
| キー | 説明 | WebUI項目 | 既定値 |
| --- | --- | --- | --- |
| `downloader` | 既定のダウンローダーインスタンス id。`instances` 内のダウンローダーインスタンスである必要があります | ダウンローダー設定の **既定に設定** | `default` |
| `rename_strategy` | リネーム方式:`none`(ホスト内蔵)、`pn`・`advance`・`template`(内蔵プラグイン `rename`)、または他のプラグインの方式 | アニメ管理設定のリネーム方式 | `pn` |
| `conflict_policy` | より高いリビジョンが既存の話数を対象にするとき:`hold` は既存ファイルを保持、`replace` は高いリビジョンに置き換え | アニメ管理設定のリビジョン競合ポリシー | `hold` |
| `media_files` | トレント内のファイルが本編か字幕かを判定する実装。ホスト内蔵の実装は拡張子で判定します | 設定ファイルのみ | `default` |
選んだ Provider が登録されていない場合(提供するプラグインが無効、または失敗で停止された場合など)、`rename_strategy` は `none` として扱われ、`conflict_policy` と `media_files` はホスト内蔵の実装を使います。
### `instances`
```json
"instances": [
{
"id": "default",
"point": "downloader",
"provider": "qbittorrent",
"options": { "host": "172.17.0.1:8080", "username": "admin", "password": "adminadmin", "path": "/downloads/Bangumi", "ssl": false }
}
]
```
| キー | 説明 |
| --- | --- |
| `id` | インスタンス id。重複できません |
| `point` | 拡張ポイント。現在は `downloader` のみ |
| `provider` | 拡張ポイントを実装する Provider id。例:`qbittorrent`、`aria2`、プラグインのダウンローダー |
| `options` | インスタンスの設定。ダウンローダーの項目は [ダウンローダー設定](/ja/config/downloader#config-json) を参照 |
## 3.3 からのアップグレード
4.0 へのアップグレード後の初回起動時に、3.3 の設定が `plugins` セクションへ移行されます。
- `downloader` → `plugins.instances` の id が `default` のダウンローダーインスタンス。`plugins.slots.downloader` は `default` になります。
- `bangumi_manage.rename_method` → `plugins.slots.rename_strategy`(廃止された `normal` は `none` になります)。
- `bangumi_manage.revision_conflict_policy` → `plugins.slots.conflict_policy`。
移行前に元のファイルは `config.json.v3.bak` にバックアップされます。既存のバックアップは上書きせず、`config.json.v3.bak.1`、`config.json.v3.bak.2` などを使います。移行に失敗した場合(移行後の設定が検証に通らない場合など)、バックアップから元のファイルを復元して**起動を中止**し、失敗した項目をログに記録します。その項目を修正してから再起動してください。

View File

@@ -2,7 +2,7 @@
![search provider](/image/config/search-provider.png){width=700}{class=ab-shadow-card}
検索プロバイダーはWebUIのTorrent検索と検索ベースの購読に使われます。内蔵providerは `mikan`、`nyaa`、`dmhy` です。既定providerは削除できませんが、URLテンプレートは編集できます。
検索プロバイダーはWebUIのTorrent検索と検索ベースの購読に使われます。内蔵providerは `mikan`、`anibt`、`nyaa`、`dmhy` です。既定providerは削除できませんが、URLテンプレートは編集できます。
検索プロバイダーの変更は `config/search_provider.json` に即時保存されます。下部の **保存して再起動** は不要です。

View File

@@ -17,7 +17,7 @@
| --- | --- | --- | --- | --- |
| `login_whitelist` | ログインIPホワイトリスト | 文字列配列 | ログインIPホワイトリスト | `[]` |
| `login_tokens` | ログインAPIトークン | 文字列配列 | ログインAPIトークン | `[]` |
| `mcp_whitelist` | MCP IPホワイトリスト | 文字列配列 | MCP IPホワイトリスト | ローカルネットワークCIDRまたは `[]` |
| `mcp_whitelist` | MCP IPホワイトリスト | 文字列配列 | MCP IPホワイトリスト | `[]` |
| `mcp_tokens` | MCP APIトークン | 文字列配列 | MCP APIトークン | `[]` |
| `webauthn_rp_id` | Passkey RP ID | 文字列 | 設定ファイルのみ | `""` |
| `webauthn_origin` | Passkey Origin | 文字列 | 設定ファイルのみ | `""` |