設定を変更する方法

何を変更するかによって、編集するファイルと反映方法が異なります。 まず以下の表から自分の場合を探してください。

変更内容	例	編集場所	反映
パスワード · 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 保持期間、Cassandra ヒープ	/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 は このボックスのみに当てはまる値 を記入するファイルです。別のボックスにコピーしてはいけません — 実際に1つのボックスのファイルをコピーした別のボックスが、静かに間違った役割として再インストールされたことがあります。

変数	何時に記入するか	空にすると
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つだと相互に上書きします。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、Cassandra 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 です。デフォルト 80G、ホストがそれより小さい場合は RAM の 90% で自動計算されます。ボックスごとに異なる値なので ノードファイル に記入します。

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

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

小すぎる値にすると «Up だが停止中» 状態になります

コンテナ内の PID 1 は systemd なので、Java プロセスのみが cgroup で OOM-kill され、docker ps は引き続き Up を表示します。Kill 記録は ホストの dmesg にのみ残ります。2026-09-04 に 64g 上限下で実際に発生し(実測ピーク 63.9G)、デフォルト値が 80G に上げられました。

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 はホストファイルなので、イメージが新しいデフォルト値を持ってきても 自動的に変わりません。 だから起動ツールが配置ごとにファイル単位で3つを比較します — 今回のイメージのデフォルト値、前回の配置のデフォルト値(/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

2026-09-03 以前のバッチの /etc/kopens/conf は自動的に再シードされます

古い plantpulse-startup バッチ(ファイル名に .template サフィックスなし)が残っていると pd がレンダリングするものがありません。起動ツールがそれを検出してバックアップ後にイメージから再シードし、[WARN] stale template layout で通知します。古い編集はバックアップにのみ残り、自動的にはマイグレートされません。

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

ファイルを編集しません。コンテナ内の pd backup schedule set が systemd タイマーを検証して書き込みます。管理コンソールのバックアップ画面の «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 をインストール後に変更しないでください。 新しい名前の空のリポジトリが作成され、古いデータは古い名前に残ります。

関連ドキュメント

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