Skip to main content

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​

PerkhidmatanPortTujuanSemakan kesihatan
Gerbang8082Proxy API utama (serasi OpenAI)GET /healthz
Admin8086Panel pentadbir + API RESTGET /health
Loggerd8085Penulis strim Redis → PostgreSQLGET /healthz
PostgreSQL5432Pangkalan data utama (pgvector)pg_isready
Redis6379Cache + strim peristiwaredis-cli ping
Pengelas8080Kerumitan tugas ML (bge-small)GET /health
Pembenam BGE6006Perkhidmatan pembenaman untuk cache semantikGET /health
Papan pemuka3000Papan pemuka analitik kos ReactHTTP 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 ubahDiperlukanPerihalan
YABANIN_GATEWAY_LISTENYaAlamat dengar (:8082)
YABANIN_PG_URI_FILEYaLaluan ke rahsia rentetan sambungan PG
YABANIN_REDIS_ADDRYaAlamat Redis (redis:6379)
YABANIN_EVENT_STREAMYaNama strim Redis (events:queue)
YABANIN_CACHE_HMAC_SECRET_FILEYaLaluan ke rahsia penandatanganan HMAC
YABANIN_EMBEDDER_BASE_URLTidakURL perkhidmatan pembenam
YABANIN_EMBEDDER_ENABLEDTidakDayakan cache semantik (true/false)

Admin​

Pemboleh ubahDiperlukanPerihalan
YABANIN_PG_URI_FILEYaLaluan ke rentetan sambungan PG
YABANIN_SESSION_KEY_FILEYaLaluan ke kunci penandatanganan sesi
YABANIN_ADMIN_LISTENYaAlamat dengar (:8086)
YABANIN_ADMIN_DOMAINYaDomain untuk kuki (localhost)
YABANIN_ADMIN_API_KEYTidakMendayakan API perkhidmatan /internal baca sahaja (lihat di bawah)

Admin: API perkhidmatan dalaman​

  • Dilumpuhkan secara lalai: tanpa YABANIN_ADMIN_API_KEY tiada permukaan /internal yang 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_id dan 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 yes didayakan 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)​

MetrikAmbang amaran
http_request_duration_seconds{quantile="0.95"}> 2s selama 5m
cache_hits_total{type="miss"} kadar> 80% selama 15m
circuit_breaker_state1 (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​

SimptomTindakan pertamaEskalasi jika
Ralat 5xx melonjakSemak log gerbang, mulakan semula jika perluBerterusan >5 min
Kependaman p95 > 2sSemak kependaman huluan + RedisBerterusan >10 min
Kadar hit cache < 25%Lihat runbook cacheBerterusan >30 min
Ralat pengelasSandaran automatik pemutus litarSemua pengelas terhenti
Penolakan bajet melonjakSemak sama ada had tersalah konfigurasiOrganisasi terkunci keluar
Cakera DB penuhVacuum + arkibkan log lama< 10% ruang bebas
Redis OOMKosongkan cache + tambah memoriBerulang