Self-hosted Proxy セットアップガイド

対象読者: 自社サーバー上で PII Firewall Proxy を運用したい開発者・インフラ担当者

Self-hosted Proxy は、PII マスキング処理を自社ネットワーク内で完結させる Docker イメージです。
外部に PII を送信せず、顧客データが自社の信頼境界の外に出ることはありません。

Privacy by Design 準拠

顧客アプリ → [PIIFW Proxy（自社サーバー）] → マスク済みテキストのみ
                                                      ↓
                                               LLM API（外部）

PII は自社ネットワーク内に留まります ✅

前提条件

要件	内容
Docker	Docker 20.10 以上（または Docker Desktop）
ライセンスキー	`piifirewall.com/console` →「Self-hosted Proxy」タブで発行
GitHub アカウント	Container Registry (GHCR) からイメージを pull するために必要
GitHub PAT	`read:packages` スコープの Personal Access Token
LLM API キー	使用するプロバイダー（OpenAI / Anthropic / Google 等）のキー

クイックスタート（約 5 分）

Step 1 — ライセンスキーを取得

piifirewall.com/console にログイン
「Self-hosted Proxy」タブを開く
「ライセンスキーを発行」ボタンをクリック
表示された JWT 形式のキー（eyJ...）をコピー

ライセンスキーの保管

ライセンスキーは再表示できません。発行直後に安全な場所（パスワードマネージャー等）に保管してください。

Step 2 — GHCR にログイン

PII Firewall のコンテナイメージは GitHub Container Registry（GHCR）のプライベートリポジトリで配布されます。
pull するには read:packages スコープの GitHub PAT が必要です。

GitHub PAT の作成:

GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
「Generate new token (classic)」をクリック
スコープで read:packages にチェック
トークンをコピー

GHCR にログイン:

bash

docker login ghcr.io -u <YOUR_GITHUB_USERNAME> -p <YOUR_GITHUB_PAT>

Step 3 — Proxy を起動

bash

docker run -d \
  --name piifw-proxy \
  -p 3001:3001 \
  -e PIIFW_LICENSE_KEY="eyJhbGci..." \
  -e OPENAI_API_KEY="sk-..." \
  ghcr.io/kmishimaslgithub/pii-firewall/proxy:latest

使用する LLM プロバイダーの API キーのみ設定してください（全て必須ではありません）。

Step 4 — 動作確認

bash

# ヘルスチェック
curl http://localhost:3001/health

# PII 検出テスト
curl -X POST http://localhost:3001/detect \
  -H "Content-Type: application/json" \
  -d '{"text": "田中太郎のメールは tanaka@example.com です", "lang": "ja"}'

期待されるレスポンス（/health）:

json

{
  "status": "ok",
  "license": {
    "mode": "jwt",
    "plan": "free",
    "api_calls_this_month": 0
  }
}

Step 5 — アプリのエンドポイントを変更

diff

- const PIIFW_BASE = "https://pii-firewallproxy-production.up.railway.app";
+ const PIIFW_BASE = "http://localhost:3001";  // または自社サーバーの内部アドレス

これだけで PII 保護が自社ネットワーク内で完結します。

⚠️ 重要: トークン消失リスク

バックアップ必須

mask_pii() が返す [SECURED:xxx] トークンは、この Proxy コンテナのストレージにのみ存在します。
コンテナを削除・再起動（デフォルトの memory モード）した場合、保存済みトークンは永久に消失し、元のデータに戻すことができません。

必須対応:

本番環境では PIIFW_STORE=redis または PIIFW_STORE=postgres を設定してトークンを永続化する
Redis / PostgreSQL の定期バックアップを実施する
[SECURED:xxx] を保存しているテーブル・フィールドを把握し、バックアップ対象に含める

環境変数リファレンス

起動必須

変数名	必須	デフォルト	説明
`PIIFW_LICENSE_KEY`	✅*	—	ライセンスキー（JWT 形式）。`PIIFW_LICENSE_FILE` を使う場合は不要
`PORT`		`3001`	リッスンポート
`NODE_ENV`		`production`	実行環境

LLM API キー（使用するプロバイダーのみ設定）

変数名	説明
`OPENAI_API_KEY`	OpenAI（GPT-4o 等）
`ANTHROPIC_API_KEY`	Anthropic（Claude）
`GOOGLE_API_KEY`	Google（Gemini）
`CUSTOM_LLM_BASE_URL`	OpenAI 互換 API を持つプロバイダー（Groq / Ollama / Azure OpenAI 等）の Base URL
`CUSTOM_LLM_API_KEY`	上記プロバイダーの API キー
`CUSTOM_LLM_MODEL`	使用するモデル名（例: `llama-3.3-70b-versatile`）

OpenAI 互換 API 対応プロバイダー

