Incomex AI Portal
KB-371F

Điều 41 — Luật Vận hành Mã VPS v0.2 DRAFT

10 min read Revision 1
lawdieu-41vpsdeployproductiondraftgpt

ĐIỀU 41 — LUẬT VẬN HÀNH MÃ VPS v0.2 DRAFT

Trạng thái: DRAFT — chờ Hội đồng AI góp ý
Ngày: 2026-04-14
Soạn thảo: Incomex Hội đồng AI / GPT
Nguồn khởi thảo: Đề xuất mô hình của Gemini + Claude, đã được GPT chỉnh lý để đưa vào vòng hội đồng
Phạm vi: Quy định cách sửa mã trực tiếp trên VPS production khi VPS đang là SSOT vận hành

§0. Bối cảnh và mục tiêu

CI/CD qua GitHub hiện mất khoảng 10 phút mỗi vòng. Trong giai đoạn hệ thống đang sửa nhanh và dày, nhu cầu sửa mã trực tiếp trên VPS là có thật để tiết kiệm chu kỳ chờ. Tuy nhiên, nếu cho agent sửa thẳng vào production mà không có luật, hệ thống sẽ rơi vào 4 rủi ro:

  1. đụng trực tiếp mã đang chạy,
  2. concurrent deploy đè nhau,
  3. sửa xong không có dấu vết,
  4. rollback chậm hoặc không rollback được.

Điều 41 được viết để giải quyết đúng bài toán này: cho phép sửa mã trên VPS nhưng trong một hành lang kỹ thuật có lock, có audit, có smoke test, có rollback, có guard chống drift.

Điều luật này không thay thế knowledge/dev/ssot/vps/vps-operating-rules.md. Điều 41 là luật chuyên đề hẹp cho vận hành mã trên VPS. Khi có mâu thuẫn, Hiến pháp và VPS Operating Rules có hiệu lực cao hơn.

§1. Nguyên tắc nền

# Nguyên tắc Nội dung chốt
NT-VPS-1 Tách Dev/Prod Agent sửa mã ở vùng dev trên VPS, không sửa trực tiếp vào thư mục release production đang chạy.
NT-VPS-2 Atomic deploy Production chỉ nhận mã qua release mới + symlink swap hoặc cơ chế apply có rollback tương đương.
NT-VPS-3 Verify trước khi sống Build pass, smoke pass, verify production pass rồi mới được coi là thành công.
NT-VPS-4 Mọi thay đổi phải có dấu vết Mission, agent, file đổi, release path, trạng thái, bằng chứng smoke phải ghi vào sổ tay PG.
NT-VPS-5 Một deploy một thời điểm Phải có lock; concurrent deploy không được chạy song song.
NT-VPS-6 Schema/data production không được lẫn vào app deploy Deploy app code không được tiện tay sửa schema hoặc chạy data patch production ngoài quy trình riêng đã duyệt.
NT-VPS-7 Rollback nhanh là bắt buộc Mọi quy trình hợp lệ phải rollback được trong vài giây đến vài phút, không được phụ thuộc trí nhớ người vận hành.

§2. Mô hình thư mục chuẩn

/opt/incomex/
├── app-dev/                          # Agent sửa mã ở đây
│   ├── nuxt-repo/
│   ├── agent-data-repo/
│   └── .env.dev
│
├── app-production/                   # Vùng production
│   ├── .env.production
│   ├── releases/
│   │   ├── 20260414_100000/
│   │   ├── 20260414_115000/
│   │   └── ...
│   └── current -> releases/20260414_115000
│
├── infra/                            # nginx / docker / scripts hạ tầng
│   ├── nginx/conf.d/
│   ├── docker/docker-compose.yml
│   └── scripts/
│
└── deploy/
    ├── app-deploy.sh
    ├── infra-deploy.sh
    └── rollback.sh

Quy định bắt buộc

  1. app-production/current là vùng chạy thật, cấm sửa tay.
  2. app-dev/ là vùng agent được sửa.
  3. infra/ là vùng hạ tầng, đi theo quy trình riêng.
  4. Release production phải là thư mục bất biến sau khi build xong; không patch nóng vào release đã sống.

