Incomex AI Portal
KB-371E

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

13 min read Revision 1
lawdieu-41vpsdeployproductiondraftgpt

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

Trạng thái: DRAFT — sau phản biện vòng 1, chờ vòng 2
Ngày: 2026-04-14
Soạn thảo: Incomex Hội đồng AI / GPT
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ỉ có một VPS dùng chung code + production data

§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 riêng dev VPS và production VPS.

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. Điều 41 không cấm điều đó; Điều 41 ép nó vào một hành lang có kiểm soát: tách vùng, lock, verify, rollback, audit trail, guard chống drift, và phân loại rõ mức độ đụng data/schema thật.

Giả định vận hành hiện tại

  • Chỉ có một DB production thật.
  • Hiện không có cách bảo vệ data tốt hơn backup.
  • Backup hiện đang chạy tự động về Google Drive; khi data quan trọng hơn có thể tăng lên 5–6 lần/ngày.
  • Vì vậy, luật này không được giả định có sandbox data riêng hay DR nhiều lớp; nó phải dùng được trong bối cảnh thật hiện nay.

Đị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.4 là luật cho giai đoạn chuyển tiếp một VPS.

§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/verify 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 destructive change và schema change không được trộn tự phát vào 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.
NT-VPS-9 Backup là tuyến bảo vệ dữ liệu thực tế hiện nay Luật không giả định có DR cao cấp; vì vậy mọi thao tác chạm data/schema phải phân loại rõ để backup/restore còn khả thi khi cần.

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

/opt/incomex/
├── app-dev/
├── app-production/
│   ├── .env.production
│   ├── releases/
│   └── current -> releases/<timestamp>
├── infra/
└── deploy/

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ụ hoặc mode verify nhanh tùy smoke profile
  • Build 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 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 file code thực thi trực tiếp trên VPS
  • Tự ý trộn destructive migration/schema patch vào app deploy loop mà không khai báo rõ

3.3. Phân loại thao tác trong giai đoạn một VPS

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

Ví dụ:

  • update hẹp có điều kiện rõ,
  • backfill nhỏ,
  • fix dữ liệu phục vụ chạy hệ thống.

Được phép có điều kiện, và phải có đủ 4 thứ:

  1. DATA-TOUCHED=true trong sổ tay PG
  2. script hoặc câu lệnh truy được
  3. DRY-RUN/evidence trước khi chạy thật: tối thiểu SELECT count(*) + 5 dòng mẫu bị tác động
  4. mô tả rõ phạm vi tác động trong notes

Không bắt buộc backup riêng cho mọi Loại B, vì bối cảnh hiện tại dùng backup định kỳ là tuyến bảo vệ thực tế. Tuy nhiên, nếu patch vượt ngưỡng nhỏ/hẹp, nó không còn là Loại B.

Loại C — Schema change / destructive data change

Ví dụ:

  • ALTER TABLE,
  • DROP/DELETE diện rộng,
  • đổi constraint,
  • rename,
  • backfill lớn có rủi ro,
  • migration có thể làm app hoặc data không tương thích.

Không được coi là app deploy thường ngày. Phải đi bằng nhiệm vụ riêng và tối thiểu phải có đủ 5 điều kiện:

  1. SCHEMA-TOUCHED=true trong sổ tay PG
  2. mô tả rõ UP change và rollback story
  3. backup point hoặc export phù hợp với phạm vi bảng/schema bị tác động
  4. evidence thử trước trên phạm vi hẹp hoặc transaction dry-run khi khả thi
  5. Owner approval explicit trong chat/task trước khi apply

3.4. Safe schema exception trong app deploy loop

Một số thay đổi schema nhỏ có thể đi cùng app deploy nếu đồng thời thỏa cả 4 điều kiện:

  1. additive-only, ví dụ ADD COLUMN NULLABLE
  2. không DROP/RENAME/ALTER destructive
  3. SCHEMA-TOUCHED=true
  4. có script kèm rollback story rõ ràng

Nếu không thỏa 4 điều kiện này, nó quay về Loại C đầy đủ.

§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ệ
Claude Desktop Điều phối, đọc luật, soạn prompt, rà soát sổ tay; không sửa file code thực thi
Claude Desktop qua Agent Data Được phép sửa tài liệu .md trong knowledge/laws nếu đi qua công cụ tài liệu có audit trail
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 bằng flock trên file lock chuẩn trong /opt/incomex/deploy/
  • Xác nhận không có deploy khác đang chạy
  • 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 khi phù hợp
  • 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
  • Build theo một trong hai cách:
    • build_method='vps_native'
    • build_method='artifact_upload' nếu build tại chỗ quá rủi ro cho VPS
  • Build fail => dừng, ghi build_failed

Bước 4 — FAST mode / FULL mode

