設定を変更する方法

何を変更するかによって、修正するファイルと反映方法が異なります。 まず、以下の表でご自身のケースを探してください。

コンポーネントの設定ファイルを直接修正すると、次回起動時に消えます

データレイクは起動するたびに設定を再レンダリングします。 plantpulse-datalake-cli/config/templates/ のテンプレートを読み込み、${PP_*} を埋めた後、 各コンポーネントの設定場所(plantpulse-storage/db/cassandra/conf/cassandra.yaml など)へ 上書きします。 どのテンプレートがどこへ行くかは config/render.map の1枚に記載されています。

そのため、cassandra.yaml · postgresql.conf · kafka.properties を開いて修正しても、 次の pd start で元に戻ります。 修正すべき場所はテンプレートです。

# ❌ 이렇게 고치면 다음 기동에 사라진다
vi /opt/kopens/plantpulse-platform/plantpulse-storage/db/cassandra/conf/cassandra.yaml

# ✅ 템플릿을 고친다 — 호스트의 /etc/kopens/conf 가 템플릿 자리로 마운트돼 있다
vi /etc/kopens/conf/cassandra.yaml.template
docker exec plantpulse-datalake pd config render     # 렌더해 보고
docker exec plantpulse-datalake pd config diff       # 「지금 도는 설정」과의 차이 (0 = 같다)
docker exec plantpulse-datalake pd restart storage   # 해당 서비스만 재시작

pd config diff が 0 以外の場合、ランタイムファイルがテンプレートと異なることを意味します — 誰かが 直接修正したか、レンダリングがまだ完了していないかのどちらかです。

変更したいもの	例	修正する場所	反映方法
パスワード · APIキー	PostgreSQLパスワード、CEP APIキー	bin/passwd.sh	ツールが再起動まで行います
このボックスのアドレス · 識別情報	他のボックスが接続するアドレス、Kafka広告アドレス、NAT公開IP	/etc/kopens/platform.node.env	bin/restart-datalake.sh
全ノード共通の非秘密の値	言語 · タイムゾーン、バックアップスケジュールスイッチ、コンソールログエンドポイント	/etc/kopens/plantpulse-platform.env	bin/restart-datalake.sh
コンテナリソース	データレイクのメモリ上限	/etc/kopens/platform.node.env (DOCKER_DATALAKE_MEMORY)	bin/restart-datalake.sh
エンジン設定の「行」	postgresql.conf パラメータ、Kafka保存期間、Aster TSDBヒープ	/etc/kopens/conf/<파일>.template	bin/restart-datalake.sh またはコンテナ内 pd config render + pd restart <서비스>
バックアップスケジュール	夜間バックアップ時刻	コンテナ内 pd backup schedule set	即時
公開ポート	ホストに開くポート	compose/docker-compose.yml	bin/restart-datalake.sh — 注意

変更後の確認は常に同じです

cd /opt/kopens/plantpulse-platform-docker/bin
./status.sh                                       # 0 = 정상
docker exec plantpulse-datalake pd config diff    # 런타임 파일 = 렌더 결과인가 (0 = 같다)
docker exec plantpulse-datalake pd doctor         # FAIL 0

1. パスワード · APIキー

ファイルを開かないでください。passwd.sh がサーバー側アカウント変更 → サイドカー更新 → 設定再レンダリング → 再起動を1つのコマンドで実行します。

cd /opt/kopens/plantpulse-platform-docker
bin/passwd.sh --list                 # 바꿀 수 있는 키
bin/passwd.sh PP_PG_PASSWORD         # 값은 프롬프트로 (권장)

詳細はパスワード · APIキーの変更にあります。

2. このボックスのアドレスと識別情報 — ノードファイル

/etc/kopens/platform.node.env はこのボックスにのみ有効な値を記述するファイルです。他のボックスへコピーしてはいけません — 実際に、あるボックスのファイルをコピーした別のボックスが、静かに誤ったロールで再インストールされたことがあります。

変数	いつ記述するか	空にした場合
PP_MASTER_IP	他のボックス(エッジ、AI、ワーカー)がこのデータレイクに接続する必要があるとき — このホストのLANアドレス	composeネットワーク内のアドレス(10.99.0.100) — 同じボックス内でのみ通信可能
PP_KAFKA_ADVERTISED_HOST	NATの背後にある、または第2インターフェースでKafkaに接続する場合のみ	起動時にツールが自動設定します(オペレーター値 > PP_MASTER_IP > ホストデフォルトIP)。通常は空のままにします
DOCKER_PP_EXTERNAL_IP	NAT環境の公開IP。TLS証明書SANに含まれます	空のままにします — 誤ったIPを設定すると証明書が1枚も生成されません
PP_NODE_ID	ボックスが複数ある場合、このボックスの短くて一意な名前	コンテナホスト名から派生 — ボックスが2つあると互いに競合します。2台目のボックスを接続する前に設定してください

sudo vi /etc/kopens/platform.node.env
#   PP_MASTER_IP=192.168.10.20

