本番配置の準備を追加(ステップ7) #11

Merged
kazu634 merged 1 commits from deploy-setup into main 2026-10-04 12:20:08 +09:00
5 changed files with 263 additions and 10 deletions
+1 -1
View File
@@ -1,4 +1,4 @@
DATABASE_URL=
VIDEO_HOST_DIR=
VIDEO_HOST_DIR=/mnt/nas-tver/tver
VIDEO_DIR=/videos
WORKER_CONCURRENCY=1
+21 -9
View File
@@ -3,7 +3,7 @@ title: tver の現状
tags:
- homelab
- tver
status: worker の登録番組確認を実装中
status: 本番配置を準備中
---
# tver の現状
@@ -14,7 +14,7 @@ status: worker の登録番組確認を実装中
## 今の状態
- Go の HTTP サーバー、TVer API クライアント、ドラマ・バラエティの新着表示、テスト、web・worker コンテナの定義がある
- **worker のダウンロード本体と登録番組の定期確認を実装中。** 待ち行列からの取得に加え、有効な登録番組の新しい回を確認して自動登録する
- web・worker・登録番組の定期確認まで実装済み。本番配置に向けて、NAS用PostgreSQL定義と配置手順を整備している
- リポジトリ: `https://gitea.kazu634.com/kazu634/tver.git`
## 目的
@@ -27,17 +27,20 @@ TVer(`https://tver.jp/`)で公開中の動画情報を取得し、選んだ
|---|---|
| TVer 利用規約との関係 | 鑑賞を前提とするダウンロードのため、問題無しと判断(ユーザー判断) |
| 利用者・公開範囲 | 自分のみ・**LAN 内だけ**。EC2 nginx では公開しない |
| 保存先 | **NAS(ds923p)** |
| 保存先 | **NAS(ds923p)の `/volume1/video/tver`**。既存の`anime`・`drama`・`misc`・`personal`・`variety`と分け、admin相当の書き込み範囲を限定する。`/volume1/video`をdockageの`/mnt/nas-tver`へNFSマウントし、`.env`は`VIDEO_HOST_DIR=/mnt/nas-tver/tver`とする |
| 自動ダウンロード | **作る**(番組を登録し、新しい回を自動でダウンロードする) |
| 再生 | **アプリの中で再生する** |
| ダウンロード | yt-dlp を使う |
| デプロイ | Dockge で管理する複数コンテナ構成。dockage VM の `/opt/stacks/tver` |
| デプロイ | 公開リポジトリをdockage VMの`/opt/stacks/tver`へcloneし、Dockgeでbuild・起動する。更新は`git pull --ff-only`後に再ビルドする |
| 開発言語 | **Go**(`web`・`worker` とも)。yt-dlp は外部コマンドとして呼び、進捗・結果は yt-dlp の出力から読み取る |
| DB | **NAS 上の tver 専用 Postgres 17 コンテナ**(Gitea と同じ方式)。バックアップは規約どおり `pg_dump` → NAS。公開ポートは未定(候補 15434、実機で確認する) |
| DB | **NAS上のtver専用Postgres 17コンテナ**(Giteaと同じ方式)。ユーザー・DB名は`tver`、公開ポートは`15434`。ポートが空いているかは未確認 [要確認] |
| DB ドライバ | `github.com/jackc/pgx/v5` の `pgxpool` |
| DB テスト | `github.com/fergusstrange/embedded-postgres` v1.34.0 の Postgres 17 を起動する。Apple Silicon では Rosetta 2 が必要 |
| 定期実行 | **`worker` 内のスケジューラ** |
| NAS のマウント | **NFS**。DSM で `192.168.10.155` のみ許可する |
| NAS のマウント | **NFS**。dockageの`/etc/fstab`へ`_netdev,nofail`付きで登録し、DSMでは接続元`192.168.10.155`だけを許可する |
| NFS 権限 | 読み書き、Squash「すべてのユーザーをadminに割り当てる」、`sys`、非同期オン。DSMのadminアカウントが無効でもUID `65532`から書き込み確認済み |
| DBの通信制限 | DSMファイアウォールでTCP `15434`を`192.168.10.155`からだけ許可する |
| DBバックアップ | 稼働後に、コンテナ内の`pg_dump`からNASへ保存する日次処理を用意する |
| 保持期間 | **削除は手動のみ**。自動削除はしない |
| 待ち行列 | **Postgres のテーブルだけで実装する**。専用のキュー基盤は持たない |
| 定期確認の間隔 | 登録番組の新しい回を **24 時間ごと**に確認する |
@@ -99,6 +102,8 @@ TVer(`https://tver.jp/`)で公開中の動画情報を取得し、選んだ
- 「予告を隠す」は既定でオンとし、180 秒以下の件を非表示にする。長さは秒から分へ切り上げて表示し、配信終了日時は Asia/Tokyo で表示する。ジャンルと予告表示の状態は URL に残す
- 画面は `html/template` と htmx 2.0.11 を使い、htmx は Go の `embed` から `/static/` でローカル配信する
- `compose.yaml` は web と worker を定義する。web は dockage VM の LAN アドレス `192.168.10.155:8080` で公開し、待ち受けは `WEB_ADDR` で変更できる。両方へ `DATABASE_URL` と同じ動画ボリュームを渡し、worker の並行数は `WORKER_CONCURRENCY`(既定1、最大2)で指定する
- NAS用の`deploy/nas/tver-db/compose.yaml`は`postgres:17`を`15434:5432`で公開し、`/volume1/docker/tver-db/pgdata`へ保存する。パスワードは同ディレクトリのGit管理外`.env`から注入する
- 本番配置と更新の手順は[[docs/deploy|tver 本番配置手順]]にまとめる。dockageでは`/volume1/video`を`/mnt/nas-tver`へNFSマウントし、その配下の`tver`だけをコンテナ内の`/videos`へ渡す
- DB は NAS 上に tver 専用 Postgres 17 コンテナを置く。`internal/store` の埋め込み SQL を `schema_migrations` で管理し、`pg_advisory_lock` で複数プロセスからの同時適用を直列化する。web は起動時に `pgxpool` で接続してマイグレーションを適用する
- `download_jobs` は `episode_id` を一意にして二重登録を防ぎ、ジョブの状態・段階別進捗・結果を持つ。`subscriptions` はシリーズ単位の登録と最終確認日時を持つ。worker からの操作と画面用の一覧取得を `internal/store` にまとめる
- worker は `yt-dlp[default]` と ffmpeg を外部コマンドとして使い、映像・音声・結合・移動の段階別進捗を1秒間隔に間引いて保存する。独立した heartbeat を5秒ごとに更新し、正確な全体パーセントは保存しない。`after_move:filepath` で実パスを取り、ffprobe で H.264 と AAC の MP4 を確認して成功とする。失敗は取り消し、DRM、地域制限、ネットワーク、配信不可、抽出失敗、出力不正、その他の順に扱い、自動再試行しない
@@ -112,8 +117,8 @@ TVer(`https://tver.jp/`)で公開中の動画情報を取得し、選んだ
| TVer `platform-api.tver.jp` | 新着一覧(`/service/api/v1/callNewerDetail/{drama\|variety}`)・番組のエピソード一覧 | **非公開 API**。セッションは `/v2/api/platform_users/browser/create` で発行する(yt-dlp と同じ方式) |
| TVer `service-api.tver.jp` | 番組の season 一覧(`/api/v1/callSeriesSeasons/{series_id}`) | **非公開 API**。[yt-dlp の TVer extractor](https://github.com/yt-dlp/yt-dlp/blob/master/yt_dlp/extractor/tver.py) と同じ取得方式 |
| yt-dlp | ダウンロード | TVer extractor を使う |
| NAS ds923p(NFS) | 動画の保存先 | DSM で NFS を有効化し、共有フォルダを `192.168.10.155` のみに許可する |
| NAS ds923p(Postgres 17) | DB | tver 専用コンテナを使う。DSM 内蔵の Postgres が `5432` を使うため別ポートで公開し、DSM ファイアウォールで `192.168.10.155` のみ許可する。公開ポートは実機で決める |
| NAS ds923p(NFS) | 動画の保存先 | `/volume1/video`をdockageの`/mnt/nas-tver`へNFSv3でマウントし、アプリは`tver`サブフォルダを使う。DSMのNFS権限は`192.168.10.155`のみ |
| NAS ds923p(Postgres 17) | DB | tver専用コンテナを`15434:5432`で公開し、DSMファイアウォールで`192.168.10.155`のみ許可する。`15434`の空きは未確認 [要確認] |
## 確認済みの事実
@@ -127,13 +132,18 @@ TVer(`https://tver.jp/`)で公開中の動画情報を取得し、選んだ
- 到達不能のプロキシ経由の通信失敗と存在しないエピソードは、ともに yt-dlp の終了コード 1 だった。stderr の文言で分類が必要。DRM・地域制限の失敗文言と終了コードは実測していない(yt-dlp の extractor ソースのみ確認) [実機] 2026-10-03 確認
- yt-dlp の TVer extractor は日本のみ(`_GEO_COUNTRIES = ['JP']`)。DRM 付きの作品は取得できない [公式] https://github.com/yt-dlp/yt-dlp/blob/master/yt_dlp/extractor/tver.py (取得日: 2026-10-03)
- dockage VM に NAS のマウントは無い。ルートの空きは約 20GB [実機] 2026-10-03 確認
- DSMのNFS権限を接続元`192.168.10.155`、読み書き、全ユーザーをadminへ割り当て、`sys`、非同期オンにすると、dockageからNFSv3で`/volume1/video`をマウントできた。設定直後の1回目は`access denied`、直後の2回目は成功したため、権限の反映待ちと考えられる [実機] 2026-10-04 確認
- DSMのadminアカウントが無効でも、UID `65532`のコンテナから`tver`サブフォルダの作成・書き込み・読み込み・rename・削除に成功した。NAS上の所有者はUID `1024`・GID `100`。`/mnt/nas-tver/tver`は作成済み [実機] 2026-10-04 確認
- NFSマウントのファイル名上限は`namlen=255` [実機] 2026-10-04 確認
## 課題
- 新着 API が 100 件で打ち切りか、続きを取得できるか [要確認]
- 新着のうち DRM 付きの作品の割合 [要確認]
- 非公開 API と yt-dlp の TVer 対応は、TVer 側の変更で予告なく壊れうる。壊れたことを検知する手段が要る
- NAS の準備(NFS 共有フォルダ、tver 専用 Postgres 17 コンテナ、DSM ファイアウォール)は DSM での手作業になる。DB の公開ポート(候補 15434)は本番前に実機で確認する [要確認]
- Container ManagerとDSMで、DB公開ポート`15434`が未使用か確認する [要確認]
- ファイル名の各入力要素をUTF-8で60バイトに制限している。NFSマウントの`namlen=255`を判断材料に、この上限を維持するかは今後検討する
- 稼働後に、コンテナ内の`pg_dump`→gzip→NAS `/volume1/backups/tver/`、既定14日保持のバックアップを用意する
- DRM・地域制限の yt-dlp 失敗時の文言と終了コードは未実測 [要確認]
## 確かめ方
@@ -147,5 +157,7 @@ TVer(`https://tver.jp/`)で公開中の動画情報を取得し、選んだ
- ライブラリのテストは一時ディレクトリの小さな動画を使い、Range の 206・範囲外の 416、相対パスとシンボリックリンクの検査、404、ファイル削除後の記録削除を確認する。共有のファイル名規則は `internal/media` でテストする
- worker のテストは `internal/worker/testdata` の偽 yt-dlp・ffprobe を使い、本物の TVer へ接続せずに正常完了、失敗分類、取消、終了時の待機復帰、進捗の間引き、heartbeat、出力検査、移動先、作業場所の片付けを確認する
- 登録番組の定期確認は偽の TVer クライアントと差し替え可能な時計・タイマーを使い、24時間の境界、順次確認、1時間走査、失敗記録、予告の既知化、終了時の中断を確認する。store の抽出・既知化・投入・日時更新・エラー消去は embedded Postgres 17 で確認する
- NAS用Composeは`deploy/nas/tver-db/compose.yaml`をYAMLパーサーで読み、`services.postgres`、環境変数、ポート、保存先、healthcheckを確認する。Dockerが使える環境では`docker compose --env-file deploy/nas/tver-db/.env.example -f deploy/nas/tver-db/compose.yaml config`でも展開結果を確認する
- 本番の確認手順は[[docs/deploy|tver 本番配置手順]]に従い、NFS上の`/mnt/nas-tver/tver`をUID `65532`で読み書き・rename・削除できること、DBがhealthyであること、webの`/healthz`、実動画の保存・再生・シークを確認する
- `env GOPATH=/private/tmp/tver-gopath GOCACHE=/private/tmp/tver-go-cache GOMODCACHE=/private/tmp/tver-go-modcache GOPROXY=off go vet ./...` で静的解析する
- `DATABASE_URL`、`VIDEO_DIR`、`WEB_ADDR=127.0.0.1:18080` を設定して `go run ./cmd/web` で web を起動できる。worker は同じ `DATABASE_URL` と `VIDEO_DIR` を設定して `go run ./cmd/worker` で起動する。worker の実行は TVer への実アクセスを伴うため手動確認は少数回に留める
+1
View File
@@ -0,0 +1 @@
POSTGRES_PASSWORD=
+36
View File
@@ -0,0 +1,36 @@
# tver 用 PostgreSQL スタック(Synology ds923p / 192.168.10.201)
#
# 配置先: ds923p の Container Manager「プロジェクト」
# /volume1/docker/tver-db/ に本ファイルを compose.yaml として配置する。
# パスワードは同じディレクトリの .env(POSTGRES_PASSWORD)から注入し、
# このファイルには実値を書かない。
#
# 注意(初回起動チェックポイント):
# 起動前に /volume1/docker/tver-db/pgdata を作成する。
# 初回起動後は Container Manager のヘルス状態とログを確認し、
# "database system is ready to accept connections" が出てからアプリを起動する。
# bind mount の所有権・権限で初期化に失敗した場合は、原因を確認してから
# 名前付きボリュームへの切り替えを検討する。
services:
postgres:
# Debian ベースの PostgreSQL 17。initdb の UTF-8 ロケールを利用する。
image: postgres:17
container_name: tver-postgres
restart: always
environment:
POSTGRES_USER: tver
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
POSTGRES_DB: tver
# 初回の initdb でのみ有効。既存の pgdata には後から反映されない。
POSTGRES_INITDB_ARGS: "--encoding=UTF8 --lc-collate=en_US.UTF-8 --lc-ctype=en_US.UTF-8"
ports:
# [要確認] Container Manager で 15434 が未使用であることを起動前に確認する。
# DSM ファイアウォールでは dockage(192.168.10.155)だけを許可する。
- "15434:5432"
volumes:
- /volume1/docker/tver-db/pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U tver -d tver"]
interval: 10s
retries: 5
+204
View File
@@ -0,0 +1,204 @@
---
title: tver 本番配置手順
tags:
- homelab
- tver
- deployment
---
# tver 本番配置手順
> [!info] 対象
> Synology NAS `ds923p`(`192.168.10.201`)に PostgreSQL 17 と動画共有を用意し、dockage(`192.168.10.155`)の `/opt/stacks/tver` で web・worker を起動する。
> [!danger] 秘匿値を記録しない
> PostgreSQL のパスワードや完成した `DATABASE_URL` は、この文書や Git 管理下のファイルに書かない。NAS と dockage の `.env` にだけ保存し、権限を `600` にする。
## 事前に確認する値
| 項目 | 値 |
|---|---|
| NAS | `ds923p` / `192.168.10.201` |
| dockage | `192.168.10.155` |
| NAS のNFS共有 | `/volume1/video` |
| dockage のNFSマウント | `/mnt/nas-tver` |
| tverの動画保存先 | NAS: `/volume1/video/tver`、dockage: `/mnt/nas-tver/tver` |
| PostgreSQL 公開ポート | `15434` |
| PostgreSQL ユーザー / DB | `tver` / `tver` |
| アプリ配置先 | `/opt/stacks/tver` |
> [!warning] 起動前の未確認事項
> - [要確認] Container Manager と DSM で、TCP `15434` が他のコンテナやサービスに使われていないこと。
## 1. NASを準備する
### 1.1 NFSサービスを有効にする
1. DSMの「コントロール パネル」→「ファイル サービス」→「NFS」でNFSサービスを有効にする。
2. 共有フォルダ `video` が `/volume1/video` にあることを確認する。
3. `video` の「編集」→「NFS 権限」で次を追加する。
| 設定 | 値 |
|---|---|
| ホスト名またはIP | `192.168.10.155` |
| 権限 | 読み書き |
| Squash | すべてのユーザーをadminに割り当てる |
| セキュリティ | `sys` |
| 非同期を有効にする | オン |
> [!success] adminへの割り当てを確認済み
> DSMの`admin`アカウントが無効な状態でも、上記設定でUID `65532`からフォルダ作成・書き込み・読み込み・rename・削除に成功した。NAS上の所有者はUID `1024`・GID `100`だった。[実機] 2026-10-04 確認
### 1.2 PostgreSQLのファイルを用意する
1. NAS上に次のディレクトリを事前作成する。
```text
/volume1/docker/tver-db/
/volume1/docker/tver-db/pgdata/
```
2. [[../deploy/nas/tver-db/compose.yaml|NAS用compose.yaml]] と `.env.example` を `/volume1/docker/tver-db/` に配置する。
3. `.env.example`を`.env`へコピーし、`POSTGRES_PASSWORD`に十分長いランダムな値を設定する。値には、URLへの埋め込みで追加のエスケープが不要な16進文字列を使える。
```bash
cd /volume1/docker/tver-db
umask 077
cp .env.example .env
# openssl rand -hex 64 で値を生成し、.env の POSTGRES_PASSWORD に設定する。
chmod 600 .env
```
> [!important] DBとアプリで同じパスワードを使う
> ここで設定した値を、後述するdockage側の`DATABASE_URL`にも使う。値そのものは文書やGitへ残さない。
### 1.3 Container ManagerでPostgreSQLを起動する
1. Container Managerの「プロジェクト」で、`/volume1/docker/tver-db/compose.yaml`を使う`tver-db`プロジェクトを作成する。
2. 起動前に、他のプロジェクトとポート一覧を確認し、`15434`が空いていることを確認する。[要確認]
3. プロジェクトをビルド・起動する。
4. `tver-postgres`が`healthy`になることを確認する。
5. コンテナログに`database system is ready to accept connections`があることを確認する。
初期化に失敗した場合は、先に`pgdata`の所有権・権限とログを確認する。空のDBを作り直す場合を除き、既存の`pgdata`を削除しない。
### 1.4 DSMファイアウォールを設定する
TCP `15434`について、送信元`192.168.10.155`だけを許可するルールを追加する。他の送信元を許可する広いルールより前に配置し、LAN内の別ホストからDBへ接続できない構成にする。
## 2. dockageを準備する
### 2.1 NFSクライアントとマウント先を用意する
```bash
sudo apt update
sudo apt install -y nfs-common
sudo mkdir -p /mnt/nas-tver
```
`/etc/fstab`へ次の1行を追加する。`_netdev`でネットワーク後に扱い、`nofail`でNAS停止時もdockageの起動を妨げない。
```fstab
192.168.10.201:/volume1/video /mnt/nas-tver nfs defaults,_netdev,nofail 0 0
```
設定を反映し、想定したNFS共有がマウントされたことを確認する。
```bash
sudo mount -a
findmnt --target /mnt/nas-tver
```
実機ではNFSv3でマウントできた。NFS権限を追加した直後の1回目は`access denied`となり、直後の2回目で成功した。NFS権限の反映待ちと考えられるため、設定内容が正しい場合は少し待って`sudo mount -a`を再実行する。[実機] 2026-10-04 確認
### 2.2 workerのUIDで書き込みを確認する
既存の`anime`・`drama`・`misc`・`personal`・`variety`とアプリのファイルを分け、admin相当の書き込み範囲を限定するため、tver専用サブフォルダを使う。Dockerグループの`kazu634`で、workerコンテナと同じUID・GID `65532:65532`の確認用コンテナを実行し、フォルダ作成、書き込み、読み取り、rename、削除を確認する。`sudo`は不要である。
```bash
docker run --rm --user 65532:65532 -v /mnt/nas-tver/tver:/videos busybox:stable sh -c 'mkdir /videos/.tver-write-test && echo ok > /videos/.tver-write-test/f && cat /videos/.tver-write-test/f && mv /videos/.tver-write-test/f /videos/.tver-write-test/g && ls -ln /videos/.tver-write-test && rm -r /videos/.tver-write-test && echo cleanup-ok'
```
期待する結果は、内容の`ok`、`ls -ln`で表示される`g`の所有者`1024 100`、最後の`cleanup-ok`である。確認後は確認用イメージを削除する。
```bash
docker rmi busybox:stable
```
`/mnt/nas-tver/tver`は作成済みで、上記のDockerコンテナによる操作は実機確認済みである。[実機] 2026-10-04 確認。別環境へ作り直す場合も、書き込み確認が成功するまでworkerを起動しない。
### 2.3 リポジトリと環境変数を用意する
公開リポジトリを標準のスタックディレクトリへcloneする。
```bash
cd /opt/stacks
git clone https://gitea.kazu634.com/kazu634/tver.git tver
cd /opt/stacks/tver
```
`.env.example`をGit管理外の`.env`へコピーし、実環境の値を設定する。
```bash
umask 077
cp .env.example .env
chmod 600 .env
```
`.env`には次の形式で設定する。`<PostgreSQLのパスワード>`はNAS側の`.env`と同じ実値へ置き換える。
```dotenv
DATABASE_URL=postgres://tver:<PostgreSQLのパスワード>@192.168.10.201:15434/tver?sslmode=disable
VIDEO_HOST_DIR=/mnt/nas-tver/tver
VIDEO_DIR=/videos
WORKER_CONCURRENCY=1
```
> [!warning] パスワードの文字種
> 上のURLへ埋め込む値に予約文字がある場合はURLエンコードが必要になる。NAS準備時に16進文字列で生成すれば、この追加処理を避けられる。
### 2.4 Dockgeで起動する
1. Dockgeでスタックディレクトリ `/opt/stacks/tver` の`compose.yaml`を`tver`スタックとして開く。
2. webとworkerの両方が`build`対象であり、`.env`が読み込まれることを確認する。
3. 「Deploy」でビルドと起動を行う。
4. Dockge上でweb・workerがともにrunningになり、再起動を繰り返していないことを確認する。
コマンドでも状態とログを確認できる。
```bash
cd /opt/stacks/tver
docker compose ps
docker compose logs --tail=100 web worker
```
## 3. 動作を確認する
1. ヘルスチェックが`200`と`ok`を返すことを確認する。
```bash
curl --fail --show-error http://192.168.10.155:8080/healthz
```
2. ブラウザで`http://192.168.10.155:8080/`を開き、新着一覧が表示されることを確認する。
3. 番組またはエピソードを1件登録し、`/queue`で待ち行列、進捗、完了を確認する。
4. `/library`から動画を再生し、シークできることを確認する。
5. NASの`/volume1/video/tver`に規則どおりのMP4が作成されたことを確認する。
6. `tver-postgres`のログとweb・workerのログに、接続失敗やマイグレーション失敗がないことを確認する。
## 4. 更新する
```bash
cd /opt/stacks/tver
git status --short
git pull --ff-only
```
`git status --short`に追跡対象ファイルの変更がある場合は、内容を確認してから更新する。pull後、Dockgeで`tver`スタックを再ビルドして再配置し、[[#3. 動作を確認する]]を繰り返す。
yt-dlpを更新するときは`Dockerfile.worker`の`YT_DLP_VERSION`の既定値を変更してリポジトリへ反映し、workerイメージをキャッシュなしで再ビルドする。更新後はworkerログと少数の実動画で抽出・保存を確認する。
## 5. 稼働後に残る作業
> [!todo] PostgreSQLバックアップ
> tver専用PostgreSQL 17コンテナ内の`pg_dump`で取得し、gzip圧縮してNASの`/volume1/backups/tver/`へ保存する日次処理を用意する。保持日数は既定14日とし、稼働確認後に別作業として実装する。