Lộ trình của agent

Bảng dưới là lộ trình của agent (mã việc AGT). Mã X-, COL-, HUB- là việc của dự án hoặc nhóm khác, chỉ nêu ở đây khi agent phụ thuộc vào chúng. Thời lượng ước tính theo giai đoạn chung (GĐ 0: 1 đến 2 tuần, GĐ 1: 6 đến 8 tuần, GĐ 2: 8 đến 10 tuần, GĐ 3: 8 đến 12 tuần).

8 phút đọcCập nhật 02/10/2026access-hub-agent, docs/07-roadmap.md

Giai đoạn 0: Nền móng

Mã	Việc	Kết quả kiểm chứng	Trạng thái
AGT-1	Khung dự án Go: CLI (run, version, check-config), cấu hình YAML nghiêm ngặt, log slog	check-config báo đúng lỗi dòng. version in đủ thông tin. Kiểm thử đơn vị cấu hình	Xong
AGT-2	CI đa nền tảng (linux, windows, amd64, arm64), lint (golangci-lint), go vet, govulncheck, kiểm thử, dựng artifact	CI xanh trên cả bốn tổ hợp, binary tĩnh (CGO_ENABLED=0), kích thước được ghi nhận	Xong

Phụ thuộc bên ngoài: module path và nơi lưu mã (X-1, đã có), hợp đồng .proto v1 (X-2, đã có, xem 10-wire-contract.md).

Spike liên quan: S1 (PDH và Windows đa ngôn ngữ, có thể làm sớm), S5 (gopsutil so với tự đọc /proc, kích thước binary và CPU).

Giai đoạn 1: MVP (Linux, đầu cuối)

Mã	Việc	Kết quả kiểm chứng	Trạng thái
AGT-3	Bộ thu Linux: CPU, tải, RAM, swap, đĩa, mạng, uptime, tiến trình, tự thân (agent_*)	Kiểm thử fixture /proc cho nhiều kernel. So sánh với top, free, df trong sai số. Tuân thủ catalog 03	Xong
AGT-4	Enroll, lưu thông tin đăng nhập an toàn (0600, ghi nguyên tử), gửi metrics protobuf, nén, backoff full jitter, pha lệch theo agent_id, xử lý đúng bảng mã lỗi	Kiểm thử với mockcollector: 401, 403, 413, 429 Retry-After, 5xx, mất kết nối. Không bao giờ log token	Xong
AGT-5	WAL trên đĩa, giới hạn dung lượng và tuổi, gửi bù có giới hạn tốc độ, phục hồi sau mất điện	Kiểm thử ngắt điện giả lập (kill -9 giữa ghi), CRC, đầy đĩa, WAL đầy bỏ cũ nhất	Xong
AGT-6	Dịch vụ systemd (hardening), gói .deb và .rpm (nfpm), install.sh có xác minh checksum, tài khoản dịch vụ, script gói	Cài, nâng cấp, gỡ, purge trên Ubuntu 20.04, 22.04, 24.04, Debian 11, 12, Rocky 8, 9, Amazon Linux 2023	Một phần: mã, gói và kiểm thử cục bộ xong (chưa commit). Ma trận distro thật và kiểm tra rpm bằng công cụ rpm CHƯA làm

Tiêu chí ra GĐ 1 (agent):

1. Enroll thật với collector ở môi trường thử, số liệu hiện trong Access Hub.
2. 200 agent mô phỏng và ít nhất 10 agent thật chạy ổn định 7 ngày, không rò rỉ bộ nhớ (RSS ổn định), CPU trong ngân sách.
3. Cúp mạng 30 phút rồi khôi phục: dữ liệu bù đủ, đúng thứ tự.
4. Mất điện giả lập 20 lần: WAL không hỏng.

Giai đoạn 2: Windows, checks, kiểm kê, vận hành