cd /opt/kopens/plantpulse-platform-docker/bin
./restart-datalake.sh        # 데이터레이크만 재생성 + 준비 대기 + 의존 앱 판정

広告アドレスが 127.0.0.1 の場合、レンダリングが拒否されます (exit 8)

サーバーがクライアントに「ここに再接続してください」と提供するアドレス(Kafka advertised.listeners、Aster TSDB broadcast_rpc_address、Temporal broadcastAddress)がループバックの場合、そのサーバーは自身の場所では正常に動作しますが、他のコンテナはすべて自分自身に接続しようとします。 ポートチェックはすべてUPなのに、クライアントは1つも接続できない状態になります。エラーメッセージが修正すべき名前を教えてくれます — ノードファイルの PP_HOST_IP · PP_MASTER_IP · PP_KAFKA_ADVERTISED_HOST です。

3. 全ノード共通の非秘密の値 — サイドカー

サイドカー /etc/kopens/plantpulse-platform.env はシークレット専用のファイルではありません。非秘密の共通値も VAR=값 の1行で記述すると、bin/env.sh が読み取り、compose に渡します。使用可能な変数は compose/platform.env.example にコメントと共にすべて記載されています — そこから行を選んで転記します。

よく使うもの:

変数	デフォルト値	意味
PP_LANG	en	韓国語運用の場合は ko
PP_TZ	Asia/Seoul	時系列がこのタイムゾーンのepochで保存されるため、韓国運用では維持
PP_BACKUP_SCHEDULE_ENABLED	true	false の場合、バックアップタイマー5つが「skipped」として記録されるだけで終了します
PP_DATALAKE_ADMIN_LOGS_ENABLED	true	false の場合、コンソールのログ画面(エンドポイント)のみ停止します
PP_KEYSPACE · PP_DB_NAME · PP_TOPIC_PREFIX	pp	データレイクが「作成」し、アプリが「読み取る」識別子。インストール後は変更しないでください

sudo vi /etc/kopens/plantpulse-platform.env
#   PP_LANG=ko

cd /opt/kopens/plantpulse-platform-docker/bin
./restart.sh                 # 언어 · 타임존은 앱에도 닿으므로 전체 재시작

サイドカーのヘッダー2行には触れないでください

# generated: と # last rotation: はツールが管理します。残りの行は VAR=값 であれば問題ありません。古い export VAR=값 行も読み取られますが、次回更新時に新しい形式で書き換えられます。

4. コンテナメモリ

データレイクコンテナのメモリ上限は DOCKER_DATALAKE_MEMORY です。デフォルトは96Gで、これが最小値です — 64G はサポート対象外です。ホスト RAM の90%を超えないよう切り詰められるため、ホストが107G未満なら96Gを割り当てられず、そのホストは仕様未満です(システム要件)。増やすときはノードファイルに記述します。

sudo vi /etc/kopens/platform.node.env
#   DOCKER_DATALAKE_MEMORY=128g

cd /opt/kopens/plantpulse-platform-docker/bin
./restart-datalake.sh

小さすぎる値を設定すると「起動しているが応答しない」状態になります

コンテナ内のPID 1はsystemdであるため、JavaプロセスのみがcgroupでOOM-killされ、docker ps は Up を表示し続けます。キル記録はホストの dmesg にのみ残ります。2026-09-04に64G上限で実際に発生し(実測ピーク63.9G)、デフォルト値が80Gに引き上げられました。2026-10-04 にはさらに 96G に引き上げられました。2026-10-29 には 96G 上限に達し、Kafka がメモリ確保失敗(ENOMEM)で停止しました — 96G 未満に下げないでください。

dmesg -T | grep -i "memory cgroup"
docker inspect plantpulse-datalake --format '{{.State.OOMKilled}}'

5. エンジン設定の「行」 — テンプレート

postgresql.conf にパラメータを追加したり、Kafkaの保存期間を変更するなど、値ではなく行を修正する場合は、ホストのテンプレートを修正します。どのテンプレートがどのファイルになるかはテンプレート一覧にあります。

# 1. 호스트에서 템플릿 편집
sudo vi /etc/kopens/conf/postgresql.conf.template

# 2-a. 데이터레이크 전체 재시작 — 기동 때 자동 렌더
cd /opt/kopens/plantpulse-platform-docker/bin
./restart-datalake.sh

# 2-b. 또는 서비스 하나만 — 컨테이너 안에서
docker exec plantpulse-datalake pd config diff        # 무엇이 바뀔지 먼저 본다
docker exec plantpulse-datalake pd config render      # 생성물을 실제로 쓴다
docker exec plantpulse-datalake pd restart storage    # 그 서비스만 재기동

# 3. 확인
docker exec plantpulse-datalake pd config diff        # 0 = 런타임이 렌더 결과와 같다

pd config render だけを実行して再起動しない場合、「反映された」ことにはなりません。ファイルが変更されただけです。pd restart <서비스> までが1セットです。

イメージが新しいデフォルト値を載せてくる場合 — 3-wayシード

