メインコンテンツまでスキップ

システムの起動と停止

概要​

PlantPulse は Docker Compose スタックとして動作します。起動 / 停止 / 再起動は /opt/kopens/plantpulse-platform-docker/bin/ の 共通動詞 一箇所で管理しており、コンテナ間の依存順序は compose の depends_on が自動的に適用するため、オペレーターが一つ一つ順序を気にする必要はありません。

終了コード 0 の意味が異なります

up.sh と restart.sh の 0 は «コマンドが成功した» という意味ではなく «今すぐ使用できる» という意味です。2026-08-14 の資格情報ローテーション時に «起動した» ことだけを見て次のステップに進み、まだ起動していないブローカーで停止した事故があったため、この2つの動詞は準備が整うまで待つように変更されました。

status.sh は異なります — 0 = 正常 / 2 = 異常 です。

推奨運用コマンド (概要)​

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

./up.sh                # 기동 (멱등) — 준비될 때까지 대기. 0 = 준비 완료
./down.sh              # 안전 종료 (의존 순서의 역순, 상태 보존)
./restart.sh           # graceful drain → 정지 → 기동 → 준비 대기
./status.sh            # 서비스 / health / 볼륨 요약. 0 = 정상 / 2 = 비정상
./ops-check.sh         # 헬스 + 최근 critical log
./logs.sh [서비스]     # 로그 보기 — 1회 출력, -f 로 따라가기 (인자 없으면 전체)
./stack-verify-boot.sh # 스택 전체 준비 판정
./doctor.sh            # 진단 tarball (시스템 변경 없음)

すべての動詞が --help をサポートしています。旧名称 (stack-run.sh · stack-stop.sh · stack-bash.sh · stack-update.sh · stack-remove.sh) もそのまま動作します。

環境変数デフォルト値意味
PP_READY_TIMEOUT900準備待機の上限(秒)
PP_READY_INTERVAL15確認間隔(秒)
PP_WAIT=0—待機しない。この場合の 0 は準備完了を意味しません

起動順序 (自動)​

コンテナ間​

compose の depends_on が service_healthy 条件で順序を守ります — «プロセスが起動した» ではなく «使用できる» を待ちます。この順序は任意ではなく、アプリケーションオーケストレーターの起動順序をそのまま移したものです。

最後の4つ (warehouse · opcua · aasx · ha) は相互に順序がありません。

データレイクコンテナ内​

インフラコンポーネントは plantpulse-datalake の単一コンテナ内で再び順番に起動します。

順序領域主要コンポーネント代表ポート
1ストレージAster TSDB, PostgreSQL, Valkey, RustFS9042 / 5432 / 6379 / 9000
2分析Spark, Hive, Kyuubi, Gravitino7077 / 9083 / 10000 / 19001
3時系列TSE Engine, UI7800 / 3000
4メッセージングKafka, MQTT9092 / 1883
5ワークフローTemporal, Kestra7233 / 8233 / 8380
6処理CEP, Data Gateway, SQL, Monitor7400 / 5500 / 4000 / 4950
所要時間

プロセス起動自体は3〜5分(JVM ウォームアップ)ですが、クリーンインストールでは Aster TSDB スキーママイグレーションと安定化のため、全コンポーネントが安定するまで15〜18分かかります。

実測 (2026-08-31、32 vCPU / 128GiB): データレイク217秒、Web サーバー316秒。データが既にある再起動ははるかに速いです。

停止順序​

cd /opt/kopens/plantpulse-platform-docker/bin
./down.sh

順序を手で守る必要はありません。 compose が依存順序の逆順で停止するため、データを書き込む側(アプリ)が先に停止し、データレイクが最後に停止します。各コンテナには十分な停止猶予 (stop_grace_period) が設定されており — データレイクは180秒 — Aster TSDB が Memtable をフラッシュする時間を確保します。

ボリューム (pp-data · pp-temp · pp-backup · pp-security · pp-proxy-certs) は停止・削除とは無関係に常に保持されます。

docker kill やホストの強制終了を使わないでください

Aster TSDB のフラッシュされていない Memtable データが失われる可能性があります。必ず ./down.sh を使用してください。既にコンテナが応答しない場合は 緊急手順 に従ってください。

再起動​

全体再起動​

