Runbook pengeluaran Yabanin
Gambaran keseluruhan seni bina
┌─────────────────────────────────────────┐
│ 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 │
└──────────────┘
Perkhidmatan
| Perkhidmatan | Port | Tujuan | Semakan kesihatan |
|---|---|---|---|
| Gerbang | 8082 | Proxy API utama (serasi OpenAI) | GET /healthz |
| Admin | 8086 | Panel pentadbir + API REST | GET /health |
| Loggerd | 8085 | Penulis strim Redis → PostgreSQL | GET /healthz |
| PostgreSQL | 5432 | Pangkalan data utama (pgvector) | pg_isready |
| Redis | 6379 | Cache + strim peristiwa | redis-cli ping |
| Pengelas | 8080 | Kerumitan tugas ML (bge-small) | GET /health |
| Pembenam BGE | 6006 | Perkhidmatan pembenaman untuk cache semantik | GET /health |
| Papan pemuka | 3000 | Papan pemuka analitik kos React | HTTP 200 |
Pelaksanaan
Pelaksanaan awal
# 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
Mengemas kini perkhidmatan
# Rebuild and restart a single service
docker compose up -d --build gateway
# Zero-downtime rolling restart (for config-only changes)
docker compose restart gateway
Gulung balik
# 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
Pemboleh ubah persekitaran
Gerbang
| Pemboleh ubah | Diperlukan | Perihalan |
|---|---|---|
YABANIN_GATEWAY_LISTEN | Ya | Alamat dengar (:8082) |
YABANIN_PG_URI_FILE | Ya | Laluan ke rahsia rentetan sambungan PG |
YABANIN_REDIS_ADDR | Ya | Alamat Redis (redis:6379) |
YABANIN_EVENT_STREAM | Ya | Nama strim Redis (events:queue) |
YABANIN_CACHE_HMAC_SECRET_FILE | Ya | Laluan ke rahsia penandatanganan HMAC |
YABANIN_EMBEDDER_BASE_URL | Tidak | URL perkhidmatan pembenam |
YABANIN_EMBEDDER_ENABLED | Tidak | Dayakan cache semantik (true/false) |
Admin
| Pemboleh ubah | Diperlukan | Perihalan |
|---|---|---|
YABANIN_PG_URI_FILE | Ya | Laluan ke rentetan sambungan PG |
YABANIN_SESSION_KEY_FILE | Ya | Laluan ke kunci penandatanganan sesi |
YABANIN_ADMIN_LISTEN | Ya | Alamat dengar (:8086) |
YABANIN_ADMIN_DOMAIN | Ya | Domain untuk kuki (localhost) |
YABANIN_ADMIN_API_KEY | Tidak | Mendayakan API perkhidmatan /internal baca sahaja (lihat di bawah) |
Admin: API perkhidmatan dalaman
- Dilumpuhkan secara lalai: tanpa
YABANIN_ADMIN_API_KEYtiada permukaan/internalyang berdiri sendiri. - Endpoint:
GET /internal/api-keys?org_id=<id>&page=1&page_size=50,GET /internal/analytics/savings?org_id=<id>&days=7. - Pengesahan: semakan pengepala masa malar; hantar kunci sebagai
X-Admin-Key: <value>(trcli menggunakan--api-key). - Baca sahaja + berskop organisasi: kedua-dua laluan memerlukan
org_iddan tidak mendedahkan operasi mutasi.
Penskalaan
Menegak (tambah CPU/memori)
# In docker-compose.yml, under deploy.resources:
deploy:
resources:
limits:
memory: 512M # was 256M
cpus: "2.0" # was 1.0
Mendatar (tambah replika)
Gerbang dan loggerd tidak berkeadaan — selamat untuk diskalakan secara mendatar:
docker compose up -d --scale gateway=3 --scale loggerd=2
Letakkan pengimbang beban (nginx/HAProxy) di hadapan replika gerbang.
Penskalaan Redis
- Replika baca: Tambah replika Redis untuk beban kerja yang berat pada bacaan (carian cache)
- Memori: Pantau
used_memory— tingkatkan had memori kontena sebelum OOM - Persistensi:
appendonly yesdidayakan untuk ketahanan; pantau kekerapan tulis semula AOF
Penskalaan PostgreSQL
- Pengumpulan sambungan: Gunakan PgBouncer jika sambungan gerbang melebihi
max_connections - pgvector: Pantau saiz indeks HNSW — indeks semula jika kependaman kueri merosot
- Replika baca: Tambah untuk kueri analitik/papan pemuka (perkhidmatan admin)
Tindak balas insiden
P0: Gerbang terhenti (semua permintaan gagal)
# 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: Kependaman tinggi (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: Perkhidmatan pengelas terhenti
# 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: Sambungan pangkalan data habis
# 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: Memori Redis penuh
# 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 ketinggalan (tunggakan strim)
# 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
Pemantauan
Metrik utama (Prometheus pada :2112)
| Metrik | Ambang amaran |
|---|---|
http_request_duration_seconds{quantile="0.95"} | > 2s selama 5m |
cache_hits_total{type="miss"} kadar | > 80% selama 15m |
circuit_breaker_state | 1 (terbuka) selama 5m |
redis_stream_length | > 10,000 |
pg_connections_active | > 80% daripada maksimum |
Papan pemuka Grafana
Tersedia di deploy/grafana/dashboards/ — import melalui UI Grafana.
Panel utama:
- Isipadu permintaan + persentil kependaman
- Kadar hit cache (tepat lwn semantik lwn miss)
- Taburan pengelas (mudah/sederhana/sukar)
- Penjimatan kos (sebenar lwn kontrafaktual)
- Kadar ralat huluan mengikut penyedia
Kaveat pemberitahuan (baca ini)
deploy/alertmanager/alertmanager.yml dihantar dengan penerima yang dibiarkan sebagai komen (SMTP/Slack/PagerDuty ialah pemegang tempat TODO). Sehingga penerima/webhook sebenar dikonfigurasi, TIADA amaran akan dihantar kepada sesiapa — Alertmanager akan menilai peraturan dan menghalakannya ke penerima log file sahaja. Sambungkan sekurang-kurangnya satu penerima sebenar sebelum bergantung pada pemberitahuan dalam pengeluaran.
Kaveat pendedahan metrik
metrics_enabled: true menyajikan /metrics pada pendengar admin (:9090). Secara lalai tiada pengesahan — tolak ansur yang disengajakan supaya Prometheus boleh mengikisnya. Tetapkan metrics_bearer_key (persekitaran YABANIN_METRICS_BEARER_KEY) untuk memerlukan Authorization: Bearer <key> sebaliknya; ambil perhatian semakan hanya pada token bearer, tanpa sekatan localhost, kerana pengikis biasanya berada dalam pod/hos lain. Utamakan kunci apabila port admin tidak dapat disekat sepenuhnya pada rangkaian. Metrik membawa nama model, id organisasi, dan isipadu trafik setiap laluan, iaitu data operasi yang anda mungkin tidak mahu didedahkan kepada segmen yang mencapai port itu. Dalam pengeluaran, sekat pada aras rangkaian: NetworkPolicy Kubernetes atau peraturan firewall yang terhad kepada pod/julat metrik Prometheus kluster, dan JANGAN terbitkan port admin pada hos dalam pelaksanaan compose. Kekalkan pengikisan di dalam kluster (PodMonitor / ServiceMonitor), jangan sekali-kali dari luarnya.
pprof berpagar
Apabila debug_pprof: true, pendengar admin gerbang mendedahkan lima profil — /debug/pprof/ (indeks), cmdline, profile, symbol, trace — semuanya di sebalik pagar yang sama seperti /debug/vars: pemanggil localhost sahaja dengan Authorization: Bearer <YABANIN_API_KEY>. Tangkap profil CPU 30s:
curl -H "Authorization: Bearer $YABANIN_API_KEY"
"http://127.0.0.1:9090/debug/pprof/profile?seconds=30" -o cpu.pprof go tool pprof cpu.pprof
Endpoint profil bernama (goroutine, heap, block, mutex, threadcreate) sengaja TIDAK didedahkan pada pendengar admin; gunakan halaman indeks untuk memilih apa yang tersedia, dan ambil data heap/goroutine daripada dump SIGQUIT atau sidecar jika perlu. Setiap penolakan mengembalikan 403 tanpa surih tindanan (kedua-dua pemanggil bukan localhost dan token bearer yang tidak sah).
Sandaran dan pemulihan
Sandaran pangkalan data
# Full backup (run daily via cron)
docker compose exec postgres pg_dump -U yabanin yabanin | gzip > backup_$(date +%Y%m%d).sql.gz
# Restore
gunzip -c backup_20260723.sql.gz | docker compose exec -T postgres psql -U yabanin yabanin
Sandaran Redis
# AOF persistence is enabled (appendonly yes)
# Manual snapshot:
docker compose exec redis redis-cli BGSAVE
# Copy dump.rdb from volume
docker compose cp redis:/data/dump.rdb ./redis_backup_$(date +%Y%m%d).rdb
Sandaran titik semak model
# Classifier checkpoint
cp artifacts/classifier-v1.pt backups/classifier-v1-$(date +%Y%m%d).pt
Sandaran sumber (git bundle)
# Local bundle of ALL branches + tags into .backups/ (default retention: last 5)
make backup
# Options: BACKUP_DIR=/other/path RETAIN=10 make backup
# Restore/clone from a bundle:
git clone .backups/yabanin-<stamp>.bundle
Tiada remote atau kelayakan digunakan; bundle diabaikan oleh git (.backups/). Salin bundle ke luar mesin (cth. ke storan yang disulitkan) untuk mendapat sandaran sebenar di luar mesin.
Operasi biasa
Tambah organisasi baharu
curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
http://localhost:8086/api/organizations \
-d '{"name": "Acme Corp", "slug": "acme"}'
Putar kunci API
curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
http://localhost:8086/api/api-keys/{id}/rotate
Konfigurasikan amaran perbelanjaan
curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
http://localhost:8086/api/organizations/{id}/spend-alert \
-d '{"threshold_usd": 100.0, "webhook_url": "https://hooks.slack.com/..."}'
Tetapkan bajet pasukan
curl -X PUT -H "Authorization: Bearer $ADMIN_TOKEN" \
http://localhost:8086/api/teams/{team_id}/budget \
-d '{"monthly_limit_usd": 500.0, "hard_limit": true}'
Latih semula pengelas
# 1. Generate new dataset
docker run --rm -v $(pwd)/datasets:/app/datasets yabanin-train \
python scripts/build_dataset.py --output /app/datasets/classifier/
# 2. Train
docker run --rm \
-v $(pwd)/datasets:/app/datasets \
-v $(pwd)/artifacts:/output \
yabanin-train \
--train /app/datasets/classifier/prompts_train.jsonl \
--test /app/datasets/classifier/prompts_test.jsonl \
--output /output/classifier-v2.pt \
--epochs 5
# 3. Evaluate
docker run --rm --entrypoint python \
-v $(pwd)/artifacts:/app/artifacts \
-v $(pwd)/datasets:/app/datasets \
-v $(pwd)/scripts:/app/scripts \
yabanin-train \
/app/scripts/evaluate_classifier.py \
--checkpoint /app/artifacts/classifier-v2.pt
# 4. Deploy new model
docker compose build classifier
docker compose up -d classifier
Rujukan pantas bertugas
| Simptom | Tindakan pertama | Eskalasi jika |
|---|---|---|
| Ralat 5xx melonjak | Semak log gerbang, mulakan semula jika perlu | Berterusan >5 min |
| Kependaman p95 > 2s | Semak kependaman huluan + Redis | Berterusan >10 min |
| Kadar hit cache < 25% | Lihat runbook cache | Berterusan >30 min |
| Ralat pengelas | Sandaran automatik pemutus litar | Semua pengelas terhenti |
| Penolakan bajet melonjak | Semak sama ada had tersalah konfigurasi | Organisasi terkunci keluar |
| Cakera DB penuh | Vacuum + arkibkan log lama | < 10% ruang bebas |
| Redis OOM | Kosongkan cache + tambah memori | Berulang |