Mã	Việc	Kết quả kiểm chứng	Trạng thái
AGT-7	Bộ thu Windows (PDH English counters, hai mẫu), dịch vụ Windows, MSI (WiX), cài im lặng, ký Authenticode	Windows 10, 11, Server 2016, 2019, 2022, gồm bản ngôn ngữ không phải tiếng Anh. Cài im lặng, nâng cấp giữ cấu hình, gỡ	Một phần (2026-10-02): xong bộ thu CPU, RAM, page file (ước lượng), đĩa, mạng, uptime, agent, kiểm tra service và port, tên và phiên bản hệ điều hành (internal/collector/windows, ADR 0007: API trực tiếp, không PDH). Biên dịch chéo windows amd64 và arm64, logic kiểm thử bằng API giả, chưa chạy trên Windows thật. Dịch vụ Windows (2026-10-02, ADR 0008): service install, uninstall, start, stop, restart, run --windows-service, tài khoản ảo NT SERVICE\AccessHubAgent, khóa ACL thư mục dữ liệu, ánh xạ mã thoát cho SCM; logic có kiểm thử, lớp advapi32 chỉ biên dịch chéo. Chưa làm: MSI (WiX), ký Authenticode (chờ Q3), kiểm kê Windows (CPU, RAM, đĩa), PDH cho I/O đĩa, chạy thật trên Windows
AGT-8	Checks: service, port, tcp, http, cert, cấu hình từ trung tâm, chặn link-local	Kiểm thử đích lỗi, timeout, redirect, chứng chỉ hết hạn, đích bị chặn	Xong (2026-10-02): internal/collector/checks. service đọc cgroup systemd (cgroup.events, không chạy lệnh, không cần quyền), port đọc /proc/net/tcp*, udp*, tcp, http (tối đa 3 chuyển hướng, nhãn URL bỏ thông tin đăng nhập và query), cert (số ngày còn lại, đọc cả chứng chỉ hết hạn). Chạy nền song song (8), timeout riêng (mặc định 5 giây, tối đa 15), không làm chậm chu kỳ. Chặn link-local cả khi DNS trỏ tới. Check từ trung tâm: nhận qua AgentConfig.checks (check cục bộ thắng khi trùng id, tối đa 50). Collector chưa phân phối check: chờ HUB-10 (đặc tả ở repo collector docs/06 mục 4.8)
AGT-9	Kiểm kê, gửi khi đổi hoặc mỗi 6 giờ	So sánh khớp với công cụ hệ điều hành, không thu dữ liệu ngoài danh sách	Xong (2026-10-01): internal/inventory (thu, băm nội dung, bộ gửi), linux.ReadHostFacts (cpuinfo, meminfo, stat, mountinfo, statfs), lệnh inventory, cấu hình inventory.enabled, inventory.interval. Đã so khớp với lscpu, free, df, ip trên Ubuntu 24.04. Chỉ Linux có CPU, RAM, đĩa; Windows chờ AGT-7. Access Hub chưa có POST /inventory (HUB-12), collector chuyển tiếp và thử lại
AGT-10	Xoay token, cấu hình từ xa có ETag, diag, status, collect-once, hiệu chỉnh đồng hồ	Xoay khi mất mạng giữa chừng không mất đăng nhập. diag che đủ bí mật	Xong phía agent (2026-10-02): cấu hình từ xa ETag (internal/remotecfg, lưu đĩa, danh sách trắng, trường 0 giữ cục bộ, dựng lại bộ thu), status (tệp status.json), diag (gói .tar.gz quét bí mật), collect-once (có từ trước), hiệu chỉnh đồng hồ (cảnh báo từ 5 giây, dời mốc từ 60 giây). Xoay token (2026-10-02): internal/renew, gọi POST /credentials/renew khi token đủ credentials.renew_after (mặc định 30 ngày, pha lệch theo agent_id), ghi credentials.json nguyên tử TRƯỚC khi dùng token mới, ghi lỗi thì giữ token cũ (chồng 24 giờ) và thử lại sau 1 giờ, 403 thì dừng. Kiểm thử với mockcollector (có renew và chồng 24 giờ). Chưa chạy thật: collector trả 503 cho đến khi Access Hub có endpoint (đặc tả ở repo collector docs/06 mục 4.7), agent chỉ ghi cảnh báo một lần rồi thử lại mỗi giờ ở mức debug
AGT-11	Ký gói .deb, .rpm, kho gói, install.sh và install.ps1 xác minh chữ ký, mẫu script first-boot cho image	Xác minh từ máy sạch. Kho apt và yum hoạt động	Chặn (2026-10-01): chờ chủ dự án chốt Q2 (kho gói) và Q3 (khóa GPG), xem repo collector docs/13