/etc/kopens/conf はホストファイルであるため、イメージが新しいデフォルト値を載せてきても自動的には変更されません。 そこで、起動ツールがデプロイごとにファイル単位でセットを比較します — 今回のイメージのデフォルト値、前回のデプロイのデフォルト値(/etc/kopens/conf.dist)、ホストファイル。

ケース	ツールが行うこと
オペレーターが触れていないファイル、デフォルト値が変更	新しいデフォルト値に置き換え
オペレーターが修正したファイル、デフォルト値も変更	オペレーターファイル維持 + [WARN] operator edit kept, but THE IMAGE DEFAULT CHANGED + デフォルト値の変更diff出力
オペレーターが修正したファイル、デフォルト値同じ	維持 (黙って)
イメージに新しいテンプレートが追加	インストール
イメージからテンプレートが削除	ホストファイルは残し、警告

restart.sh · update.sh の出力で [WARN] operator edit kept 行を確認した場合、自身の編集と新しいデフォルト値を手動でマージする必要があります。新しいデフォルト値ファイルの場所が同じ行で示されます。

自身のテンプレートがイメージのデフォルト値とどこが異なるかは、コンテナ内で確認できます。

docker exec plantpulse-datalake pd config diff --templates
#   same     — 같다
#   differs  — 호스트 사본이 다르다 (렌더는 이쪽을 쓴다)
#   local    — 운영자가 추가한 파일
#   missing  — 이미지엔 있는데 호스트엔 없다

ホストディレクトリを丸ごとイメージのデフォルト値に戻したい場合(バックアップはツールが /etc/kopens/conf.backup/<시각>/ に保存します):

cd /opt/kopens/plantpulse-platform-docker/bin
TEMPLATE_FORCE_SEED=1 ./restart-datalake.sh

6. バックアップスケジュール

ファイルは修正しません。コンテナ内 pd backup schedule set が datalake DBの backup_schedule テーブルにQuartz cronを書き込みます — そのテーブルを読み取って実行するのは plantpulse-datalake-admin-api 内のスケジューラーです。管理コンソールのバックアップ画面「Schedule editor」が同じコマンドを呼び出します。

docker exec plantpulse-datalake pd backup schedule                                   # 지금 일정
docker exec plantpulse-datalake pd backup schedule set --job postgres-diff --calendar "*-*-* 02:45:00"
docker exec plantpulse-datalake pd backup schedule set --job purge --enabled false
docker exec plantpulse-datalake pd backup schedule reset --job postgres-diff         # 기본값으로

ジョブ名は5つ — postgres-diff · postgres-full · cassandra-diff · cassandra-full · purge。カレンダーはsystemd構文です(*-*-* 02:45:00 毎日、Sun *-*-* 01:00:00 日曜日)。間違った式は何も書き込まず拒否します。選択は /data1/pp-data/backup/schedule.json に残り、コンテナを再作成しても維持されます → バックアップ · 復元

7. 公開ポート

ホストに開くポートは compose/docker-compose.yml の plantpulse-datalake サービス ports: が決定します。変更する際は2点を確認してください。

• コンテナ内でlistenするポートは defaults.env(PP_*_PORT)とテンプレートが決定します。公開ポートのみ変更すると「コンテナは6379にbind、composeは6399を公開」のような不一致が生じます。両方を一緒に確認する必要があります。
• 1883 / 1884(MQTT)はデータレイクではなく、プロキシコンテナが公開します。データレイクに同じポートを追加すると、bind競合で起動に失敗します。

ポートの全一覧とファイアウォールはポートおよびサービス管理を参照してください。

反映されない場合 — 順番に確認

確認項目	内容
① どのファイルが優先されるか	bin/env.sh --print の # source: 列。ノードファイル > サイドカー > シェル > デフォルト値
② コンテナに届く名前か	composeが設定していない名前は入りません → 変数リファレンス
③ コンテナを再作成したか	サイドカー · ノードファイルの値はコンテナ再作成時にのみ反映されます。docker restart では反映されません — restart-datalake.sh を使用してください
④ レンダリングされたか	pd config diff が 0 かどうか。1 の場合は pd config render 後に再起動
⑤ パスワードか	ファイル編集では変更されません → passwd.sh
⑥ テンプレートが古いか	pd config diff --templates に differs · missing → 上記 3-wayシード

しないでください

• コンテナ内の PP_HOME/…/conf/* を編集しないでください。 次回起動時に消え、消えるまでどちらが本物か誰も知りません。
• docker restart plantpulse-datalake で値の変更を反映しようとしないでください。 環境変数はコンテナを再作成するときに設定されます。restart-datalake.sh がその作業を行います。
• FORCE=1 pd start を使用しないでください。 稼働中のプロセスの上に同じポートで別のプロセスを起動してしまいます。
• PP_KEYSPACE · PP_DB_NAME · PP_TOPIC_PREFIX をインストール後に変更しないでください。 新しい名前の空のストレージが作成され、古いデータは古い名前に残ります。

関連ドキュメント

• 設定ファイルはどこにあるか
• 変数リファレンス
• 起動 · 停止 · 再起動