CUSTOM_LLM_BASE_URL を設定することで以下のプロバイダーに対応できます:

プロバイダー	Base URL
Groq	`https://api.groq.com/openai/v1`
Azure OpenAI	`https://{resource}.openai.azure.com/openai/deployments/{deployment}/`
Ollama（ローカル）	`http://localhost:11434/v1`
LM Studio（ローカル）	`http://localhost:1234/v1`
Mistral	`https://api.mistral.ai/v1`
Together AI	`https://api.together.xyz/v1`

Ollama / LM Studio を使用することで 完全オフライン（エアギャップ）構成 も実現できます。

ストレージ設定

変数名	デフォルト	説明
`PIIFW_STORE`	`memory`	ストレージバックエンド（`memory` / `redis` / `postgres`）
`PIIFW_TOKEN_TTL`	`86400000`	トークンの保存時間（ミリ秒）。`0` で無期限
`PIIFW_STORE_URL`	—	Redis または PostgreSQL の接続 URL

ログ設定

変数名	デフォルト	説明
`LOG_LEVEL`	`info`	ログレベル（`debug` / `info` / `warn` / `error`）

Privacy by Design — ログについて

どのログレベルに設定しても、リクエストボディ（PII を含む可能性のあるデータ）はログに記録されません。
記録されるのはメタデータ（タイムスタンプ・HTTP ステータス・処理時間）のみです。この動作はコードレベルで強制されており、設定で変更することはできません。

高度な設定

変数名	説明
`PIIFW_LICENSE_FILE`	エアギャップモード用ライセンスファイルのパス（Enterprise 向け）
`UI_ORIGIN`	CORS 許可オリジン（カンマ区切りで複数指定可）

ストレージ設定

インメモリ（デフォルト）

bash

PIIFW_STORE=memory

✅ メリット	⚠️ 注意点
設定不要・即時起動	コンテナ再起動でトークン消失
POC・評価用途に最適	本番環境には非推奨

Redis（本番推奨）

bash

PIIFW_STORE=redis
PIIFW_STORE_URL=redis://localhost:6379
# TLS 環境の場合: rediss://user:password@your-redis-host:6380

✅ メリット	用途
コンテナ再起動後もトークン保持	本番・ステージング環境
高速（インメモリ DB）	高トラフィック環境

PostgreSQL（Enterprise）

bash

PIIFW_STORE=postgres
PIIFW_STORE_URL=postgresql://piifw:password@localhost:5432/piifw

✅ メリット	用途
完全永続化・監査ログ対応	Enterprise・コンプライアンス要件あり
既存 PostgreSQL に統合可能	既存インフラ活用

Docker Compose を使う場合

docker-compose.selfhosted.yml を使用することで、Redis や PostgreSQL を含む構成を簡単に起動できます。

bash

# ダウンロード
curl -O https://raw.githubusercontent.com/kmishimaslgithub/pii-firewall/main/proxy/docker-compose.selfhosted.yml

# 環境変数ファイルを作成
cp .env.selfhosted.example .env
# .env に PIIFW_LICENSE_KEY と LLM API キーを記入

# 起動（インメモリモード）
docker compose -f docker-compose.selfhosted.yml up -d

# 起動（Redis 付き・本番推奨）
docker compose -f docker-compose.selfhosted.yml --profile redis up -d

エアギャップモード（Enterprise）

外部通信がゼロの閉域網環境向けの起動方法です。
M-DEEP から年次で発行される .lic ファイルを使用します。

bash

docker run -d \
  --name piifw-proxy \
  -p 3001:3001 \
  -e PIIFW_LICENSE_FILE=/etc/piifw/license.lic \
  -v /path/to/your/license.lic:/etc/piifw/license.lic:ro \
  -e CUSTOM_LLM_BASE_URL=http://your-ollama-server:11434/v1 \
  -e CUSTOM_LLM_MODEL=llama3.2 \
  ghcr.io/kmishimaslgithub/pii-firewall/proxy:latest

エアギャップモードの特徴

PIIFW_LICENSE_KEY は不要（PIIFW_LICENSE_FILE を使用）
月次レポートは送信されません（外部通信ゼロ）
LLM は Ollama 等のローカル推論サーバーを使用可能
ライセンスの有効期限は 1 年。更新時は新しい .lic ファイルを差し替えてコンテナを再起動

イメージの真正性確認（SHA256）

各リリースの GitHub Release ページに SHA256 ダイジェストを公開しています。
pull したイメージが公式ビルドであることを以下の手順で確認できます。

bash

# 1. GitHub Release ページから SHA256 ダイジェストを確認
#    例: sha256:abc123...

# 2. ダイジェスト指定で pull（推奨）
docker pull ghcr.io/kmishimaslgithub/pii-firewall/proxy@sha256:abc123...

