運用Tips
日々の運用で効くノウハウを集めました。
バックアップ
SQLite ファイル (pipeline.db) をコピーすればフルバックアップになります。WAL モードなので稼働中でも読み出しロックは起きにくいです。確実を期すなら VACUUM INTO を使います。
sqlite3 pipeline.db "VACUUM INTO 'pipeline-backup-$(date +%Y%m%d).db'"ワーカー追加 / 削除
worker は pull 型なので、追加はデーモン起動だけで OK です (制御プレーン側の設定変更は不要)。削除はデーモン停止だけで、一定時間後に lost → DB から削除されます。
ホストアフィニティと担当割当
workload の host_affinity に対象ホスト名を入れると、そのホストの worker だけが claim できます。より細かい「どの worker がどの workload を取るか」は、Flow 図の Worker×Workload マトリクスや各 worker の filter (POST /workers/{id}/filter) で制御できます。
失敗のリトライ
例外で失敗したタスクは max_attempts 回まで自動で retry されます。上限超過後はキューに残りますが claim されません (dead-letter)。POST /workloads/{slug}/queue/reset-failed または RunsDrawer の再投入で復旧できます。
同時実行の抑制 (VRAM保護)
VRAM を大きく確保する plugin を同一 GPU で多重起動すると OOM (CUBLAS_ALLOC_FAILED 等) で setup() が死ぬことがあります。max_concurrent_per_host (ホスト単位) と max_concurrent_total (fleet 全体) で上限をかけて防ぎます。単一 writer 保証には max_concurrent_total: 1 が有効です。
監視
- Flow 図のタンク液面 / 赤ボックスで滞留と GPU 障害を監視します。
- Throughput で各ノードのレート推移を追います。
/api/v1/dashboard/overviewのrecent_failuresを定期 ping します。- Storage SDK の
reg.health()で MinIO/DB の死活をチェックできます。 - nvidia-smi メトリクスは worker の heartbeat から自動収集されます。
アップデート
cd /opt/pipeline
git pull
pip install -e .
sudo systemctl restart pipeline-oss-control # 制御プレーン
# 各worker:
sudo systemctl restart 'pipeline-worker-*'プラグイン / コードの各ホストへの配信は Web UI の Deploy 画面から行えます。配信後は md5 突合で全ホストの一致を確認してから worker を再起動してください。Web UI を更新した場合は cd web && npm install && npm run build も実行します。
トラブルシューティング
| 症状 | まず疑うところ |
|---|---|
| ワーカーが workload を claim しない | workload が enabled か / host_affinity がそのホスト名に一致するか / worker の filter が別 slug に絞られていないか (Flow のマトリクスで確認) / max_concurrent_per_host・max_concurrent_total の上限に達していないか / executor_type が shell/python_module か (他は claim されません)。 |
タスクが pending のまま増える | その workload を担当する worker がいない (Workers 画面) / 優先度の高い別 workload に処理が食われている (priority を見直す)。 |
| プラグインが読み込めない (PluginConfigError) | source_path と module 名が正しいか / 依存が worker の venv に入っているか (requirements は自動 install されません)。 |
setup() で落ちる | init_kwargs の不足 / モデル・DB 接続の失敗 / GPU OOM (同居数を max_concurrent_per_host で絞る)。 |
| self_loop が止まった | tick の自己 enqueue 前に worker が死んだ。watchdog が 300 秒アイドルで自動復活します。多重起動していないか (max_concurrent_total: 1) も確認。 |
| コード変更が反映されない | worker の再起動 + __pycache__/*.pyc 削除を忘れていないか。process() はプロセス内キャッシュです。 |
| 失敗が消えず溜まる | max_attempts 超過の dead-letter。原因を直し reset-failed で再投入。 |
FAQ
- Q. 依存を入れたのに ModuleNotFoundError。 A. 制御プレーンではなく、そのプラグインを動かすワーカーの venv に入れてください。deploy の
setup_commandにpip installを書くのが確実です。 - Q. 同じ pk が2回処理されたようだ。 A. 仕様です。lease 失効やリトライで再実行され得ます。
process()は冪等に書いてください。 - Q. GPU を使う workload だと明示したい。 A.
requires_gpu: trueを立て、host_affinityで GPU ホストに寄せます (ランタイム強制ではなく配置設計の目安)。 - Q. PostgreSQL は使える? A. 現状未実装です。SQLite (既定) か MariaDB を使ってください。
- Q. 認証は? A. 初回起動時の
PIPELINE_ADMIN_PASSWORDで管理者ログインを有効化できます。内部エンドポイント (/api/v1/_internal/*) は nginx 等で遮断する前提です。