サービス運用

AI スタックは**docker compose ひとつ**です。運用コマンドは全部インストール本体の bin/ にあり、 compose を代わりに呼び出してくれます。

cd /opt/kopens/plantpulse-ai-docker/bin

よく使うもの

やりたいこと	コマンド	備考
立ち上げる	./up.sh	終了コード 0 なら «準備完了» です
落とす	./down.sh
再起動する	./restart.sh	0 なら再起動後に準備完了
今の状態を見る	./status.sh	compose スタック状態サマリー
詳しく診断する	./health.sh	サービス別詳細レポート
ログを追う	./logs.sh
イメージを新しく取得して上げる	./update.sh	取得後に再起動まで

終了コードを信じてください

up.sh · restart.sh はコンテナが立ち上がったことではなく使えるようになったことを 0 で 知らせます。スクリプトで自動化するとき、別途待機ループを入れる必要はありません。

何が間違っているのか見極めるとき

./doctor.sh

🔴 doctor.sh は何も変えません。 読んで判断するだけです。そのため障害中でも 安心して先に実行できます — 直すのは人が決めることです。

env ファイルの行のうち、起動を妨げるものは «bad» として、そのままにしても何も変わらない古い名前・重複行(起動前判定の [warn] — alias · oldname · media-same)は**«old or redundant lines»** として別に表示します。後者は障害原因 ではありません。整理するコマンドは bin/lint-env.sh が示してくれます → 環境変数設定

コンテナを一つだけ扱うとき

スタック全体を揺らす必要がなければ、スクリプトにサービス名を渡します。

cd /opt/kopens/plantpulse-ai-docker/bin
./status.sh                            # 무엇이 떠 있나
./restart.sh plantpulse-rag-api        # 0 이면 재시작 후 준비됨
./logs.sh plantpulse-lightrag

docker compose を素手で呼ばないでください

compose ファイルは compose/ の下に、設定は /etc/kopens/plantpulse-ai.env にあります。インストールディレクトリで docker compose … をそのまま打つとファイルが見つからないか、見つかっても別の設定で動きます — up の場合は配布した イメージが巻き戻ることがあります。スクリプトは compose ファイルと設定ファイルを明示して呼び出します。

コンテナ名とそれぞれの役割は インストール概要 の表にあります。

コンテナの中に入る必要があれば:

bin/shell.sh plantpulse-rag-api

ログ

./logs.sh                         # 스택 전체를 따라 본다
./logs.sh plantpulse-llm          # 서비스 하나

コンテナログはDocker がローテーションします(compose に設定済み)。ホストで別途削除すべき ファイルは溜まりません。

コンテナは非rootで動きます

2026.10 から compose の全サービスが実行ユーザー(user:)を明示し、root で動くのは GPU 指標を 読む plantpulse-dcgm ひとつだけです(GPU プロファイリングフィールドを読むには root と SYS_ADMIN が必要です)。

何	実行ユーザー (uid:gid)
自社イメージ — 入口プロキシ・コパイロット・管理コンソール・RAG・時系列インサイト・文書理解・ビジョン・デジタルスレッドなど	10001:0
vLLM(plantpulse-llm · -emb · -rerank、映像・音声を有効化したインストールの plantpulse-asr) · plantpulse-asr-audio	10001:0
Neo4j 2つ	7474:7474
Qdrant	1000:1000
Phoenix	65532:65532
Docling	1001:0
plantpulse-dcgm	root (例外)

入口プロキシ(plantpulse-proxy)も非rootになったことで、コンテナの内側ポートが 8080 · 9443 · 8443 に 変わりました。ホストから見える 80 · 443 · 5960 はそのままです → サービスポートマップ

旧インストールで root 所有として作られた書き込みボリュームは、非rootプロセスが書き込めません。Docker は既存ボリュームの 所有者を変更してくれず、書き込み失敗は大抵静かに起こるか(ログファイルの代わりにコンソールにだけ残る形)即死します(Qdrant は root 所有ストレージで即座に落ちます)。そのため up.sh · restart.sh · update.sh が通る起動スクリプトが compose を上げる前に bin/volumes-nonroot.sh を呼び出します。

