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. Profilreal-models(pengelas/embedder/llama-server) memerlukan hujung atas julat itu; tanpa profil itu, tindanan menjalankan peringkat mock (lihatdeploy/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 ubah | Maksud |
|---|---|
API_DOMAIN / ADMIN_DOMAIN / DASHBOARD_DOMAIN | nama hos awam (Caddy + domain kuki admin) |
POSTGRES_PASSWORD | dijana oleh init-secrets; jangan ubah selepas up pertama (pg_data mengekalkan yang lama) |
Disyorkan sebelum didedahkan:
| Pemboleh ubah | Maksud |
|---|---|
ALERT_WEBHOOK_URL | webhook pemilik (Slack/PagerDuty/operasi) |
ALERT_TG_BOT_TOKEN | token bot Telegram pemilik (daripada @BotFather) |
ALERT_TG_CHAT_ID | id 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/seedyang 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.htmlmenunjukkan semua perkhidmatan "ok".- Sandaran tiba:
ls deploy/../→ lihatdocs/runbooks/backup-restore-rehearsal.md; jadualkan latih tubi pemulihan suku tahunan. - Padam sebarang file rahsia sementara yang dicipta untuk pembenihan.