Auto_Bangumi/docs/deploy/upgrade-4.0.md

# 从 3.3 升级到 4.0

4.0 是插件化重构的大版本：下载器改为可以有多个的实例，重命名、硬链接、种子过滤、媒体库刷新改由内置插件提供。第一次启动时，AB 会自动把 3.3 的配置迁移到新位置。本页说明迁移改了什么、如何升级、升级后检查什么，以及如何回滚到 3.3。

## 升级前

1. **确认当前版本是 3.3.x。** 4.0 只支持从 3.3.x 升级。检测到更早版本的数据（`config/version.info` 记录的版本低于 3.3，或残留 2.x 的 `data/data.json`）时，AB 拒绝启动，并提示先升级到最新的 3.3.x 启动一次。被拒绝时 `config.json` 可能已经被改写为 4.0 格式，请先用 `config.json.v3.bak` 覆盖它，再换回 3.3.x。
2. **停止容器，备份 `config` 与 `data` 两个目录。** 回滚到 3.3 时需要这两份备份（见 [回滚到 3.3](#回滚到-3-3)）。

```shell
docker stop AutoBangumi
cp -a ${HOME}/AutoBangumi/config ${HOME}/AutoBangumi/config.bak-3.3
cp -a ${HOME}/AutoBangumi/data ${HOME}/AutoBangumi/data.bak-3.3
```

## 更换镜像标签

4.0 的镜像标签：

| 标签 | 含义 |
| --- | --- |
| `4.0.0` | 指定的版本。**推荐**，升级与回滚都可控 |
| `latest` | 最新正式版，现在是 4.0。仍在使用 `latest` 的 3.3 用户，拉取新镜像就会升级到 4.0，请先完成上面的备份 |
| `3.3.7` | 3.3 的最后一个版本。暂时不升级时把标签固定为它 |

镜像同时发布到 `ghcr.io/estrellaxd/auto_bangumi` 与 Docker Hub 的 `estrellaxd/auto_bangumi`。

Docker Compose：修改 `image` 后重新创建容器。

```yaml
services:
  AutoBangumi:
    image: "ghcr.io/estrellaxd/auto_bangumi:4.0.0"
```

```shell
docker compose pull
docker compose up -d
```

Docker CLI：删除旧容器，用新标签和原来的参数重新运行 `docker run`。

挂载卷（`/app/config`、`/app/data`）、端口与环境变量都没有变化，4.0 没有新增环境变量。插件安装在 `config/plugins/` 下，已经包含在 `/app/config` 卷里。

### 应用内更新

应用内更新不能把 3.3 升级到 4.0：4.0 的更新包要求镜像版本不低于 `4.0.0-beta.1`。3.3.7 起，**设置 → 软件更新** 在稳定版与测试版渠道都只提供 3.x 版本。更早的 3.3.x 会显示 4.0，点击 **立即更新** 会失败，提示镜像版本过低、需要拉取新镜像。请按上一节更换镜像标签。

## 第一次启动：配置迁移

AB 在读取 `config.json` 之前检查它是不是 3.3 格式。是 3.3 格式时，先把原文件备份为 `config.json.v3.bak`，再把下列字段移到 4.0 的位置：

| 3.3 字段 | 4.0 位置 |
| --- | --- |
| `downloader` | `plugins.instances` 中 id 为 `default` 的下载器实例：`type` 变为 `provider`，其它字段（地址、用户名、密码、下载路径、SSL）放入 `options` |
| — | `plugins.slots.downloader` 设为 `"default"`（默认下载器实例） |
| `bangumi_manage.rename_method` | `plugins.slots.rename_strategy`。已废弃的 `normal` 改为语义相同的 `none` |
| `bangumi_manage.revision_conflict_policy` | `plugins.slots.conflict_policy` |
| Bark 渠道的 `token` | `device_key` |
| WeCom 渠道的 `chat_id` | `webhook_url` |

迁移前后的下载器配置示例：

::: code-group

```json [3.3]
{
  "downloader": {
    "type": "qbittorrent",
    "host": "172.17.0.1:8080",
    "username": "admin",
    "password": "adminadmin",
    "path": "/downloads/Bangumi",
    "ssl": false
  },
  "bangumi_manage": {
    "rename_method": "pn",
    "revision_conflict_policy": "hold"
  }
}
```

```json [4.0]
{
  "plugins": {
    "slots": {
      "downloader": "default",
      "rename_strategy": "pn",
      "conflict_policy": "hold"
    },
    "instances": [
      {
        "id": "default",
        "point": "downloader",
        "provider": "qbittorrent",
        "options": {
          "host": "172.17.0.1:8080",
          "username": "admin",
          "password": "adminadmin",
          "path": "/downloads/Bangumi",
          "ssl": false
        }
      }
    ]
  }
}
```

:::

示例只列出相关字段；其它设置保持原样。

- **备份不会被覆盖。** 已有 `config.json.v3.bak` 时（例如回滚到 3.3 后再次升级），新的备份另存为 `config.json.v3.bak.1`、`config.json.v3.bak.2` 等。第一份备份里是最早的 3.3 配置。
- **迁移成功**时，日志出现 `Migrated config.json to 4.0 (...); the 3.3 file is kept as config.json.v3.bak`，括号里列出被移动的字段。
- **迁移失败**时，`config.json` 保持 3.3 的内容，AB 拒绝启动，日志写明出错的字段。修正该字段后重新启动即可。
- 已经是 4.0 格式的配置不会再迁移，也不会再生成备份。
- 环境变量（`AB_DOWNLOADER_HOST`、`AB_METHOD` 等）照常生效，仍然只在没有 `config.json` 的首次启动时读取；它们的值写入默认下载器实例与 `plugins.slots`。

数据库在同一次启动中自动升级到 schema v28：新增插件存储表 `plugin_kv`，番剧、电影、RSS 订阅与种子新增 `downloader_id` 列；aria2 的任务映射表按下载器实例重建；从搜索结果建立的订阅，关键词中的集号被去掉（每条改动记入日志）。已有种子归属 `default` 实例；已有规则与订阅的 `downloader_id` 为空，表示跟随默认实例。

## 4.0 中改变的行为

### 多个下载器

**设置 → 下载设置** 可以添加多个下载器实例（qBittorrent、aria2 或插件提供的下载器）并指定默认实例。规则与 RSS 订阅可以选择下载器，留空时用默认实例。每个种子记录它所在的下载器，重命名与删除都在该下载器上进行。详见 [下载器设置](../config/downloader)。

### 重命名改为插件

`pn`、`advance` 与新增的 `template` 由默认启用的内置插件「重命名」（`rename`）提供，`none` 由 AB 本身提供。`pn` 与 `advance` 的输出与 3.3 逐字一致。

- `template` 用自定义模板生成文件名。保存设置时 AB 试渲染模板，不合法的模板直接拒绝保存。
- 运行时某个文件的模板渲染失败，该文件保留原名，并发送「文件未重命名」通知；不会退回 `pn`。
- 在 **设置 → 插件** 中停用「重命名」插件后，所有番剧按 `none` 处理，保留原文件名。

详见 [番剧管理设置](../config/manager)。

### 硬链接到媒体库

新增内置插件「硬链接到媒体库」（`hardlink`），**默认停用**。启用后，种子整理完成时把正片与字幕链接到媒体库目录，下载目录保持原样继续做种。

- 下载器与 AB 看到的路径不同时（例如分别运行在不同容器中），按下载器实例在 `path_map` 中配置路径映射。
- 无法创建硬链接（跨文件系统）时，默认复制文件（`cross_device: copy`）。
- 在 Docker 中，媒体库目录也要挂载进 AB 容器。要使用硬链接，请把下载目录与媒体库放在同一块盘上，并以同一个挂载点映射进容器。

详见 [番剧管理设置](../config/manager)。

### 其它内置插件

- 「种子过滤」（`ingest-filters`）默认启用。「包含过滤」留空时不过滤任何种子。
- 「媒体库刷新」（`media-server-refresh`）默认启用。填写 Jellyfin / Emby / Plex 的地址与 API Key 后才会请求刷新媒体库。

### 第三方插件

本地目录（`config/plugins/local/`）与 pip 安装的插件没有签名，需要在 **设置 → 插件** 中开启「允许未签名插件」（`plugins.allow_unsigned`）才会加载。插件开发见 [插件开发](../dev/plugins)。

### 移除的功能

- 3.2 兼容的 GET 控制端点（`/api/v1/restart`、`/start`、`/stop`、`/shutdown`）和 `GET /api/v1/auth/refresh_token`。请改用 POST。调用这些端点的脚本需要修改。
- 旧版 `experimental_openai` 配置节与通知的单渠道旧字段。3.3 已把它们迁移到 `llm` 与 `notification.providers`。

## 升级后检查

- [ ] 日志中有 `Migrated config.json to 4.0` 一行，`config` 目录中有 `config.json.v3.bak`。
- [ ] **设置 → 下载设置** 中有 id 为 `default` 的实例，地址、用户名与下载路径与 3.3 相同，并且能连接。
- [ ] 重命名方式与 3.3 相同。3.3 中的 `normal` 现在显示为 `none`，行为相同：不重命名文件。
- [ ] **设置 → 插件** 中「重命名」插件处于启用状态。
- [ ] 使用 Bark 或 WeCom 通知时，发送一条测试通知。
- [ ] 需要硬链接或媒体库刷新时，在 **设置 → 插件** 中启用并配置它们。
- [ ] 使用 3.2 的 GET 控制端点的脚本已改为 POST。

## 回滚到 3.3

4.x 把运行版本写入 `config/version_v4.info`，不改动 `config/version.info`，所以 3.3 启动时不会误判数据版本。4.x 每次启动时，如果数据库还是 3.3 的结构，AB 先把它备份为 `data/data.db.v3.bak`（替换旧的备份）。

**有升级前的完整备份时**（推荐）：

1. 停止容器。
2. 用 `config.bak-3.3` 与 `data.bak-3.3` 替换 `config` 与 `data` 目录。
3. 把镜像标签改回 3.3（例如 `3.3.6`），重新创建容器。

升级后在 4.0 中做的修改（新番剧、新订阅、新设置）全部丢失。

**没有完整备份时：**

1. 停止容器。
2. 用编号最大的 `config/config.json.v3.bak.N` 覆盖 `config/config.json`（只有一份时就是 `config.json.v3.bak`）。3.3 不认识 `plugins.instances`，不还原时下载器设置会变成默认值。
3. 删除 `data/data.db-wal` 与 `data/data.db-shm`（如果存在），再用 `data/data.db.v3.bak` 覆盖 `data/data.db`。3.3 不认识 4.0 改动过的数据表，不能继续使用 4.0 的数据库。不删除这两个文件时，SQLite 会把其中 4.0 的改动重新写回还原的数据库。
4. 如果在 4.0 中使用过应用内更新，删除 `config/updates/` 目录。否则 3.3 镜像启动时会加载其中更新的 4.0 代码。
5. 把镜像标签改回 3.3（例如 `3.3.6`），重新创建容器。

这种方式回到升级 4.0 时的状态：在 4.0 中新增的番剧、种子记录与修改的设置全部丢失。

以后再次升级到 4.0 时，迁移会重新运行：配置的新备份另存为 `config.json.v3.bak.1` 等，数据库备份 `data.db.v3.bak` 被替换为回滚后的 3.3 数据库。