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

秘密情報の管理

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

このポリシーは 2026.07 リリースから適用されます。既存のインストールも引き続き動作します(下の「既存インストールの移行」を参照)。

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

環境変数ファイルのパスは**/etc/kopens/plantpulse-studio.env**です。インストールディレクトリ(/opt/kopens/plantpulse-studio-docker)内ではなく、リポジトリツリーの外に置き、パーミッションは0600です。Platform · AI · Studio の 3 製品が同じ規約で/etc/kopens/plantpulse-<product>.envを使用します。

インストールディレクトリのルートにある.envは旧パスです。現在誰も読み込まないため、そこを編集してもスタックは変わりません。旧ファイルが残っていても、移行後は参照目的のみです。

秘密情報 6 種 — 何を、いつ​

.envに入れる値です。使わない機能のキーは空にしておいてかまいません。

環境変数用途必要になる時期ない場合
PLATFORM_API_KEYPlantPulse Platform サービスキー本データ(サイト·設備·タグ·アラーム)の照会全般チャット質問·デプロイアプリで本データが照会されない
ANTHROPIC_API_KEYAnthropic キーAI プロバイダがanthropicの場合エージェントが実際に動作しない(スタブ応答)
OPENAI_API_KEYOpenAI キーAI プロバイダがopenaiの場合〃
AI_API_KEYOpenAI 互換ゲートウェイキー社内 AI ゲートウェイを使う場合〃
GIT_TOKENリモート Git アクセストークン(PAT)アプリソースを顧客の GitLab/GitHub にプッシュする場合Git プッシュ機能のみ使用不可
APP_REGISTRY_TOKENアプリイメージレジストリトークンデプロイされたアプリを Docker イメージで push する場合イメージ push 機能のみ使用不可
AI キーは 3 つの中から 1 つだけ

環境設定 → AI タブで選択したプロバイダに対応するキーが 1 つあればかまいません。社内ゲートウェイ(OpenAI 互換)を使う現場の場合はAI_API_KEYです。

キーの入力​

sudo vi /etc/kopens/plantpulse-studio.env
# ── 비밀(키·토큰) — 환경변수 전용 ─────────────────────────
PLATFORM_API_KEY=...
ANTHROPIC_API_KEY=sk-ant-...
# OPENAI_API_KEY=
# AI_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 pp-studio-serverは**.envを再度読み込みません。**コンテナ作成時に注入された以前の環境変数をそのまま保持して再起動するだけです。キーを変更した後に「なぜそのままなんだ」と長く探し続けることになる典型的な落とし穴です。

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

bash bin/restart.sh
# 또는
docker compose up -d --force-recreate
.envに入れたからといってコンテナに渡されるわけではありません

コンテナに渡されるのはdocker-compose.ymlのenvironment:リストに記載されている変数だけです。上記 6 種はすでに配線されていますが、表にない変数を新たに追加した場合は compose にも合わせて追加する必要があります。(渡し忘れで AI が無効状態で起動した実例があります。)

反映確認​

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

画面上では、環境設定 → AI / Platform タブのキー入力欄が無効化され、**「環境変数で管理中」**と表示されていれば正常です。

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

順位出典備考
1環境変数(/etc/kopens/plantpulse-studio.env)値があればこちらが常に優先されます
2settings.jsonレガシーフォールバック — 旧インストール互換用

アップグレードしても既存インストールが急に動作しなくなることはありません。ただしファイルに秘密情報が残っている場合、起動ログが移行対象を通知します(値はログに絶対残らず、どの項目をどの環境変数に移すべきかだけを表示します)。

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

移行手順は 3 ステップです。

  1. 該当値を/etc/kopens/plantpulse-studio.envの対応する環境変数に移す
  2. bash bin/restart.sh
  3. 環境設定画面でその項目が「環境変数で管理中」に変わったことを確認した後、settings.jsonで旧値を削除する → 起動時の警告が消える
settings.json の位置

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

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

ANTHROPIC_API_KEY · AI_API_KEYには**専用ツールがあります。**ファイル更新とコンテナ再作成を一度に行い、値がシェルの履歴に残りません。

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

詳しい使い方はパスワード · API キーの変更に記載されています。

その他のキー(PLATFORM_API_KEY · 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 回(Platform キーの確認)、アプリビルド 1 回(AI キーの確認)で実際の動作を確認するのが確実です。

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

項目動作
ファイルパーミッションサーバ起動時に毎回settings.json·環境変数ファイルを0600、ステータスディレクトリを0700に強制
監査ログ環境設定変更時に変更されたフィールドが記録される — 秘密情報は値の代わりにフィンガープリント(ハッシュの先頭 8 文字)のみ
画面環境変数で管理されるキーは入力が無効化され、誤って上書きすることができない
キー代行Platform キーはサーバ内のみに存在し、ログイン済みユーザーのリクエストにのみ代行で付加されます(匿名リクエストには付加されません)

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

環境設定 → MCP タブでユーザーが任意の数だけ追加する外部 MCP サーバーのトークンは、数が可変なため環境変数では表現できずsettings.jsonに保存されます。 (Platform · AI キーより機密性が低い値です。)

守るべきこと​

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

発行元(Platform · AI プロバイダ · Git · レジストリ)で先に廃止し、新しいキーを発行した後、上の「キーの交換」手順を実行してください。サーバ再起動前は旧キーがメモリに残っています。

関連ドキュメント​