FULL mode

  • Chạy instance tạm từ release mới ở port phụ nếu khả thi
  • Verify theo smoke profile
  • Smoke fail => dừng, ghi smoke_failed

FAST mode

  • Áp dụng cho fix nhỏ/hẹp
  • Có thể bỏ qua port phụ nếu smoke profile đánh dấu không khả thi
  • Nhưng bắt buộc verify production ngay sau swap + post-deploy watch

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
  • Kiểm tra theo smoke profile: status, max size, max latency
  • Nếu swap + restart quá 60 giây mà chưa healthy => rollback

Bước 6.5 — Post-deploy watch

  • Theo dõi 5 phút sau deploy
  • Nếu fail lặp lại vượt ngưỡng định nghĩa trong smoke profile/watch profile => auto rollback + alert
  • Pass watch => đánh dấu is_known_good=true

Bước 7 — Rollback

  • Chỉ rollback về release gần nhất có is_known_good=true
  • 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 hoặc retention theo ngày
  • Release lock

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

Hạ tầng đi theo quy trình:

  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.

§7. Smoke profile bắt buộc

Không hardcode cứng 3 endpoint giống nhau cho mọi app. Mỗi app phải có smoke profile riêng, có thể ở dạng YAML/JSON, tối thiểu quy định:

  • endpoints
  • expected_status
  • max_size_bytes
  • max_latency_ms
  • watch rule sau deploy
  • cho phép hay không cho FAST mode
  • có thể hay không thể test bằng port phụ

§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,
  data_touched BOOLEAN NOT NULL DEFAULT false,
  schema_touched BOOLEAN NOT NULL DEFAULT false,
  is_known_good BOOLEAN NOT NULL DEFAULT false,
  build_method TEXT,
  backup_point 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,
  • data_touched,
  • schema_touched,
  • is_known_good,
  • build_method.

backup_point là bắt buộc cho Loại C, và là tùy chọn có khuyến nghị cho Loại B khi phạm vi patch không còn thật sự nhỏ.

§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
dot-vps-deploy-watch theo dõi 5 phút sau deploy để xác nhận known-good

§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. Tăng tần suất backup code/data lên mức phù hợp khi cần, có thể 5–6 lần/ngày nếu dữ liệu bắt đầu đáng kể hơn
  6. Chạy audit backfill cho các thay đổi gần đây chưa có sổ tay
  7. Sau đó mọi thay đổi mới phải đi qua Điều 41

§11. Các chỉnh lý chính sau phản biện vòng 1

Đã tiếp thu

  • bắt buộc DATA-TOUCHED / SCHEMA-TOUCHED
  • thêm is_known_good
  • thêm post-deploy watch
  • rollback về known-good thay vì release liền trước
  • thêm smoke profile có ngưỡng cụ thể
  • thêm FAST/FULL mode
  • cho phép Desktop sửa tài liệu markdown, không sửa code thực thi
  • cho phép build bằng artifact upload khi build native quá rủi ro
  • cho phép safe schema exception có điều kiện

Chưa tiếp thu toàn phần

  • Không nâng PG advisory lock thành blocker bắt buộc: giai đoạn hiện tại một VPS, local deploy script, flock đơn giản và đủ dùng hơn; lock file stale không đồng nghĩa lock còn giữ, vì lock gắn với process. Có thể nâng cấp sau nếu thực tế chứng minh cần.
  • Không bắt buộc backup riêng cho mọi Loại B: bối cảnh hiện tại chỉ có backup định kỳ là tuyến bảo vệ thực tế; bắt buộc export/backup cho mọi patch nhỏ sẽ làm quy trình nặng và dễ bị bypass. Chỉ siết bắt buộc backup point với Loại C, và với Loại B thì siết DRY-RUN + evidence phạm vi.

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

  1. Ngưỡng nào để Loại B không còn là “nhỏ” và phải nâng lên Loại C?
  2. flock có đủ cho giai đoạn này không, hay có bằng chứng thực tế buộc phải nâng sang advisory lock?
  3. FAST mode nên giới hạn ở loại thay đổi nào để không bị lạm dụng?
  4. Retention nên theo 10 release, 7 ngày, hay kết hợp cả hai?
  5. Backup frequency 1/ngày có cần amend ngay thành mức cao hơn trong luật hay để ở mức “khi data đáng kể hơn thì tăng”?
  6. Tiêu chí nào kích hoạt việc amend Điều 41 để chuyển sang mô hình 2 VPS?

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

Điều 41 v0.4 chấp nhận thực tế hiện nay: một VPS duy nhất, một DB thật duy nhất, agent cần quyền đủ 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ó tách vùng, có lock, có smoke profile, có FAST/FULL mode, có rollback về known-good, có audit trail, có guard chống drift, và có phân loại rõ mức độ đụng data/schema production.