サービス	合わせる箇所	合わせる所有者
plantpulse-copilot-web · plantpulse-timeseries-insight-api	アプリログ	10001:0
plantpulse-timeseries-insight-server	アプリログ・インストール別ファインチューニング重み	10001:0
plantpulse-lightrag	索引ストレージ・入力原本	10001:0
vLLM セット(録音 plantpulse-asr はONのインストールのみ)	コンパイルキャッシュ	10001:0
plantpulse-asr-audio (ONのインストールのみ)	音声ライブラリボリューム(pi-asr-audio)	10001:0
plantpulse-neo4j · plantpulse-digital-thread-neo4j	データ	7474:7474
plantpulse-qdrant	ベクトルストレージ	1000:1000
plantpulse-phoenix	データ	65532:65532
plantpulse-proxy	証明書(pp-proxy-certs)	10001:0
plantpulse-registry (プロファイルをONにしたときのみ)	イメージストレージ	10001:0

そのサービスのユーザーでないファイルが一つでもあるときだけ変更するため、最初の一回だけ処理して、その後は確認のみ して通過します。合わせられなければ起動を止めます(所有権が間違ったまま上がると書き込みが静かに失敗するため)。

docker compose up を素手で呼ぶとこの段階をスキップします

2026.09 以下で導入したホストは、初回起動を必ず bin/up.sh(または update.sh · restart.sh)で行ってください。

デフォルトでは立ち上がらないもの — compose プロファイル

プロファイル	コンテナ	用途
registry	plantpulse-registry · plantpulse-registry-ui	閉域網ハブノードのローカルイメージストレージ
media	plantpulse-asr · plantpulse-asr-audio	映像・音声録音(音声での問い合わせを含む)。ホスト env の PI_MEDIA_ENABLED=true 一行でONにします — 運用スクリプト(up.sh · restart.sh · status.sh · logs.sh …)がその値を見てプロファイルを付けます → 映像・音声収集

media はプロファイル名を直接渡さず PI_MEDIA_ENABLED でONにしてください — そのスイッチが rag-api・文書理解の値と録音モデル 取得まで一緒に揃えます。ホスト env に COMPOSE_PROFILES を書くと、起動前判定が unknown で起動を止めます。

plantpulse-asr-audio は音声ライブラリをボリュームに移して終わる一回限りのサービスです。status.sh で «Exited (0)» なら正常で、正常として扱われます。0 以外のコードで終わった場合は plantpulse-asr も立ち上がりません。

バックアップとパスワード

やりたいこと	コマンド	ドキュメント
バックアップを取る	./backup.sh (何を取得するかは ./backup.sh --list — ログ・キャッシュと録音の音声ライブラリボリュームは除きます)	データベース管理
パスワード・キーを変更する	./passwd.sh	パスワード・APIキー変更
インストールを撤去する	./remove.sh	元に戻せません

データベースはプラットフォームのものを使います

PostgreSQL · Aster TSDB · Redis(Valkey) · RustFS はAI スタックが立ち上げません。 プラットフォームのインストール分を共用で使います(PP_DATALAKE_ADMIN_URL のホスト)。この4つが落ちると AI も一緒に止まるため、 障害時は サービスポートマップ でどちら側の問題かをまず切り分けてください。

2026.10 からそのアカウント・パスワードは、コンテナが起動するときにプラットフォームから受け取ります。 プラットフォームに届かなければ 受け取る側のコンテナが FATAL で止まり、プラットフォームでパスワードを変えた場合は該当コンテナを再起動するだけで 済みます → 環境変数設定

関連ドキュメント

• AI 管理コンソール — 画面で見る状態
• ログおよびモニタリング
• サービスポートマップ