シークレット管理

API キーとトークンは 環境変数ファイルにのみ 置きます。設定ファイル(settings.json)は平文のため、ファイルが流出するとキーがそのまま露呈するからです。

この原則は 2026.07 リリースから適用され、既存インストールもそのまま動作します(下記「既存インストールの移行」参照)。

設定の正本は /etc/kopens/plantpulse-studio.env の一つだけ

環境変数ファイルのパスは /etc/kopens/plantpulse-studio.env です。インストールディレクトリ (/opt/kopens/plantpulse-studio-docker) 内ではなく repo ツリー外で、権限は 0600 です。platform · ai · studio の3製品が同じ規約で /etc/kopens/plantpulse-<product>.env を使用します。

インストールディレクトリルートの .env は 旧パスです。現在は誰も読み取らないため、そこを修正してもスタックは変わりません。旧ファイルが残っていても、移行後は照合用のみです。

シークレット6種 — 何を、いつ

.env に格納する値です。使用しない機能のキーは空のままで構いません。

環境変数	用途	いつ必要か	ない場合
`PP_API_TOKEN`	PlantPulse プラットフォームサービスキー	実データ(サイト・設備・タグ・アラーム)参照全般	🔴 空だと起動を拒否します
`PI_LLM_API_KEY`	OpenAI 互換ゲートウェイキー	社内 AI ゲートウェイを使用する場合(デフォルトパス)	🔴 空だと起動を拒否します
`PS_ANTHROPIC_API_KEY`	Anthropic キー	AI プロバイダーが anthropic の場合	エージェントが実際に動作しない(スタブ応答)
`OPENAI_API_KEY`	OpenAI キー	AI プロバイダーが openai の場合	〃
`GIT_TOKEN`	リモート Git アクセストークン(PAT)	アプリのソースを顧客の GitLab/GitHub へプッシュする場合	Git プッシュ機能のみ使用不可
`APP_REGISTRY_TOKEN`	アプリイメージレジストリトークン	デプロイされたアプリを Docker イメージとして push する場合	イメージ push 機能のみ使用不可

コンテナ内で見える名前とは異なります

ログ・ソースでは PLATFORM_API_KEY · AI_API_KEY · ANTHROPIC_API_KEY と表示されますが、 .env に記載する名前は上記のものです。対照表は環境変数リファレンスの「二層の名前」にあります。

AI キーは3つのうち1つだけ

環境設定 → AI タブで選択したプロバイダーに合うキーが1つあれば十分です。社内ゲートウェイ(OpenAI 互換)を使う現場なら PI_LLM_API_KEY です。

キーの設定

sudo vi /etc/kopens/plantpulse-studio.env

# ── 비밀(키·토큰) — 환경변수 전용 ─────────────────────────
PP_API_TOKEN=...
PI_LLM_API_KEY=...
# PS_ANTHROPIC_API_KEY=sk-ant-...
# OPENAI_API_KEY=
# GIT_TOKEN=
# APP_REGISTRY_TOKEN=

sudo chmod 600 /etc/kopens/plantpulse-studio.env
cd /opt/kopens/plantpulse-studio-docker && bash bin/restart.sh

docker restart ではキーは変わりません

docker restart plantpulse-studio-server は .env を再読み込みしません。 コンテナ作成時に注入された旧環境変数をそのまま保持して再起動するだけです。キーを変更した後に「なぜ変わらないのか」と長いこと探す典型の落とし穴です。

必ずコンテナを 再作成 する必要があります。

bash bin/restart.sh
# 또는
docker compose up -d --force-recreate

.env に記載してもコンテナに入るわけではありません

コンテナに渡されるのは docker-compose.yml の environment: リストに記載された変数のみです。上記6種は既に配線済みですが、表にない変数を新規に追加した場合、compose にも同時に追加する必要があります。(受け渡し漏れで AI が無効状態で表示された実例があります。)

反映確認

# 서버가 인식한 키 출처 확인 — 부팅 로그
docker logs plantpulse-studio-server 2>&1 | head -40

画面では 環境設定 → AI / プラットフォーム タブのキー入力欄に 환경변수 기본값 バッジが付き、空欄に 「環境変数値を使用中 — 入力すると上書きします」 と表示されれば正常です。入力欄自体は ロックされません — 環境変数はデフォルト値であり、画面から上書きできます。

優先順位と既存インストールの移行

優先順位	ソース	備考
1	画面で入力した値(`settings.json`)	値があればこちらが優先されます
2	環境変数(`/etc/kopens/plantpulse-studio.env`)	インストールが植え付けるデフォルト値

