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

ランブック: 公開スタンドの導入(単一 VPS)

対象: RAM 4–8 GB の VPS 1台です。deploy/docker-compose.prod.yml 経由で公開エッジ(api / admin / dashboard のドメイン)を公開します。所要時間は約30分です。関連: docs/runbooks/production.md(2日目以降の運用)、docs/runbooks/alerts.md(アラート配信)、docs/runbooks/backup-restore-rehearsal.md(DR 訓練)。

0. 前提条件​

  • VPS は RAM 4–8 GB、vCPU 2以上、ディスク 40 GB、Docker Engine と docker compose プラグインです。real-models プロファイル(classifier/embedder/llama-server)には、その範囲の大きい側が必要です。プロファイルなしでは、スタックはモック層で動作します(deploy/docker-compose.e2e.yml を参照)。

DNS: VPS の IP を指す A レコードを3つ用意します。

  • API_DOMAIN(ゲートウェイ、OpenAI 互換 API)
  • ADMIN_DOMAIN(管理コンソール)
  • DASHBOARD_DOMAIN(React SPA)
  • ポート 80/443 を開放します(Caddy は初回起動時に Let's Encrypt 証明書を発行します)。
  • リポジトリを /opt/yabanin にチェックアウトします(異なる場合は以降のパスを調整してください)。

1. シークレット(初回のみ、冪等)​

cd /opt/yabanin
./scripts/deploy/init-secrets.sh

deploy/.env(deploy/.env.example から)と deploy/secrets/(pg_uri、session_key、cache_hmac、kms_local_key、metrics-bearer.key)を作成します。いずれもモードは 600 です。どちらのパスも gitignore されています。コミットしたり、暗号化せずに筐体外へコピーしたりしないでください。

2. deploy/.env の設定​

vi deploy/.env

必須:

変数意味
API_DOMAIN / ADMIN_DOMAIN / DASHBOARD_DOMAIN公開ホスト名(Caddy と管理 Cookie のドメイン)
POSTGRES_PASSWORDinit-secrets が生成します。最初の up の後は変更しないでください(pg_data は古い値を保持します)

公開前に推奨:

変数意味
ALERT_WEBHOOK_URL所有者の webhook(Slack/PagerDuty/運用)
ALERT_TG_BOT_TOKEN所有者の Telegram ボットトークン(@BotFather から)
ALERT_TG_CHAT_ID所有者のチャット ID(ボットへ一度書き込み、その後 https://api.telegram.org/bot<token>/getUpdates を確認します)

重要な Prometheus アラートは両方のチャネルへファンアウトします。未設定のものは開発用のブラックホールシンクのままです。試験発火: docs/runbooks/alerts.md。

3. ビルドと起動​

# Dashboard static assets (dashboard-web mounts web/dashboard/dist)
npm ci --prefix web/dashboard && npm run build --prefix web/dashboard

cd deploy
docker compose -f docker-compose.prod.yml build # gateway/admin/loggerd images
docker compose -f docker-compose.prod.yml run --rm migrate # exit code enforced
docker compose -f docker-compose.prod.yml up -d --wait --scale migrate=0

up は postgres/redis、可観測性スタック(prometheus、alertmanager、grafana)、caddy(TLS)、dashboard-web、バックアップとステータスページのサイドカーも起動します。

4. シード(組織 + ルート管理者 + 最初の API キー)​

deploy/.env に追加します(すべて任意です。SEED_ADMIN_EMAIL が未設定なら何もしません):

SEED_ADMIN_EMAIL=owner@example.com
YABANIN_ADMIN_PASSWORD_FILE=/run/secrets/seed_admin_password
SEED_PROFILE=provider # or mock
SEED_UPSTREAM_URL=https://api.z.ai/v1
SEED_UPSTREAM_KEY_FILE=/run/secrets/upstream_key
SEED_MODEL=gpt-4o

追加のシークレットファイルを2つマウントし、ワンショットを実行します。

cd deploy
echo ',strong-password' > secrets/seed_admin_password # mode 600, then delete after seeding
echo '$UPSTREAM_KEY' > secrets/upstream_key # mode 600, then delete after seeding
docker compose -f docker-compose.prod.yml run --rm \
-v ./secrets/seed_admin_password:/run/secrets/seed_admin_password:ro \
-v ./secrets/upstream_key:/run/secrets/upstream_key:ro seed

シードされた API キーの平文は、コンテナログに一度だけ出力されます(docker compose logs seed)。2回目の実行は冪等な無操作で、再出力はしません。

5. スモーク​

# Static + functional smoke against the local stack (mock overlay):
./scripts/deploy/smoke.sh --up

# Public edge checks (from any machine):
curl -sS https://$API_DOMAIN/healthz # {"status":"ok"}
curl -sS https://$ADMIN_DOMAIN/health # {"status":"ok"}
curl -sSI https://$DASHBOARD_DOMAIN/ | head -1 # HTTP/2 200
curl -sS https://$API_DOMAIN/status.html # static status page

チャット補完(シード手順で得た実際のキー):

curl -sS https://$API_DOMAIN/v1/chat/completions \
-H "Authorization: Bearer $SEED_KEY" -H 'Content-Type: application/json' \
-d '{"model":"gpt-4o","messages":[{"role":"user","content":"ping"}],"max_tokens":16}'

レート制限の確認(429)​

レート制限はアプリ内で適用されます(deploy/caddy/Caddyfile.tmpl の注記を参照)。最も厳しいゾーンを確認します。管理ログインは、15分あたり、IP ごとに 5回です。

for i in 1 2 3 4 5 6; do
curl -s -o /dev/null -w "attempt $i: %{http_code}\n" -X POST \
https://$ADMIN_DOMAIN/auth/login -d 'email=nobody@example.com&password=x'
done
# expect 200 (or 401 wrong-credentials) for 1–5 and 429 on attempt 6

ゲートウェイのゾーン(50 リクエスト/秒/IP、バースト 100、429 時は Retry-After)を発動させるには負荷ツールが必要です: hey -n 300 -c 50 https://$API_DOMAIN/healthz。

6. 導入後チェックリスト​

  • 3つのドメインすべてが、有効な証明書付きの TLS を提供しています。
  • docker compose -f docker-compose.prod.yml ps — すべてのサービスが健全です(migrate/seed が終了コード 0 で終わるのは、想定されたワンショットです)。
  • 管理コンソールへのログインが動作し、シードされた組織とキーが見えます。
  • Telegram/webhook の試験アラートを受信しています(docs/runbooks/alerts.md を参照)。
  • https://$API_DOMAIN/status.html ですべてのサービスが "ok" と表示されます。
  • バックアップの着地: ls deploy/../ → docs/runbooks/backup-restore-rehearsal.md を参照してください。四半期ごとのリストア訓練を予定します。
  • シード用に作成した一時シークレットファイルを削除します。