# 3. pull 済みイメージのダイジェストを確認
docker inspect ghcr.io/kmishimaslgithub/pii-firewall/proxy:latest \
  --format='{{index .RepoDigests 0}}'

Privacy by Design — M-DEEP へ送信されるデータ

通常モード（PIIFW_LICENSE_KEY）では、月に 1 回だけ M-DEEP へレポートを送信します。
送信されるのは以下の 3 項目のみです。PII・テキスト・IP アドレスは一切含まれません。

json

{
  "license_key_hash": "sha256:xxxx",  // ライセンスキーのハッシュ（キー本体は送らない）
  "api_calls_this_month": 8432,        // APIコール数（整数のみ）
  "proxy_version": "1.2.0"             // Proxy のバージョン（互換性確認用）
}

項目	送信される？
テキスト・プロンプト内容	❌ 送信しない
マスク前・マスク後のデータ	❌ 送信しない
IPアドレス・ホスト情報	❌ 送信しない
ユーザー情報・操作ログ	❌ 送信しない
APIコール数（整数）	✅ 月次のみ

レポートを手動で送信・確認するには:

bash

curl -X POST http://localhost:3001/license/refresh

トラブルシューティング

コンテナが起動しない / すぐに終了する

bash

# ログを確認
docker logs piifw-proxy

よくある原因:

エラーメッセージ	原因	対応
`LICENSE ERROR: 有効期限切れ`	ライセンスキーの期限切れ	`piifirewall.com/console` でキーを更新
`LICENSE ERROR: 発行元が不正`	無効なライセンスキー	キーが正しくコピーされているか確認
`LICENSE ERROR: 署名が不正`	ライセンスキーが改ざんされている	新しいキーを再発行

GHCR からイメージを pull できない

bash

# 認証状態を確認
docker login ghcr.io -u <YOUR_GITHUB_USERNAME> -p <YOUR_GITHUB_PAT>

# PAT のスコープを確認（read:packages が必要）
# GitHub → Settings → Developer settings → Personal access tokens

`[SECURED:xxx]` が復元できない

bash

# ストレージ状態を確認
curl http://localhost:3001/health | jq .

# ストレージが memory の場合 → コンテナ再起動でトークンが消失します
# → PIIFW_STORE=redis または postgres に変更してバックアップを設定してください

ヘルスチェックが失敗する

bash

# ポートのバインドを確認
docker ps | grep piifw-proxy

# コンテナ内から確認
docker exec piifw-proxy wget -qO- http://localhost:3001/health

次のステップ

エンドポイントリファレンス（REST API） — 全エンドポイントの仕様
Secure RAG — RAG パイプラインへの組み込み方法
複合攻撃検知 — プロンプトインジェクション・SQL インジェクション検知

Self-hosted Proxy セットアップガイド ​

前提条件 ​

クイックスタート（約 5 分） ​

Step 1 — ライセンスキーを取得 ​

Step 2 — GHCR にログイン ​

Step 3 — Proxy を起動 ​

Step 4 — 動作確認 ​

Step 5 — アプリのエンドポイントを変更 ​

⚠️ 重要: トークン消失リスク ​

環境変数リファレンス ​

起動必須 ​

LLM API キー（使用するプロバイダーのみ設定） ​

ストレージ設定 ​

ログ設定 ​

高度な設定 ​

ストレージ設定 ​

インメモリ（デフォルト） ​

Redis（本番推奨） ​

PostgreSQL（Enterprise） ​

Docker Compose を使う場合 ​

エアギャップモード（Enterprise） ​

イメージの真正性確認（SHA256） ​

Privacy by Design — M-DEEP へ送信されるデータ ​

トラブルシューティング ​

コンテナが起動しない / すぐに終了する ​

GHCR からイメージを pull できない ​

[SECURED:xxx] が復元できない ​

ヘルスチェックが失敗する ​

次のステップ ​

Self-hosted Proxy セットアップガイド

前提条件

クイックスタート（約 5 分）

Step 1 — ライセンスキーを取得

Step 2 — GHCR にログイン

Step 3 — Proxy を起動

Step 4 — 動作確認

Step 5 — アプリのエンドポイントを変更

⚠️ 重要: トークン消失リスク

環境変数リファレンス

起動必須

LLM API キー（使用するプロバイダーのみ設定）

ストレージ設定

ログ設定

高度な設定

ストレージ設定

インメモリ（デフォルト）

Redis（本番推奨）

PostgreSQL（Enterprise）

Docker Compose を使う場合

エアギャップモード（Enterprise）

イメージの真正性確認（SHA256）

Privacy by Design — M-DEEP へ送信されるデータ

トラブルシューティング

コンテナが起動しない / すぐに終了する

GHCR からイメージを pull できない

`[SECURED:xxx]` が復元できない

ヘルスチェックが失敗する

次のステップ