Auto_Bangumi/docs/ja/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 形式に書き換えられている場合があります。3.3.x に戻す前に、`config.json.v3.bak` で `config.json` を上書きしてください。
2. **コンテナを停止し、`config` と `data` の 2 つのフォルダーをバックアップします。** 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 の環境は、次の pull で 4.0 にアップグレードされます。先に上記のバックアップを取ってください |
| `3.3.7` | 3.3 の最後のリリース。当面 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 が表示され、**今すぐ更新** を押すと、イメージが古いため新しいイメージを pull するよう求めるエラーで失敗します。前の節のとおりイメージタグを変更してください。

## 初回起動：設定の移行

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` へのフォールバックはしません。
- **設定 → プラグイン** で `rename` プラグインを無効にすると、すべてのアニメが `none` として扱われ、元のファイル名が保たれます。

詳しくは [アニメ管理設定](../config/manager) を参照してください。

### メディアライブラリへのハードリンク

新しい内蔵プラグイン `hardlink` は**既定で無効**です。有効にすると、トレントの整理が終わったときに動画と字幕をメディアライブラリのフォルダーにリンクします。ダウンロードフォルダーはそのまま残り、シードを続けます。

- ダウンローダーと AB から見えるパスが異なる場合（別々のコンテナで動いている場合など）、ダウンローダーインスタンスごとに `path_map` でパスの対応を設定します。
- ハードリンクを作れない場合（ファイルシステムが異なる場合）、既定ではファイルをコピーします（`cross_device: copy`）。
- Docker では、メディアライブラリのフォルダーも AB コンテナにマウントする必要があります。ハードリンクを使うには、ダウンロードフォルダーとメディアライブラリを同じディスクに置き、1 つのマウントポイントでコンテナにマウントしてください。

詳しくは [アニメ管理設定](../config/manager) を参照してください。

### その他の内蔵プラグイン

- トレントフィルタープラグイン `ingest-filters` は既定で有効です。`include` オプションが空のときは何もフィルターしません。
- `media-server-refresh` は既定で有効です。Jellyfin / Emby / Plex のアドレスと API キーを設定したときだけ、ライブラリの更新を要求します。

### サードパーティープラグイン

ローカルフォルダー（`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` と表示されますが、動作は同じでファイル名を変更しません。
- [ ] **設定 → プラグイン** で `rename` プラグインが有効になっている。
- [ ] Bark または WeCom の通知を使っている場合、テスト通知を送る。
- [ ] ハードリンクやメディアサーバーの更新が必要な場合、**設定 → プラグイン** で有効にして設定する。
- [ ] 3.2 の GET 制御エンドポイントを使うスクリプトを POST に変更した。

## 3.3 へのロールバック

4.x は実行バージョンを `config/version_v4.info` に書き込み、`config/version.info` は変更しません。そのため 3.3 は起動時にデータのバージョンを誤認しません。4.x は起動するたびに、データベースがまだ 3.3 の構造であれば、それを `data/data.db.v3.bak` にバックアップします（古いバックアップは置き換えられます）。

**アップグレード前の完全なバックアップがある場合**（推奨）：

1. コンテナを停止します。
2. `config` と `data` フォルダーを `config.bak-3.3` と `data.bak-3.3` で置き換えます。
3. イメージタグを 3.3（例：`3.3.6`）に戻し、コンテナを作り直します。

4.0 で行った変更（新しいアニメ、新しい購読、新しい設定）はすべて失われます。

**完全なバックアップがない場合：**

1. コンテナを停止します。
2. 番号が最も大きい `config/config.json.v3.bak.N` で `config/config.json` を上書きします（1 つしかない場合は `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` を上書きします。4.0 がテーブルを変更したデータベースは 3.3 では使えません。この 2 つのファイルを残すと、SQLite がその中の 4.0 の変更を復元したデータベースに書き戻します。
4. 4.0 でアプリ内更新を使った場合は、`config/updates/` フォルダーを削除します。削除しないと、3.3 のイメージが起動時にそこにある新しい 4.0 のコードを読み込みます。
5. イメージタグを 3.3（例：`3.3.6`）に戻し、コンテナを作り直します。

この方法ではアップグレード時の状態に戻ります。4.0 で追加・変更したアニメ、トレントの記録、設定はすべて失われます。

再び 4.0 にアップグレードすると移行がもう一度実行されます。設定の新しいバックアップは `config.json.v3.bak.1` などに保存され、`data.db.v3.bak` はロールバック後の 3.3 のデータベースに置き換えられます。