Self-hosting Miracle Network

Miracle Network có thể chạy trên hạ tầng của bạn (VPS, bare metal, hoặc Kubernetes) thay vì chỉ dùng cloud hosted. Bài viết này là tổng quan guest-safe cho admin và DevOps — không chứa hostname nội bộ, credential, hay lệnh copy-paste nguy hiểm. Chi tiết vận hành đầy đủ nằm trong runbook ops (tier B) sau khi bạn ký entitlement enterprise.

Khi nào nên self-host?

Self-host phù hợp khi:

Dữ liệu phải nằm trong biên giới pháp lý (VN on-prem, air-gap một phần)
Bạn cần tích hợp mạng nội bộ (LDAP, ERP, hệ thống chứng khoán)
Team đã có kinh nghiệm vận hành Postgres, Redis, reverse proxy

Self-host không bắt buộc để dùng Miracle Network — nhiều khách bắt đầu trên SaaS staging/production hosted rồi migrate sau.

Kiến trúc tham chiếu (logical)

Internet / VPN
    │
    ▼
 Reverse proxy (TLS termination)
    │
    ├── Web (Next.js) ──► API (Node)
    │                         │
    │                         ├── Postgres (main + commerce + …)
    │                         └── Redis (cache / queue)
    │
    └── Worker / cron jobs

Các unit có thể tách deploy (web, api, worker) để giảm blast radius — xem deploy units matrix trong tài liệu admin. n8n và OpenClaw thường là L4 adapter tách container, không nhét vào cùng process API.

Môi trường tối thiểu

Thành phần	Ghi chú
Postgres 14+	DB riêng per domain (main, commerce, dcg) — không gộp schema tùy tiện
Redis	Session/cache; bắt buộc nếu scale ngang API
Node 20+ / pnpm	Build web + api từ monorepo staging mirror
Object storage	FS driver hoặc S3-compatible cho media

Staging luôn trước production: domain staging, database suffix _staging, deploy script riêng — không thử nghiệm migration trực tiếp trên prod.

Quy trình triển khai khuyến nghị

Clone mirror staging — repo miraclenetwork-staging là SSOT code; production promote qua pipeline đã audit
Preflight — script preflight kiểm tra env, DB name, domain không lẫn prod
Deploy selective — chỉ --app web hoặc --app api khi hotfix; full deploy khi đổi cross-cutting
Smoke — health /api/v1/health, login flow, một workflow critical
Backup — snapshot DB + object storage trước migration lớn

Không dùng script deploy lạ ngoài SSOT — mỗi môi trường có một entrypoint duy nhất để tránh drift.

Biến môi trường và secret

Mọi secret qua file env hoặc secret manager — không commit vào git:

JWT_SECRET, DATABASE_URL, key LLM, webhook HMAC
Quyền file env 600, owner service account
Rotate định kỳ; ghi change record không kèm giá trị plaintext

Public docs (tier A) không mirror nội dung ops tier B. Admin đọc /dashboard/ops/docs với RBAC.

Database và migration

Prisma migrate hoặc db push tùy môi trường bootstrap — không migrate deploy lên DB trống không kiểm soát
Không cross-DB transaction (G3 constitution)
IAM user UUID chỉ ở main DB (G2)

Sau restore DR: chạy verify migrate status trước khi mở traffic.

AI / LLM self-host

Nhiều triển khai gắn Ollama hoặc gateway LLM nội bộ:

Cấu hình URL inference qua env — không hardcode IP public trong repo
Model registry YAML SSOT — pin tag model dài hạn cho reproducibility
Failover sang cloud provider chỉ khi policy cho phép

Companion RAG (docs.ask) dùng corpus help_docs riêng — không tự động ingest full ops markdown.

Observability

Tối thiểu cần:

Log structured JSON + request id
Metric health pod/process
Alert disk, DB connection, 5xx rate

Không log body request có PII hoặc token. Audit authz fail ở mức warn.

Backup và DR

Backup DB scheduled + test restore hàng quý
Encryption key backup không quote trong chat support
Runbook DR nằm tier B — drill trên DB throwaway trước prod

Bảo mật edge

TLS 1.2+; HSTS trên domain public
Rate limit login và webhook
CSP strict trên web — tránh inline script không kiểm soát
Không expose admin API ra internet không IP allowlist

Hub tài liệu sau self-host

Nhu cầu	Nơi đọc
Onboarding user	`/docs/getting-started` (tier A)
Agent AI	`/docs/first-ai-agent`
Ops nội bộ	Dashboard ops docs (RBAC)
Deploy k3s / nginx	Runbook admin (tier B)

Checklist trước go-live

Staging pass preflight + smoke E2E critical
Secret scan pass trên repo và content docs
RBAC admin tách user vận hành
Backup restore test ghi nhận
Domain prod ≠ staging; DB prod không suffix _staging
Incident contact và escalation rõ

Hỗ trợ

Self-host enterprise thường đi kèm entitlement support riêng. Trong lúc pilot, dùng /support hoặc Hỏi AI cho câu hỏi onboarding — câu hỏi sâu về nginx/k3s sẽ được chuyển tới kênh ops có NDA.

Đọc tiếp: Bắt đầu nhanh · Tạo AI agent đầu tiên