Incomex AI Portal
KB-54B6 rev 2

VPS Operating Rules — SSOT

7 min read Revision 2
ssotvpsrulesoperationssecurityenforcement

VPS Operating Rules — SSOT

Version: 1.0 Date: 2026-02-28 Status: Active Enforcement: Bắt buộc cho mọi Agent thao tác trên VPS

I. MỤC ĐÍCH

Tài liệu này quy định luật vận hành VPS — mọi AI Agent, CLI Agent, và người dùng PHẢI tuân thủ khi thao tác trên VPS production.

Bài học từ sự cố S-88: Codex không đọc Operating Rules SSOT → sửa trực tiếp VPS → gây mất kết nối AI agents → mất thời gian khôi phục.

II. LUẬT CƠ BẢN (BẮT BUỘC)

Luật 1: ĐỌC TRƯỚC KHI LÀM

Mọi Agent PHẢI đọc các tài liệu sau TRƯỚC KHI thao tác VPS:

  1. knowledge/dev/ssot/operating-rules.md (Nguyên tắc Điều hành)
  2. knowledge/dev/ssot/vps/vps-architecture.md (Kiến trúc VPS)
  3. knowledge/dev/ssot/vps/vps-operating-rules.md (tài liệu này)

Agent phải trích dẫn dòng cụ thể để chứng minh đã đọc.

Luật 2: KHÔNG SỬA TRỰC TIẾP TRÊN VPS

Mọi thay đổi config/code phải:

  1. Tạo branch trên GitHub
  2. Commit + Push + tạo PR
  3. CI green
  4. Review (Mũ 2)
  5. Merge
  6. Deploy qua CI/CD pipeline (rsync)

NGOẠI LỆ duy nhất: Khôi phục khẩn cấp (emergency restore) — phải báo cáo ngay sau đó + commit retroactively.

Luật 3: KHÔNG TẠO RESOURCE MỚI

  • KHÔNG tạo Service Account mới (GC-LAW §1.3)
  • KHÔNG tạo GCS bucket mới, Cloud Run service mới
  • KHÔNG thêm Docker container mới mà không có kế hoạch + phê duyệt trong SSOT
  • KHÔNG expose port mới ra public mà không qua Nginx

Luật 4: GITOPS LÀ NGUỒN SỰ THẬT

  • docker-compose.yml trên VPS PHẢI khớp với Git
  • nginx/conf.d/*.conf trên VPS PHẢI khớp với Git
  • .env trên VPS KHÔNG nằm trong Git (secrets) nhưng cấu trúc phải document trong SSOT
  • Bất kỳ drift nào giữa VPS và Git = vi phạm

Luật 5: VERIFY TRƯỚC KHI BÁO CÁO

  • HTTP 200 từ server ≠ hoạt động đúng cho end user
  • Agent phải test từ góc nhìn end user (browser URL, MCP tools, API call)
  • Verify checklist PHẢI bao gồm: tất cả domains accessible, MCP tools hoạt động, ops proxy hoạt động

III. QUY TRÌNH VẬN HÀNH

A. Deploy Changes

1. Branch → Code → Commit → Push → PR
2. CI green (GitHub Actions)
3. Mũ 2 Review
4. Merge (squash + delete branch)
5. CI deploy → rsync → VPS
6. Verify production (all domains + MCP + ops)

B. Docker Operations

Hành động Lệnh Khi nào
Restart service docker compose restart <service> Sau deploy
Rebuild service docker compose up -d --build <service> Khi code thay đổi
View logs docker compose logs -f <service> Debug
Full restart docker compose down && docker compose up -d Emergency only

CẢNH BÁO: docker compose down sẽ dừng TẤT CẢ services. Chỉ dùng khi cần thiết.

C. Backup Verification

Check Frequency Method
MySQL backup exists Weekly ls -la /opt/incomex/backups/mysql/
Qdrant backup exists Weekly ls -la /opt/incomex/backups/qdrant/
PostgreSQL backup exists Weekly ls -la /opt/workflow/postgres/backups/
GCS upload success Weekly gsutil ls gs://huyen1974-system-backups-shared/
Backup restore test Monthly Restore → verify → delete test

D. Monitoring

Check How Expected
All containers healthy docker ps 8 containers UP
Nginx curl -s https://vps.incomexsaigoncorp.vn 200
Directus curl -s https://directus.incomexsaigoncorp.vn/server/health OK
Agent Data curl -s https://vps.incomexsaigoncorp.vn/api/health healthy
Ops Proxy curl -s https://ops.incomexsaigoncorp.vn/items/tasks?limit=1 -H "X-API-Key: ..." 200
MCP connectivity /opt/incomex/scripts/test-mcp-connectivity.sh 5/5 PASS
Config integrity /opt/incomex/scripts/check-config-integrity.sh No drift

IV. BẢO MẬT

Quy tắc Secrets

  1. KHÔNG hardcode credentials trong code, scripts, hay docker-compose
  2. Secrets lấy từ Google Secret Manager hoặc .env file (chmod 600)
  3. .env KHÔNG commit vào Git
  4. Khi cần credentials mới → thêm vào Secret Manager → cập nhật .env

Quy tắc Access

  1. SSH: chỉ key auth, KHÔNG password
  2. Database ports: KHÔNG expose public
  3. Admin UIs (Directus, Uptime Kuma): qua authenticated endpoints only
  4. AI Agent access: qua API key (X-API-Key header) + Nginx filter

Nợ bảo mật cần xử lý

# Issue Priority Path
SEC-01 Plaintext creds in start-agent-data.sh — ✅ FALSE POSITIVE
SEC-02 World-readable .env — ✅ RESOLVED (chmod 600)
SEC-03 Hardcoded vars in backup scripts — ✅ RESOLVED (.env)
SEC-04 No Docker memory limits 🟡 Medium TD-039 Open
SEC-05 Port 3001 bypasses Nginx 🟡 Medium TD-040 Open

V. EMERGENCY PROCEDURES

Service Down

1. ssh contabo
2. docker ps                           # Xem container nào down
3. docker compose logs <service>       # Đọc error
4. docker compose restart <service>    # Restart đơn lẻ
5. Verify: curl domains               # Confirm recovery
6. Báo cáo root cause

Full System Down

1. ssh contabo
2. cd /opt/incomex/docker
3. docker compose down
4. docker compose up -d
5. Wait 60s for healthchecks
6. Verify tất cả domains + MCP + ops
7. Báo cáo + commit retroactive nếu có thay đổi

Config Drift Detected

1. check-config-integrity.sh báo FAIL
2. So sánh VPS file vs Git file
3. Nếu VPS sai → restore từ Git (rsync)
4. Nếu Git thiếu → commit VPS version vào Git
5. Cập nhật checksums

VI. CAPACITY PLANNING

Ngưỡng cảnh báo

Resource Warning Critical
CPU >70% sustained >90%
RAM >80% (9.6 GB) >90% (10.8 GB)
Disk >70% (67 GB) >85% (81 GB, auto-prune)

Service RAM Budget

Service Current Limit (đề xuất)
MySQL ~650 MB 1.5 GB
Agent Data ~511 MB 1 GB
PostgreSQL ~200 MB 2 GB
Directus ~152 MB 512 MB
Nuxt ~100 MB 512 MB
Qdrant ~100 MB 512 MB
Nginx ~50 MB 256 MB
Prefect (future) — 1 GB
Kestra (future) — 1 GB
Total budget ~1.8 GB ~8.8 GB / 12 GB

VII. CHANGELOG

Date Version Change
2026-02-28 1.0 Initial creation từ audit + infrastructure docs