2026-08-23 にこの順序が«逆転しました»

以前は環境変数が優先されていました。その結果、env に死んだキーが1つ入ると環境設定画面で何を入力しても無視される状態になり、画面からは修正手段が一切ありませんでした。 AI プロバイダーをいつでも切り替えられる必要があるという要件が、この順序を強制しました。

そのため キーが死んでいてもサーバーに入る必要はありません — 環境設定画面に新しい値を入力すれば即座に上書きされます。以前の順序を覚えていた方は、ここで変更してください。

代償は settings.json が平文であることです(サーバーが 0600 を強制し、バックアップアーカイブも 600/700)。シークレットをファイルに置きたくない場合は 画面を空にし、環境変数のみを 使用してください — そうすれば従来と同様に動作します。

アップグレードしても既存インストールが突然壊れることはありません。ただし、ファイルにシークレットが残っている場合、起動ログが移行先を通知します(値はログに絶対残らず、どの項目をどの環境変数に移せばよいかのみ表示されます)。

settings.json 에 비밀이 남아 있습니다 — … platform.apiKey → PLATFORM_API_KEY

移行手順は3段階です。

該当値を /etc/kopens/plantpulse-studio.env の対応環境変数へ移す
bash bin/restart.sh
環境設定画面でその項目のバッジが 환경변수 기본값 に変わったことを確認後、 settings.json で旧値を削除する → 起動警告が消える

settings.json の場所

<DATA_ROOT>/state/settings.json (デフォルト /var/lib/pp-studio/state/settings.json)。編集前のバックアップを推奨し、編集後は再起動が必要です。

キー交換(ローテーション)

Anthropic キーとゲートウェイキーには 専用ツールがあります。 ファイル更新とコンテナ再作成を一度に行い、値がシェルヒストリーに残りません。

cd /opt/kopens/plantpulse-studio-docker
bash bin/backup.sh                    # ① 되돌릴 지점 확보
bin/passwd.sh PS_ANTHROPIC_API_KEY    # ② 값 생략 → 프롬프트로 입력
bash bin/status.sh                    # ③ 헬스 확인

詳細な使用方法はパスワード · API キー変更にあります。

残りのキー(PP_API_TOKEN · OPENAI_API_KEY · GIT_TOKEN · APP_REGISTRY_TOKEN)はツールの対象外のため、ファイルを直接編集します。

cd /opt/kopens/plantpulse-studio-docker
bash bin/backup.sh                              # ① 되돌릴 지점 확보
sudo vi /etc/kopens/plantpulse-studio.env       # ② 새 키로 교체
bash bin/restart.sh                             # ③ 컨테이너 재생성
bash bin/status.sh                              # ④ 헬스 확인

交換後はチャット問い合わせ1回(プラットフォームキー確認)、アプリビルド1回(AI キー確認)で実動作を点検するのが確実です。

自動的に適用される保護

項目	動作
ファイル権限	サーバーが起動するたびに `settings.json` · 環境変数ファイルを `0600`、状態ディレクトリを `0700` に強制
監査ログ	環境設定変更時に変更されたフィールドが記録される — シークレットは値の代わりに指紋(ハッシュ先頭8文字)のみ
画面	環境変数で管理されるキーは入力が無効化され、誤って上書きできない
キー代行	プラットフォームキーはサーバー内のみに存在し、ログインしたユーザーのリクエストにのみ代わりに付与される(匿名リクエストには付与されない)

例外 — MCP 外部サーバートークン

環境設定 → MCP タブでユーザーが任意の数追加する外部 MCP サーバーのトークンは、数が可変のため環境変数で表現できず、settings.json に保存されます。 (プラットフォーム・AI キーよりも感度が低い値です。)

守るべきこと

してはいけないこと

環境変数ファイル · settings.json をバージョン管理(Git)にコミットしないでください。正本を repo ツリー外(/etc/kopens/)に置いた理由がこれです。
キーをチャット・メール・チケット本文に貼り付けないでください。
バックアップアーカイブを権限なく共有しないでください — バックアップと復元の取り扱い注意を参照。

露出した疑いがある場合

発行元(プラットフォーム · AI プロバイダー · Git · レジストリ)で まず無効化 し、新しいキーを発行した後、上記「キー交換」手順を実行してください。サーバー再起動までは旧キーがメモリに残っています。

シークレット6種 — 何を、いつ​

キーの設定​

反映確認​

優先順位と既存インストールの移行​

キー交換(ローテーション)​

自動的に適用される保護​

例外 — MCP 外部サーバートークン​

守るべきこと​

関連ドキュメント​