Yabanin 本番ランブック
アーキテクチャ概要
┌─────────────────────────────────────────┐
│ Internet / CDN │
└────────────────┬───────── ───────────────┘
│
┌────────────────▼────────────────────────┐
│ Gateway (:8082) │
│ - Auth middleware (API key → org/team) │
│ - Cache lookup (Redis + pgvector) │
│ - Classifier routing (ML + rule-tier) │
│ - Budget enforcement │
│ - Upstream proxy (OpenAI/Anthropic) │
└──┬──────┬──────┬──────┬──────────────────┘
│ │ │ │
┌──────────▼┐ ┌──▼──┐ ┌▼────────┐ ┌──────────────┐
│ PostgreSQL │ │Redis│ │Classifier│ │ BGE Embedder │
│ (:5432) │ │(:6379)│ (:8080) │ │ (:6006) │
│ pgvector │ │ │ │ ML V1 │ │ │
└─────┬─────┘ └──┬──┘ └─────────┘ └──────────────┘
│ │
┌─────▼─────┐ │ Redis Stream: events:queue
│ Admin ─│ │
│ (:8086) │◄───┘
│ Dashboard │ ┌──────────────┐
│ (:3000) │ │ Loggerd │
└───────────┘ │ (:8085) │
│ DB writer │
└────── ────────┘
サービス
| サービス | ポート | 目的 | ヘルスチェック |
|---|---|---|---|
| ゲートウェイ | 8082 | メイン API プロキシ(OpenAI 互換) | GET /healthz |
| Admin | 8086 | 管理パネル + REST API | GET /health |
| Loggerd | 8085 | Redis ストリーム → PostgreSQL ライター | GET /healthz |
| PostgreSQL | 5432 | プライマリデータベース(pgvector) | pg_isready |
| Redis | 6379 | キャッシュ + イベントストリーム | redis-cli ping |
| Classifier | 8080 | ML タスクの複雑度(bge-small) | GET /health |
| BGE Embedder | 6006 | セマンティックキャッシュ向けの埋め込みサービス | GET /health |
| Dashboard | 3000 | React のコスト利用分析ダッシュボード | HTTP 200 |
導入
初回導入
# 1. Create secrets (one-time setup)
cd deploy/secrets
echo "postgresql://yabanin:SECRET@postgres:5432/yabanin?sslmode=disable" > pg_uri
openssl rand -hex 32 > session_key
openssl rand -hex 32 > cache_hmac
# 2. Build and start all services
cd deploy/
docker compose up -d
# 3. Verify migrations ran
docker compose logs migrate | tail -20
# 4. Verify all services healthy
docker compose ps
curl http://localhost:8082/healthz
curl http://localhost:8086/health
サービスの更新
# Rebuild and restart a single service
docker compose up -d --build gateway
# Zero-downtime rolling restart (for config-only changes)
docker compose restart gateway
ロールバック
# Roll back to previous image
docker compose down gateway
docker tag yabanin-gateway:latest yabanin-gateway:rollback
docker tag yabanin-gateway:previous yabanin-gateway:latest
docker compose up -d gateway
# Database rollback (if migration caused issues)
# CAUTION: only run .down.sql if you understand the consequences
psql -h localhost -U yabanin -d yabanin -f migrations/0029_team_budgets.down.sql
環境変数
ゲートウェイ
| 変数 | 必須 | 説明 |
|---|---|---|
YABANIN_GATEWAY_LISTEN | はい | 待受 アドレス(:8082) |
YABANIN_PG_URI_FILE | はい | PG 接続文字列シークレットへのパス |
YABANIN_REDIS_ADDR | はい | Redis アドレス(redis:6379) |
YABANIN_EVENT_STREAM | はい | Redis ストリーム名(events:queue) |
YABANIN_CACHE_HMAC_SECRET_FILE | はい | HMAC 署名シークレットへのパス |
YABANIN_EMBEDDER_BASE_URL | いいえ | 埋め込みサービスの URL |
YABANIN_EMBEDDER_ENABLED | いいえ | セマンティックキャッシュを有効にします(true/false) |
Admin
| 変数 | 必須 | 説明 |
|---|---|---|
YABANIN_PG_URI_FILE | はい | PG 接続文字列へのパス |
YABANIN_SESSION_KEY_FILE | はい | セッション署名キーへのパス |
YABANIN_ADMIN_LISTEN | はい | 待受アドレス(:8086) |
YABANIN_ADMIN_DOMAIN | はい | Cookie のドメイン(localhost) |
YABANIN_ADMIN_API_KEY | いいえ | 読み取り専用の /internal サービス API を有効にします(下記を参照) |
Admin: 内部サービス API
- デフォルトでは無効です。
YABANIN_ADMIN_API_KEYがない場合、独立した/internalの公開面はありません。 - エンドポイント:
GET /internal/api-keys?org_id=<id>&page=1&page_size=50、GET /internal/analytics/savings?org_id=<id>&days=7。 - 認証: 定数時間でのヘッダー検査です。キーは
X-Admin-Key: <value>として送ります(trcli は--api-keyを使います)。 - 読み取り専用かつ組織スコープです。両方のルートは
org_idを必須とし、変更操作は公開しません。
スケーリング
垂直(CPU/メモリの増加)
# In docker-compose.yml, under deploy.resources:
deploy:
resources:
limits:
memory: 512M # was 256M
cpus: "2.0" # was 1.0
水平(レプリカの追加)
ゲートウェイと loggerd はステートレスなので、水平にスケールしても安全です。
docker compose up -d --scale gateway=3 --scale loggerd=2
ゲートウェイのレプリカの前に、ロードバランサ(nginx/HAProxy)を置きます。
Redis のスケーリング
- 読み取りレプリカ: 読み取りが多いワークロード(キャッシュの参照)向けに Redis レプリカを追加します
- メモリ:
used_memoryを監視します。OOM の前にコンテナのメモリ上限を上げてください - 永続化: 耐久性のため
appendonly yesが有効です。AOF の書き換え頻度を監視します
PostgreSQL のスケーリング
- コネクションプーリング: ゲートウェイの接続が
max_connectionsを超える場合は PgBouncer を使います - pgvector: HNSW インデックスのサイズを監視します。クエリのレイテンシが悪化したら再インデックスします
- 読み取りレプリカ: 利用分析やダッシュボードのクエリ(admin サービス)向けに追加します
インシデント対応
P0: ゲートウェイ停止(すべてのリクエストが失敗)
# 1. Check gateway health
curl http://localhost:8082/healthz
# 2. Check recent logs
docker compose logs gateway --tail=100
# 3. Check dependencies
docker compose ps # Are postgres/redis/classifier healthy?
# 4. Quick restart
docker compose restart gateway
# 5. If still failing, check DB connectivity
docker compose exec gateway wget -qO- http://postgres:5432 || echo "DB unreachable"
# 6. If Redis is down, gateway can still serve (cache miss fallback)
# but loggerd cannot write to DB. Fix Redis first.
P1: 高レイテンシ(p95 > 2s)
# 1. Check upstream provider latency
docker compose logs gateway --tail=50 | grep "duration"
# 2. Check Redis latency
docker compose exec redis redis-cli --latency
# 3. Check DB connection pool
docker compose exec postgres psql -U yabanin -c \
"SELECT count(*), state FROM pg_stat_activity GROUP BY state;"
# 4. Check if classifier is slow (>100ms timeout)
docker compose logs gateway --tail=50 | grep "classifier"
# 5. Mitigation: disable classifier temporarily (fallback to rule-tier)
curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
http://localhost:8086/api/organizations/$ORG_ID/routing \
-d '{"routing_mode": "always_cheap"}'
P1: Classifier サービスの停止
# Gateway automatically falls back to rule-tier classifier (circuit breaker)
# Verify fallback is working:
docker compose logs gateway --tail=50 | grep "circuit.*open"
# Check classifier health
curl http://localhost:8080/health
# Restart classifier
docker compose restart classifier
# Verify recovery
docker compose logs gateway --tail=50 | grep "circuit.*closed"
P1: データベース接続の枯渇
# Check active connections
docker compose exec postgres psql -U yabanin -c \
"SELECT count(*), state, application_name FROM pg_stat_activity GROUP BY state, application_name;"
# If idle connections are high, restart services to release them
docker compose restart gateway admin
# Increase max_connections if needed
docker compose exec postgres psql -U yabanin -c "SHOW max_connections;"
# Edit postgresql.conf or set in docker-compose env
P2: Redis のメモリ不足
# Check memory usage
docker compose exec redis redis-cli INFO memory | grep used_memory_human
# Check evicted keys
docker compose exec redis redis-cli INFO stats | grep evicted_keys
# Flush cache if needed (will cause temporary cache miss spike)
docker compose exec redis redis-cli FLUSHDB
# Or flush specific patterns:
docker compose exec redis redis-cli --scan --pattern "cache:*" | xargs redis-cli DEL
P2: Loggerd の遅延(ストリームのバックログ)
# Check stream length
docker compose exec redis redis-cli XLEN events:queue
# Check consumer group lag
docker compose exec redis redis-cli XINFO GROUPS events:queue
# Scale loggerd
docker compose up -d --scale loggerd=3
# If backlog is huge, trim old messages
docker compose exec redis redis-cli XTRIM events:queue MAXLEN 100000