cd /opt/kopens/plantpulse-platform-docker/bin
./restart.sh
  1. (稼働中の場合) データレイクに graceful drain を要求
  2. スタック全体を依存順序の逆順で停止
  3. depends_on の順序で再起動
  4. 準備完了まで待機 — 終了コードが 0 であれば使用可能な状態

bin/env.sh の変更、ロケール・タイムゾーンの変更、一時的な問題の解消、定期的な再起動に使用します。

アプリ1つだけ再起動​

アプリ6つはそれぞれ独立したコンテナで動作しているため、そのコンテナだけを再起動すれば、他のアプリとインフラはそのまま稼働し続けます。これがコンテナを分割した理由の一つです。

cd /opt/kopens/plantpulse-platform-docker
docker compose -f compose/docker-compose.yml restart plantpulse-server-web
docker compose restart は依存順序を守りません

複数のアプリをまとめて復旧させる必要がある場合は、./restart.sh でスタック全体を再起動する方が安全です。

インフラコンポーネントのみ再起動​

./shell.sh                                                              # 데이터레이크 진입
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd restart storage
exit

pd restart <서비스> が受け付ける名前は services/order.txt にある8つだけです — storage · analytics · messaging · timeseries · cep · workflow · data-gateway · admin-api。それ以外の名前は unknown service で終了します。詳細は起動ガイドを参照してください。

状態確認​

一行サマリー​

./status.sh            # 0 = 정상 / 2 = 비정상

status.sh が異常と見なすのは5つです。

判定内容
サービス一覧を読み取れないcompose 解析失敗、または docker へのアクセス不可
compose が宣言したサービスにコンテナがない起動していない
コンテナが running ではない9つ全てが常時動作します — 除外対象はありません
常時稼働コンテナの health が unhealthystarting / none は判定保留
ヘルス API が OK ではないデータレイク内で probe

ボリュームと conf は報告のみで終了コードには含めません — インストール構成によっては一部が存在しないのが正常なためです。

9つを同じ基準で見ます

plantpulse-certs は証明書を一度焼き込んで稼働し続けながら期限を監視します。9つを同じ基準 (healthy) で見ればよいです。

ヘルスチェックはイメージが保持しています。 compose に probe ブロックがないのは意図的であり、pp.healthcheck: image ラベルがそれを明示しています。プローブパスが他のリポジトリのものを compose に記述すると、そのファイルが移された瞬間に顧客先で壊れます。

コンテナ確認​

docker ps                       # 아홉 개가 모두 (healthy)
docker stats --no-stream        # 컨테이너별 CPU / 메모리

ヘルスチェック API​

# 호스트 / 외부에서 — 4950 이 publish 되어 있습니다
curl -kfsS https://<server-ip>:4950/api/health | jq

# 컨테이너 안에서 — 어떤 구성에서도 동작합니다
docker exec plantpulse-datalake curl -kfsS https://127.0.0.1:4950/api/health | jq

"status" の値は OK · WARN · FAIL の3つだけで、OK/WARN が正常範囲です。

4949 でも同じ API が応答します

コンソールとヘルス API は両方のポートでサービスされます — 4950(HTTPS)と 4949(平文 HTTP)。同じコンソール・同じ API で、スキームのみ異なります。4949 はもう 4950 にリダイレクトしません。

4949 は平文です — ログインパスワードとセッションクッキーがそのまま流れます。信頼できないネットワークでは 4950 を使用してください。4949 は自己署名証明書の警告が実際にオペレーターを立ち止まらせるボックスのための選択肢です。

ログ確認​

./logs.sh                              # 여덟 컨테이너를 시간순으로 한 화면에
./logs.sh plantpulse-server-web -n 200 # 특정 컨테이너
./logs.sh cassandra                    # 데이터레이크 안 컴포넌트 로그 파일
./logs.sh --list                       # 볼 수 있는 대상 전체
./logs.sh -f plantpulse-proxy          # 계속 따라가기 (Ctrl-C 로 종료)

デフォルトは最後の N 行(デフォルト200)を表示して終了です。追従するには -f を付けてください。

自動起動設定​

特別な設定は不要です。 コンテナは compose に再起動ポリシーが宣言されているため、ホストを再起動しても Docker デーモンが起動すれば一緒に立ち上がります。plantpulse-certs は restart: unless-stopped です — 人が意図的に停止した場合は、デーモンを再起動しても停止したままになります。再起動しても証明書を新たに焼き込むことはありません。

