Skip to main content

Runbook: laksanakan pendirian awam (VPS tunggal)

Sasaran: satu VPS dengan RAM 4–8 GB yang mendedahkan pinggir awam (domain api / admin / papan pemuka) melalui deploy/docker-compose.prod.yml. Masa: ~30 minit. Berkaitan: docs/runbooks/production.md (operasi hari ke-2), docs/runbooks/alerts.md (penghantaran amaran), docs/runbooks/backup-restore-rehearsal.md (latih tubi DR).

0. Prasyarat​

  • VPS dengan RAM 4–8 GB, 2+ vCPU, cakera 40 GB, Docker Engine + pemalam docker compose. Profil real-models (pengelas/embedder/llama-server) memerlukan hujung atas julat itu; tanpa profil itu, tindanan menjalankan peringkat mock (lihat deploy/docker-compose.e2e.yml).

DNS: tiga rekod A → IP VPS:

  • API_DOMAIN (gerbang, API serasi OpenAI)
  • ADMIN_DOMAIN (konsol admin)
  • DASHBOARD_DOMAIN (SPA React)
  • Port 80/443 terbuka (Caddy mengeluarkan sijil Let's Encrypt pada permulaan pertama).
  • Repositori didaftar keluar di /opt/yabanin (laraskan laluan di bawah jika berbeza).

1. Rahsia (sekali, idempoten)​

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

Mencipta deploy/.env (daripada deploy/.env.example) dan deploy/secrets/ (pg_uri, session_key, cache_hmac, kms_local_key, metrics-bearer.key), semua mod 600. Kedua-dua laluan diabaikan oleh git — jangan sekali-kali komit atau salinnya keluar dari mesin tanpa penyulitan.

2. Konfigurasi deploy/.env​

vi deploy/.env

Diperlukan:

Pemboleh ubahMaksud
API_DOMAIN / ADMIN_DOMAIN / DASHBOARD_DOMAINnama hos awam (Caddy + domain kuki admin)
POSTGRES_PASSWORDdijana oleh init-secrets; jangan ubah selepas up pertama (pg_data mengekalkan yang lama)

Disyorkan sebelum didedahkan:

Pemboleh ubahMaksud
ALERT_WEBHOOK_URLwebhook pemilik (Slack/PagerDuty/operasi)
ALERT_TG_BOT_TOKENtoken bot Telegram pemilik (daripada @BotFather)
ALERT_TG_CHAT_IDid sembang pemilik (tulis kepada bot sekali, kemudian semak https://api.telegram.org/bot<token>/getUpdates)

Amaran Prometheus yang kritikal disebarkan ke kedua-dua saluran; yang tidak ditetapkan kekal pada sink lubang hitam pembangunan. Tembakan ujian: docs/runbooks/alerts.md.

3. Bina dan mulakan​

# 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 juga memulakan postgres/redis, tindanan keteramatan (prometheus, alertmanager, grafana), caddy (TLS), dashboard-web, serta sidecar sandaran dan halaman status.

4. Benih (organisasi + admin akar + kunci API pertama)​

Tambah pada deploy/.env (semua pilihan — SEED_ADMIN_EMAIL tidak ditetapkan = operasi kosong):

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

Lekapkan dua file rahsia tambahan dan jalankan tugas sekali:

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

Teks biasa kunci API yang dibenihkan dicetak sekali pada log kontena (docker compose logs seed). Larian kedua ialah operasi kosong yang idempoten dan TIDAK mencetaknya semula.

5. Ujian asap​

# 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

Penyiapan sembang (kunci sebenar daripada langkah benih):

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}'

Pengesahan had kadar (429)​

Pengehadan kadar dikuatkuasakan dalam aplikasi (lihat nota dalam deploy/caddy/Caddyfile.tmpl); sahkan zon yang paling ketat — log masuk admin, 5 percubaan / 15 min / IP:

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

Zon gerbang (50 permintaan/s/IP, letusan 100, Retry-After pada 429) memerlukan alat beban untuk dicetuskan: hey -n 300 -c 50 https://$API_DOMAIN/healthz.

6. Senarai semak selepas pelaksanaan​

  • Ketiga-tiga domain menyediakan TLS dengan sijil yang sah.
  • docker compose -f docker-compose.prod.yml ps — setiap perkhidmatan sihat (migrate/seed yang keluar 0 ialah tugas sekali yang dijangka).
  • Log masuk konsol admin berfungsi; organisasi dan kunci yang dibenihkan kelihatan.
  • Amaran ujian Telegram/webhook diterima (lihat docs/runbooks/alerts.md).
  • https://$API_DOMAIN/status.html menunjukkan semua perkhidmatan "ok".
  • Sandaran tiba: ls deploy/../ → lihat docs/runbooks/backup-restore-rehearsal.md; jadualkan latih tubi pemulihan suku tahunan.
  • Padam sebarang file rahsia sementara yang dicipta untuk pembenihan.