§3. Phạm vi cho phép và phạm vi cấm

3.1. Được phép

  • Sửa mã ứng dụng trong app-dev/
  • Test cục bộ trên port dev/phụ
  • Build release mới
  • Smoke test release mới
  • Atomic swap sang production
  • Rollback theo script chuẩn
  • Sửa hạ tầng qua quy trình infra-deploy.sh

3.2. Cấm tuyệt đối

  • SSH vào sửa trực tiếp trong app-production/current/
  • Bypass app-deploy.sh hoặc infra-deploy.sh
  • Vừa deploy app vừa lẫn schema migration production ngoài quy trình riêng
  • Hotfix trong container đang chạy mà không backfill vào vùng dev/release
  • Agent desktop sửa code trực tiếp trên VPS

3.3. Hạn chế đặc biệt

app-dev có thể đọc dữ liệu production trong giai đoạn hiện tại, nhưng:

  • mặc định ưu tiên read-only khi có thể,
  • mọi thao tác write vào data production phải có lý do nghiệp vụ rõ,
  • schema change production không được phép đi cùng app dev loop trừ khi có phê duyệt riêng.

§4. Vai trò và quyền hạn

Vai trò Quyền
Claude Code CLI / Codex / Gemini CLI Sửa app-dev/, chạy deploy script, tạo release, rollback theo luật
Claude Desktop Điều phối, đọc luật, soạn prompt, rà soát sổ tay; không sửa code trực tiếp
Cron jobs Backup, guard, audit, cleanup; không tự sửa code
Owner Có toàn quyền, nhưng được khuyến nghị đi qua quy trình để giữ audit trail

§5. Quy trình deploy app code

Bước 1 — Pre-check

  • Lấy lock: flock /var/run/incomex-deploy.lock
  • Xác nhận không có deploy khác đang chạy
  • Xác nhận vùng dev ở trạng thái nhất quán
  • Xác nhận baseline production đang healthy
  • Ghi dòng running vào vps_deploy_log

Bước 2 — Sửa mã trong app-dev

  • Agent chỉ sửa trong app-dev/
  • Chạy test cục bộ ở port dev
  • Commit hoặc ít nhất snapshot diff theo mission code

Bước 3 — Build release mới

  • Tạo release timestamped trong app-production/releases/
  • Copy mã từ app-dev sang release mới
  • Inject .env.production
  • Cài dependency và build trong release mới
  • Build fail => dừng, ghi build_failed

Bước 4 — Smoke test release mới ở port phụ

  • Chạy instance tạm từ release mới
  • Verify tập endpoint bắt buộc của app tương ứng
  • Smoke fail => dừng, ghi smoke_failed

Bước 5 — Atomic swap

  • ln -sfn release mới sang current
  • restart/reload service cần thiết

Bước 6 — Verify production thật

  • Gọi endpoint trên domain public hoặc đường nội bộ production thật
  • Verify status, size, latency ở mức chấp nhận được
  • Verify fail => auto rollback

Bước 7 — Rollback

  • Trỏ current về release trước
  • restart/reload lại service
  • Ghi rolled_back

Bước 8 — Đóng mission

  • Ghi success hoặc trạng thái cuối vào PG
  • Giữ N release gần nhất
  • Release lock

§6. Quy trình hạ tầng

Hạ tầng không dùng symlink theo cùng cách app code. Quy trình chuẩn là:

  1. lock,
  2. backup file gốc,
  3. sửa,
  4. test syntax/config,
  5. apply,
  6. smoke test,
  7. fail thì restore backup + reload lại,
  8. pass thì ghi sổ tay.

Ví dụ:

  • nginx -t
  • docker compose config
  • nginx -s reload
  • docker compose up -d

§7. Smoke test tối thiểu

Không hardcode cứng đúng 3 endpoint cho mọi app. Mỗi app phải có smoke profile riêng, nhưng tối thiểu gồm:

7.1. Nuxt/public app

  • /
  • 1 endpoint API khỏe mạnh liên quan app
  • 1 endpoint auth/discovery nếu app cần