Tiêu chí ra GĐ 2 (agent): 1.000 agent (mô phỏng cộng thật) hoạt động 14 ngày, cấu hình từ xa có hiệu lực trong 5 phút, cài hàng loạt 100 máy Windows bằng GPO hoặc Intune thử nghiệm thành công.

Mẫu Ansible, GPO, Intune, cloud-init (X-8) là việc chung của nền tảng, chưa làm, sẽ dùng gói của agent.

Giai đoạn 3: An toàn quy mô lớn

Mã	Việc	Kết quả kiểm chứng	Trạng thái
AGT-12	Cập nhật tự động: manifest ký Ed25519, tải, kiểm tra, thay thế nguyên tử, quay lui, triển khai theo đợt	Cập nhật hỏng tự quay lui. Chặn hạ cấp. Đợt 1% và dừng khẩn cấp hoạt động	Chưa xây. Đã viết đề xuất giao thức và thiết kế phía agent cho nhóm Collector ở 11-auto-update-proposal.md (2026-10-02). Chờ: Q3 (khóa ký), COL-16, quyết định quyền hạn thay binary (mục 6 của đề xuất)
AGT-13	mTLS phía agent (chứng chỉ máy khách từ collector)	Xoay chứng chỉ, thu hồi, kết hợp với token	Chưa
AGT-14	Hoàn thiện arm64 (Linux) và gói Windows arm64 (tùy chọn)	Bộ kiểm thử gói chạy trên arm64	Chưa

Giai đoạn 4 (tùy chọn)

Thu log, hành động từ xa theo danh sách trắng (cần ADR mới thay thế ADR 0005), hỗ trợ container. Chỉ bắt đầu khi có quyết định.

Quy trình phát hành

1. Nhánh main luôn xanh. Phát hành bằng tag vMAJOR.MINOR.PATCH (semver).
2. CI dựng binary, gói, MSI, ký, sinh SHA256SUMS, SBOM, tải lên nơi lưu trữ.
3. Bản mới vào kênh beta trước, sau khi đạt kiểm thử chấp nhận thì đẩy vào stable.
4. Ghi changelog (CHANGELOG.md) và ghi chú tương thích giao thức.
5. Phiên bản giao thức và phiên bản agent tách biệt. Collector hỗ trợ N và N-1 của giao thức.

Rủi ro chính của agent

Rủi ro	Giảm thiểu
PDH sai trên Windows đa ngôn ngữ	Dùng PdhAddEnglishCounter, spike S1 sớm, kiểm thử máy không phải tiếng Anh
Agent làm chậm máy sản xuất	Ngân sách và giới hạn cứng, kiểm thử tải, cgroup limits trong unit
Nhân bản VM trùng danh tính	Phát hiện machine_id, identity_mismatch
Mất dữ liệu khi mất điện	WAL với CRC và phục hồi, kiểm thử ngắt điện
Chứng chỉ ký mã chậm cấp	Bắt đầu xin sớm (Q3), GĐ 1 nội bộ chưa cần
Chuỗi cung ứng	Ký, SBOM, build tái lập, govulncheck
Khác biệt hệ điều hành cũ	Ma trận hỗ trợ rõ, kiểm thử trên toàn ma trận

Danh sách rủi ro và câu hỏi mở của agent: mục 10 của L1 và mục 16 của L2.