Incomex AI Portal
KB-371E

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

13 min read Revision 1
lawdieu-41vpsdeployproductiondraftgpt

ĐIỀU 41 — LUẬT VẬN HÀNH MÃ VPS v0.3 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ý thêm theo bối cảnh một VPS duy nhất dùng chung code + production data
Phạm vi: Quy định cách sửa mã trực tiếp trên VPS khi VPS đang là SSOT vận hành và hiện chưa tách riêng dev/prod thành 2 VPS độc lập

§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ờ. Đồng thời, hiện chỉ có một VPS duy nhất, nên chưa thể tách:

  • một VPS chỉ để dev/sửa mã,
  • và một VPS chỉ để production.

Vì vậy, hệ thống tạm chấp nhận mô hình một VPS dùng chung cho cả code và production data. Agent cần có quyền thao tác đủ mạnh để sửa và deploy nhanh trên VPS này. Tuy nhiên, nếu cho agent sửa trực tiếp mà không có luật, hệ thống sẽ rơi vào 5 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,
  5. thao tác app code vô tình làm hỏng data/schema production.

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

Định hướng tương lai

Khi bắt đầu có khách hàng thật hoặc volume data đủ lớn, mô hình mục tiêu sẽ là:

  • VPS-A: dev/build/repair
  • VPS-B: production runtime

Điều 41 v0.3 là luật cho giai đoạn chuyển tiếp một VPS; không mặc định coi đây là mô hình dài hạn tối ưu.

Đ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 trong bối cảnh đặc biệt hiện nay. 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 Một VPS nhưng vẫn phải tách vùng Dù chỉ có một VPS, vẫn phải tách vùng sửa mã (app-dev) và vùng chạy thật (app-production/current).
NT-VPS-2 Agent được quyền sửa trên VPS nhưng không được sửa bừa Quyền đủ mạnh là cần thiết, nhưng mọi thay đổi phải đi qua quy trình có lock, audit, verify và rollback.
NT-VPS-3 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-4 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-5 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-6 Một deploy một thời điểm Phải có lock; concurrent deploy không được chạy song song.
NT-VPS-7 Data production là thật, schema production là vùng nhạy cảm Trong giai đoạn một VPS, app-dev có thể phải đọc/ghi data thật; nhưng schema/data patch production không được trộn tự phát vào vòng app deploy thường ngày.
NT-VPS-8 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
  • Trong giai đoạn hiện tại, app-dev được phép chạm vào production data nếu nhiệm vụ đòi hỏi và không có môi trường tách riêng

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
  • 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
  • Tự ý trộn migration/schema patch vào app deploy loop mà không khai báo rõ nhiệm vụ đó là thay đổi production data/schema

3.3. Hạn chế đặc biệt cho giai đoạn một VPS

Do chỉ có một DB thật, luật này chấp nhận việc app-dev có thể đọc/ghi vào DB production. Tuy nhiên phải phân biệt rõ 3 loại thao tác:

Loại A — App code change thông thường

  • sửa mã,
  • build,
  • deploy,
  • verify.

Được phép theo quy trình §5.

Loại B — Data patch nghiệp vụ nhỏ, có chủ đích

  • sửa dữ liệu thật do nhu cầu nhiệm vụ,
  • backfill hẹp,
  • fix dữ liệu phục vụ chạy hệ thống.

Được phép có điều kiện:

  • phải ghi rõ trong vps_deploy_log.notes,
  • nên có script hoặc evidence truy được,
  • phải mô tả phạm vi tác động.

Loại C — Schema change / migration / destructive data change

  • ALTER TABLE,
  • DROP/DELETE diện rộng,
  • đổi constraint,
  • backfill lớn có rủi ro.

Không được coi là app deploy thường ngày. Phải đi bằng nhiệm vụ riêng, có phê duyệt/điều hành riêng, và tối thiểu phải có rollback story hoặc backup point.

§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; có thể chạm production data trong phạm vi nhiệm vụ hợp lệ của giai đoạn một VPS
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

Ghi chú quan trọng

Trong giai đoạn một VPS, “agent có toàn quyền” không có nghĩa là agent được bypass luật. Toàn quyền ở đây là toàn quyền trong hành lang có kiểm soát của Điều 41.

§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ó.

Khuyến nghị thêm cho giai đoạn một VPS

Nên có thêm 2 trường hoặc 2 quy ước ghi chú:

  • data_touched BOOLEAN hoặc ghi rõ DATA-TOUCHED trong notes
  • schema_touched BOOLEAN hoặc ghi rõ SCHEMA-TOUCHED trong notes

Mục tiêu là tách rõ deploy app thường ngày với nhiệm vụ có đụng dữ liệu/schema thật.

§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 thêm theo bối cảnh một VPS duy nhất

  1. Không phủ nhận việc agent chạm production data. Luật thừa nhận đây là thực tế hiện tại.
  2. Tách rõ app code change / data patch nhỏ / schema change lớn. Không để mọi thứ lẫn vào một khái niệm “được phép sửa trên VPS”.
  3. Giữ quyền agent đủ mạnh nhưng vẫn cấm bypass luật.
  4. Bắt buộc để lại dấu vết khi có đụng data/schema thật.
  5. Viết rõ đây là luật chuyển tiếp cho giai đoạn một VPS, không phải đích kiến trúc dài hạn.

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

  1. Với giai đoạn một VPS, có nên thêm cờ bắt buộc DATA-TOUCHED / SCHEMA-TOUCHED vào sổ tay 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. Khi nào thì Điều 41 phải được amend để chuyển sang mô hình 2 VPS độc lập?

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

Điều 41 v0.3 chấp nhận thực tế hiện nay: chỉ có một VPS duy nhất, một DB thật duy nhất, agent cần quyền thao tác đủ mạnh để sửa nhanh trên VPS. Nhưng quyền đó không phải quyền sửa bừa. Luật buộc mọi thao tác phải đi trên một đường ray có vùng dev/prod, có lock, có smoke test, có rollback, có audit trail, có guard chống drift, và có phân loại rõ mức độ đụng tới data/schema production.