ランブック: 公開スタンドの導入(単一 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_PASSWORD | init-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を参照してください。四半期ごとのリストア訓練を予定します。 - シード用に作成した一時シークレットファイルを削除します。