Lộ trình tổng thể
Đây là lộ trình chủ cho cả ba thành phần: Access Hub (mã HUB), Collector (mã COL), Agent (mã AGT), và các hạng mục dùng chung (mã X). Lộ trình chi tiết của từng hệ thống do dự án đó giữ, nhưng phải khớp bảng này.
Thời gian là ước tính cho một nhóm nhỏ (2 đến 3 kỹ sư Go, 1 kỹ sư Laravel, tham gia bán thời gian của DevOps). Mọi mốc phải xem lại sau mỗi giai đoạn.
Tổng quan
| Giai đoạn | Mục tiêu | Thời gian | Mốc hoàn thành (exit criteria) |
|---|---|---|---|
| 0. Nền tảng | Repo, CI, giao thức, khung dự án, hợp đồng API | 1 đến 2 tuần | .proto v1 chốt, mock Access Hub chạy, CI xanh ở cả hai repo |
| 1. MVP | Linux agent + enroll + 1 collector + alert mất tín hiệu + trạng thái sức khỏe trong Access Hub | 6 đến 8 tuần | 1.000 agent mô phỏng và 20 máy thật chạy liên tục 7 ngày, alert agent down đến chuông và thông báo, không mất dữ liệu |
| 2. Đầy đủ | Windows, luật ngưỡng, checks, rollup, biểu đồ, kiểm kê, purge, kiểm thử tải 5k | 8 đến 10 tuần | 5.000 agent mô phỏng đạt NFR, MSI ký, biểu đồ, luật mặc định, purge tenant |
| 3. Quy mô và an toàn | HA, JetStream, VM cluster, cập nhật tự động ký, mTLS, IaC, đa collector | 8 đến 12 tuần | 10.000+ agent đạt NFR, chịu mất node, cập nhật theo đợt có quay lui |
| 4. Mở rộng (tùy chọn) | Log, hành động từ xa có kiểm soát, giám sát không agent, phát hiện bất thường | Theo nhu cầu | Quyết định theo giá trị kinh doanh |
Tổng thời gian đến hết GĐ 3: khoảng 23 đến 32 tuần. GĐ 1 và các hạng mục HUB có thể chạy song song với GĐ 0 khi hợp đồng API đã chốt.
Giai đoạn 0: Nền tảng
| Mã | Việc | Repo |
|---|---|---|
| X-1 | Chốt module path Go, host git, quy ước nhánh và phát hành | Cả hai |
| X-2 | Viết .proto v1 (agent.proto), cấu hình buf lint và breaking | Collector |
| X-3 | Xuất OpenAPI của Access Hub (Scramble) làm hợp đồng, sinh mock | Cả hai |
| COL-1 | Khung dự án Go: cmd/collector, cấu hình, log, /healthz /readyz /metrics, tắt êm | Collector |
| COL-2 | Docker Compose dev (Redis, VictoriaMetrics), Makefile, CI cơ bản | Collector |
| AGT-1 | Khung dự án Go: CLI (run, version, check-config), cấu hình YAML, log | Agent |
| AGT-2 | CI đa nền tảng (linux, windows, amd64, arm64), lint, kiểm thử | Agent |
| HUB-2 | Quyền monitoring.* và vai trò collector | Access Hub |
| HUB-3 | routes/api/monitoring.php, rate limiter | Access Hub |
| X-4 | ADR 0001 đến 0011 của Collector và ADR của Agent được duyệt | Cả hai |
Giai đoạn 1: MVP
| Mã | Việc | Ghi chú |
|---|---|---|
| HUB-1 (phần 1) | Bảng collectors, licenses, agents, alerts, alert_events | |
| HUB-4 | API collector: enroll, agents, seen, heartbeat | Mẫu API, kiểm thử |
| HUB-5 | API events và xử lý alert, thông báo, chuông Reverb, audit | |
| HUB-6 | License: model, API, giao diện, bộ tạo lệnh cài | |
| HUB-7 | Trang Agents, Tổng quan, tab sức khỏe (giá trị mới nhất) | Tài liệu trong ứng dụng, dịch vi/en |
| HUB-8 | MonitoringCollectorClient, ngắt mạch, trạng thái không có dữ liệu | |
| COL-3 | Ingest: xác thực token, registry (Redis + Access Hub), giới hạn, last_seen | Xong. Redis dùng DB riêng khi kiểm thử. Presence và rate limit còn ở bộ nhớ tiến trình (adapter Redis chưa làm) |
| COL-4 | Enroll proxy, đồng bộ registry, thu hồi | Xong. renew trả 503 (Access Hub chưa có endpoint, xem docs/06) |
| COL-5 | Bus in-process, worker, ghi TSDB theo lô, nhãn company_id, server_id | Xong. Adapter VictoriaMetrics (/api/v1/import) chỉ kiểm thử bằng httptest, chưa chạy với VM thật. Kho bộ nhớ khi tsdb.url trống |
| COL-6 | Phát hiện mất tín hiệu, sự kiện, outbox, gửi Access Hub idempotent | Xong. Quét 10s, ngưỡng max(3 x interval, 90s), seq là mili giây phát sinh tăng chặt, outbox bộ nhớ, tệp hoặc Redis (độ bền Redis phụ thuộc AOF), người gửi giữ lease Redis 15s. Kiểm thử với mockhub |
| COL-7 | API admin: registry push, status, series (giá trị mới nhất) | Xong, xem 03-protocol.md mục 4. Reload luật đã có từ COL-8, settings và silences từ COL-9, renew là stub 503. Kiểm thử hai tenant qua ingest và API admin |
| COL-R | Tách tiến trình: ingest, worker, admin chạy riêng qua Redis (registry, presence, bus Streams, outbox, lease) | Xong. Hai ingest sau load balancer chạy được (giới hạn tốc độ tính theo từng instance). Bus JetStream chưa làm. Mỗi tiến trình cần collector_id riêng |
| AGT-3 | Bộ thu Linux: CPU, tải, RAM, swap, đĩa, mạng, uptime | Gopsutil, fixture /proc |
| AGT-4 | Enroll, lưu thông tin đăng nhập an toàn, gửi metrics, backoff, jitter | |
| AGT-5 | Đệm đĩa WAL, gửi bù | Kiểm thử mất điện giả lập |
| AGT-6 | Dịch vụ systemd, gói .deb, .rpm (nfpm), script cài | Một phần: mã, gói .deb, .rpm, install.sh và kiểm thử cục bộ xong. Ma trận distro thật và kiểm tra rpm bằng công cụ rpm chưa làm. Chưa ký ở GĐ 1 nội bộ, ký ở GĐ 2 |
| X-5 | agentsim v1 (1.000 agent ảo) | Công cụ xong (2026-10-02): cmd/agentsim, mockhub -sim-licenses. Chạy 1.000 và 5.000 agent 3 phút, p99 ingest 5 đến 7 ms, 0 mẫu bị bỏ (docs/perf/2026-10-02-agentsim.md). Còn soak 7 ngày cùng X-6 |
| X-6 | Kiểm thử soak 7 ngày với 20 máy thật (Ubuntu, Debian, Rocky, CentOS 7) |
Giai đoạn 2: Đầy đủ
| Mã | Việc |
|---|---|
| AGT-7 | Bộ thu Windows (PDH, English counters), dịch vụ Windows, MSI (WiX), cài im lặng, ký Authenticode |
| AGT-8 | Checks: port, tcp, http, cert, service (cấu hình từ trung tâm). Xong phía agent (2026-10-02): check cục bộ và nhận check trung tâm qua AgentConfig.checks. Collector đã phân phối check (COL-20, 2026-10-02), còn chờ Access Hub (HUB-10, 06 mục 4.8) cung cấp GET /checks |
| AGT-9 | Kiểm kê, gửi khi đổi hoặc mỗi 6 giờ. Xong (2026-10-01) phía agent; collector nhận và chuyển tiếp từ COL-3. Chờ Access Hub: HUB-12, hợp đồng ở 06 mục 6.1 |
| AGT-10 | Xoay token, cấu hình từ xa có ETag, diag, status. Một phần (2026-10-01): cấu hình từ xa, status, diag, hiệu chỉnh đồng hồ xong; xoay token chờ Access Hub (đặc tả 06 mục 4.7) |
| AGT-11 | Ký gói .deb, .rpm, kho gói, script cài có xác minh. Chặn (2026-10-01): chờ chủ dự án chốt Q2 (nơi lưu kho apt, yum) và Q3 (ai giữ khóa GPG ký gói), xem 13 |
| COL-20 | Phân phối check trung tâm tới agent. Xong (2026-10-02), xem 03 mục 2.4 và 06 mục 4.8. Gói internal/checks (cùng mẫu đồng bộ với silence): kéo GET /checks theo sync_version, bia mộ, áp nguyên tử, snapshot, POST /reload/checks. Chỉ mục theo (company_id, server_id) lấy từ check và từ bản ghi agent đã xác thực, nên check công ty A không bao giờ tới agent công ty B kể cả khi hub liệt kê trùng id máy. Check sai bị bỏ từng cái, tối đa 50 check một máy (cắt theo id), ETag cấu hình đổi khi tập check đổi (agent nhận qua MetricsAck.config_etag). Chờ Access Hub: HUB-10 |
| COL-8 | Luật ngưỡng: biên dịch, đánh giá, trạng thái, snapshot. Xong (2026-09-30), xem 05-alerting.md mục 2.1 và 06 mục 4.1. Kéo GET /rules theo sync_version, bia mộ, áp nguyên khối, snapshot luật và trạng thái (Redis, tệp hoặc bộ nhớ), POST /reload/rules thật cùng tín hiệu Redis, hysteresis, for, no_data, rule_version trong sự kiện. Chưa làm: rule.invalid dạng sự kiện. Silence, bảo trì, reload/settings đã xong ở COL-9. Không chạy được -race (máy thiếu gcc), thay bằng kiểm thử đồng thời |
| COL-9 | Chống nhiễu. Xong (2026-10-01), xem 05-alerting.md mục 3 và 4, 06 mục 4.2 đến 4.5. Hysteresis có từ COL-8. Flapping (4 lần trong 30 phút vào, yên 30 phút ra, alert.flapping). Chặn thông báo suppressed và suppress_reason (decommissioned, maintenance, silence) cho cả agent.down, agent.up, group_*. Silence qua GET /silences (sync_version, bia mộ, áp nguyên khối, snapshot, POST /reload/silences), cách ly theo công ty, so theo timestamp sự kiện. group_down, group_update, group_resolved theo subnet và datacenter, tham số theo công ty từ GET /settings/{company_id} (POST /reload/settings thật). Chờ Access Hub: HUB-13 (silence, server_status, subnet_id, datacenter, settings). Giới hạn: nhóm không chia sẻ giữa nhiều worker |
| COL-10 | Rollup (vmalert, vm-long), API series tự chọn nguồn. Xong (2026-10-01), xem 04-data-model.md mục "Retention và rollup", 03 mục 4, 06 mục 4.4 và 4.6. Luật vmalert sinh từ catalog bằng collector -rollup-rules (cùng mã với bộ đọc). Nguồn chọn theo tuổi của from (7 ngày) và step (ô 5 phút hoặc 1 giờ), step làm tròn theo ô, điểm gộp lại các ô bằng cùng hàm, rollup trống thì đọc lại vm-raw khi còn trong 30 ngày. Khoảng tối đa 400 ngày khi có vm-long. Retention theo gói: metrics_retention_days từ GET /settings/{company_id}, collector cắt from khi đọc (không xóa vật lý, xem Q17). Kiểm thử với VictoriaMetrics thật (deploy/dev/vmcheck). Chờ Access Hub: trả metrics_retention_days, gọi reload khi đổi gói (mục 4.6 của 06) |
| COL-11R | Retention theo gói và xóa vật lý (Q17). Xong (2026-10-02), ADR 0016: nhãn ngày ah_day trên mọi mẫu và rollup, đọc cắt theo giới hạn đọc (ân hạn 30 ngày), ghi bỏ mẫu trong vùng khóa, janitor xóa cả ngày bằng delete_series và force_merge, lưới an toàn (không xóa khi hub lỗi, chờ 24 giờ, nhớ retention lớn nhất 30 ngày), chuyển dữ liệu rollup cũ sang nhãn ngày. Đo 4 phương án trên dev (deploy/dev/vmcheck/retbench_test.go). Chờ Access Hub: ghi nhận thay đổi retention và trả metrics_retention_previous_days, metrics_retention_grace_until (06 mục 4.6 điểm 6) |
| COL-11 | Purge server và tenant, tách cardinality, giới hạn theo công ty. Xong (2026-10-01), xem 03 mục 4 (xóa dữ liệu) và giới hạn ở mục 1. Bia mộ purge (internal/purge, Redis hoặc bộ nhớ, 15 phút) ghi trước khi xóa, worker bỏ lô còn trên bus và trong bộ đệm, quên trạng thái alert, flapping, nhóm của tenant không phát sự kiện, xóa TSDB lần hai sau 10 giây. Giới hạn series theo công ty ở ingest (max_series_per_company, mặc định tắt vì gói đã giới hạn số agent). Hạn mức số agent theo gói do Access Hub kiểm lúc enroll, collector chuyển mã quota_exceeded. Chờ Access Hub: HUB-14 gọi purge, xem 06 mục 8 |
| COL-12 | Kiểm thử "hai tenant", fuzz giao thức. Xong (2026-10-01), xem 12-testing.md mục 2. Bốn đích fuzz (make fuzz, job CI fuzz-short), ma trận hai tenant qua admin, ingest, kiểm kê, purge, retention. Không tìm thấy lỗi sau 90 giây mỗi đích. -race vẫn không chạy được trên máy dev (thiếu gcc), CI có |
| HUB-9 | Luật ngưỡng: CRUD, giao diện, đồng bộ, bộ luật mặc định |
| HUB-10 | Checks. Đặc tả cho Access Hub ở 06 mục 4.8 (2026-10-01). AGT-8 (agent) và COL-20 (collector) đã xong, chỉ còn phía Access Hub |
| HUB-11 | Biểu đồ và chọn khoảng thời gian |
| HUB-12 | Kiểm kê: so sánh, áp dụng (quan hệ IacDrift). Đặc tả ở 06 mục 6.1 |
| HUB-13 | Silence, bảo trì |
| HUB-14 | Purge Server và Company gọi collector. Đặc tả ở 06 mục 8.1, collector sẵn sàng (COL-11) |
| X-7 | agentsim 5.000, kiểm thử tải theo kịch bản mục 8 của 08. Một phần (2026-10-02): 5.000 agent enroll đồng loạt và gửi 3 phút trên một tiến trình đạt NFR-01; còn các kịch bản mất thành phần và cấu hình tách vai trò |
| X-8 | Mẫu Ansible, GPO, Intune, cloud-init cho cài hàng loạt |
Giai đoạn 3: Quy mô và an toàn
| Mã | Việc |
|---|---|
| COL-13 | Bus JetStream, shard lease, phát lại |
| COL-14 | Redis HA, cache bộ nhớ nhiều tầng cho registry |
| COL-15 | VictoriaMetrics cluster cho hệ thống Cloud (ADR 0017): hai cụm vm-raw và vm-long, cấu hình rollup theo cụm; janitor và purge chạy trên cụm (xóa qua vmselect /delete/0/..., force_merge từng vmstorage, không xóa khi thiếu node); ghi kép và đích ghi, đọc, xóa tách riêng trong cấu hình; chạy agentsim trên cụm (1.000, 5.000, 10.000 máy, qua nửa đêm UTC); tính dung lượng chỉ mục cho nhãn ah_day (Business 90 ngày); runbook cutover và quay lui (docs/14 mục 12.1); kiểm thử hai tenant lại trên cụm |
| COL-16 | Endpoint cập nhật, manifest ký, đợt triển khai, dừng khẩn cấp |
| COL-17 | mTLS tùy chọn, cấp chứng chỉ máy khách |
| COL-18 | Nhiều collector, gán và chuyển agent, định tuyến truy vấn. Chuyển công ty giữa collector theo docs/14 mục 12.2 (ba lựa chọn, gỡ ghim License). Không tách collector theo loại khách (quyết định 02/10/2026) |
| COL-19 | Helm chart, HPA, PodDisruptionBudget |
| AGT-12 | Cập nhật tự động: kiểm chữ ký, tải, thay thế nguyên tử, quay lui |
| AGT-13 | mTLS phía agent |
| AGT-14 | Hỗ trợ arm64 hoàn chỉnh, gói cho Windows arm64 (tùy chọn) |
| HUB-15 | Quản lý collector, gán agent |
| HUB-16 | Trang phát hành agent, kênh (stable, beta), dừng khẩn cấp |
| HUB-17 | Tích hợp IaC: manifest cho luật, License |
| HUB-18 | Đẩy alert lên ứng dụng di động (nếu có kênh push) |
| X-9 | agentsim 10.000 trở lên, kiểm thử hỗn loạn (mất Redis, TSDB, node, Access Hub) |
| X-10 | Tài liệu vận hành đầy đủ, runbook, diễn tập khôi phục |
Giai đoạn 4 (tùy chọn, cần quyết định)
| Hạng mục | Điều kiện để khởi động |
|---|---|
| Thu log (tail, journald, Event Log) | Có nhu cầu rõ và chọn được backend (VictoriaLogs, Loki) |
| Hành động từ xa (khởi động lại dịch vụ) từ danh sách trắng | Mô hình cấp phép, phê duyệt (dùng luồng approval sẵn có), ký lệnh. Cần ADR mới đảo ngược ADR 0010 có kiểm soát |
| Giám sát không agent (ICMP, SNMP, kiểm tra từ collector) | Cho thiết bị không cài được agent |
| Phát hiện bất thường, dự báo đầy đĩa | Đã có đủ dữ liệu lịch sử |
| Retention theo công ty | Yêu cầu tuân thủ cụ thể |
Phụ thuộc giữa các giai đoạn
.protov1 (X-2) và hợp đồng Access Hub (X-3) chặn COL-3, AGT-4, HUB-4. Làm sớm nhất.- AGT-4 và COL-3 cần thử nghiệm ghép sớm bằng mock, không đợi Access Hub thật.
- GĐ 2 luật ngưỡng (COL-8) phụ thuộc đồng bộ thuộc tính máy chủ (HUB-4 mở rộng, endpoint
servers/attributes). - GĐ 3 cập nhật tự động (AGT-12) phụ thuộc kho khóa ký và quyết định nơi lưu trữ gói (xem 13).
Định nghĩa hoàn thành chung
Một hạng mục chỉ được coi là xong khi:
- Mã đã hợp nhất và qua CI (lint, kiểm thử, quét bảo mật).
- Có kiểm thử phù hợp (đơn vị, tích hợp, và kiểm thử hợp đồng với phía kia).
- Tài liệu cập nhật: doc kỹ thuật trong repo và (với phần Access Hub) trang docs trong ứng dụng, bản vi và en.
- Metric và log cần thiết đã có, cảnh báo nội bộ đã cập nhật.
- Đã xem xét cô lập tenant nếu đụng dữ liệu công ty.
- Với Access Hub: theo danh sách hoàn thành ở 06 mục 9.
Rủi ro lộ trình
Xem 13-risks-open-questions. Rủi ro lớn nhất: Windows (PDH và MSI), khóa ký và kênh cập nhật, kiểm chứng sức chứa thật, và tải phía MySQL của Access Hub khi có sự kiện diện rộng.