確認すべきは Docker デーモンの自動起動だけです。

systemctl is-enabled docker     # enabled 여야 합니다
sudo systemctl enable docker    # 아니라면
再起動直後にプロキシが一時的に赤く表示されることがあります

ホスト再起動は depends_on の順序が適用されない唯一の経路です — 全てが一斉に起動するため、Web サーバーが起動するまで(実測最大316秒)、プロキシのヘルスチェックが一時的に失敗することがあります。再試行予算は360秒に設定されており、docker は unhealthy を理由にコンテナを再起動しないため、自己回復する一時的な状態です。

緊急手順​

Web コンソールが応答しない​

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

# 1. 어느 컨테이너가 문제인가
./status.sh

# 2. 프록시와 웹 서버 로그
./logs.sh plantpulse-proxy -n 100
./logs.sh plantpulse-server-web -n 200

# 3. 웹 서버만 재시작 (인프라는 유지)
cd /opt/kopens/plantpulse-platform-docker
docker compose -f compose/docker-compose.yml restart plantpulse-server-web

# 4. 회복되지 않으면 진단 번들
bin/doctor.sh
プロキシが緑なのに画面が 502 の場合

プロキシのヘルスチェックは自身 + アップストリーム到達までしか見ません(バックエンドの健全性は Web サーバー自身のヘルスチェックが判定します)。プロキシが緑なのに画面が表示されない場合は plantpulse-server-web 側を確認してください。

OOM (Out Of Memory) 発生​

# 1. 어느 컨테이너가 OOM 인가
docker inspect plantpulse-server-web --format '{{.State.OOMKilled}} {{.State.ExitCode}} {{.RestartCount}}'

# 2. 호스트 커널 로그
dmesg | grep -i "out of memory\|oom"

# 3. 컨테이너별 사용량
docker stats --no-stream

コンテナごとに制限値が個別に設定されています — データレイクは DOCKER_DATALAKE_MEMORY(デフォルト 96G)、アプリは DOCKER_SERVER_MEMORY · DOCKER_BATCH_MEMORY などです(環境変数)。値を調整した後、./restart.sh で適用します。

1つのアプリの OOM が全体を落としません

アプリごとに mem_limit を個別に持つことがコンテナ分離の第一の目的です。1つのアプリが制限に達しても、インフラと他のアプリは稼働し続けます。

DB 接続失敗​

データベースはすべて plantpulse-datalake 内にあります。

cd /opt/kopens/plantpulse-platform-docker/bin
./shell.sh                                                            # 데이터레이크 진입

/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node psql       # PostgreSQL
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node cql        # Cassandra
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node status     # Cassandra 링 상태

インフラだけを復旧させるにはコンテナ内で pd restart storage を、それでもダメな場合はホストで ./restart.sh を使用します。

データ破損の疑いがある場合​

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

./down.sh                                  # 즉시 정지 (추가 손상 방지)
ls -lh /data1/pp-backup/docker-volume/     # 최신 백업 확인
./doctor.sh                                # 진단 번들 (데이터를 임의로 수정하지 마세요)

生成された tarball を webmaster@kopens.com まで送付してください。

運用チェックリスト​

日常点検​

点検項目コマンド / 確認方法正常基準
全体サービス状態./status.sh終了コード 0
運用ヘルス./ops-check.shcritical ログなし
ヘルス APIcurl -kfsS https://<server-ip>:4950/api/healthstatus が OK または WARN
コンテナdocker ps9つ全てが (healthy)
ディスク使用量df -h /data1使用率80%未満
コンテナリソースdocker stats --no-stream制限値に対して余裕あり
Aster TSDB 状態コンテナ内で pd node status全ノードが UN (Up/Normal)

週次点検​

点検項目コマンド / 確認方法正常基準
Aster TSDB Compactionコンテナ内で pd node compactionstatsPending タスクが過多でない
Aster TSDB テーブルコンテナ内で pd node table-stats異常な増加なし
Kafka トピック / lagコンテナ内で pd node topic遅延メッセージ数が正常範囲
バックアップ確認ls -lh /data1/pp-backup/docker-volume/正常なバックアップが存在
Docker 使用量docker system df未使用イメージが累積していない
ログ容量du -sh /opt/kopens/plantpulse-platform-docker/logs異常な増加なし
セキュリティアップデートOS パッケージアップデート確認既知の脆弱性なし