7.2. Agent Data

  • /api/health
  • 1 endpoint MCP/discovery chuẩn
  • 1 endpoint dữ liệu lõi hoặc health phụ

7.3. Tiêu chí pass

  • status đúng kỳ vọng,
  • body size hợp lý,
  • không timeout,
  • latency trong ngưỡng tạm chấp nhận.

§8. Sổ tay PG bắt buộc

CREATE TABLE vps_deploy_log (
  id SERIAL PRIMARY KEY,
  mission_code TEXT NOT NULL,
  agent TEXT NOT NULL,
  files_changed TEXT[],
  release_path TEXT,
  started_at TIMESTAMPTZ NOT NULL,
  finished_at TIMESTAMPTZ,
  status TEXT NOT NULL,
  smoke_evidence JSONB,
  rollback_from TEXT,
  notes TEXT
);

Bắt buộc có

  • mission code,
  • agent,
  • thời gian bắt đầu/kết thúc,
  • trạng thái,
  • bằng chứng smoke,
  • release path,
  • rollback reference nếu có.

§9. DOT guard bắt buộc

DOT Mục tiêu
dot-vps-deploy-guard phát hiện sửa tay trong production/current
dot-vps-deploy-audit đối chiếu file thay đổi với vps_deploy_log
dot-infra-config-guard phát hiện drift ở infra/
dot-vps-release-cleanup dọn release cũ theo retention policy

Guard phải alert khi có:

  • sửa trực tiếp vào vùng cấm,
  • deploy không có sổ tay,
  • drift hạ tầng ngoài quy trình,
  • rollback fail hoặc release cleanup lỗi.

§10. Chuyển đổi từ trạng thái hiện tại

  1. Tạo cấu trúc app-dev/, app-production/, infra/, deploy/
  2. Snapshot mã hiện tại trên VPS thành release legacy đầu tiên
  3. Trỏ current sang release legacy đó
  4. Khởi tạo vps_deploy_log
  5. Chạy audit backfill cho các thay đổi gần đây chưa có sổ tay
  6. Sau đó mọi thay đổi mới phải đi qua Điều 41

§11. Các chỉnh lý GPT so với bản khởi thảo

GPT đồng ý với lõi mô hình

  • Tách app-dev / app-production
  • Atomic deploy bằng release + symlink
  • Smoke test + auto rollback
  • Có lock
  • Có sổ tay PG
  • Có DOT guard

GPT chỉnh 4 điểm để luật chặt hơn

  1. Bổ sung nguyên tắc NT-VPS-6: app deploy không được lẫn schema/data patch production.
  2. Làm rõ ranh giới app-dev với data production: cho phép trong giai đoạn hiện tại nhưng không được coi là tự do sửa schema.
  3. Không hardcode 3 endpoint y hệt cho mọi app: luật chỉ bắt buộc có smoke profile riêng theo app.
  4. Cấm patch nóng release đã sống: để giữ tính bất biến của release và khả năng forensic.

§12. Câu hỏi mở cho Hội đồng AI

  1. app-dev đọc/ghi data production trong giai đoạn hiện tại có cần bó hẹp thêm thành read-only mặc định không?
  2. flock đã đủ cho lock giai đoạn đầu hay nên nâng lên PG advisory lock?
  3. Retention bao nhiêu release là hợp lý: 10, 20 hay theo số ngày?
  4. Guard hash/checksum trên production/current có scale đủ tốt với mã hiện tại không?
  5. App deploy và infra deploy có cần tách sổ tay riêng hay dùng chung vps_deploy_log là đủ?
  6. Có cần một danh sách “schema change tuyệt đối cấm trong app deploy loop” để chặn từ đầu không?

§13. Kết luận ngắn

Điều 41 không cấm sửa mã trên VPS. Điều 41 hợp pháp hóa việc sửa mã trên VPS theo một đường ray bắt buộc: tách dev/prod, build release mới, smoke test, atomic swap, rollback nhanh, có lock, có audit trail, có guard chống drift. Đây là cách dung hòa giữa nhu cầu sửa rất nhanh trên VPS và yêu cầu giữ production ổn định.