L1 - Nền tảng giám sát máy chủ - Collector (data plane)
Tên trang theo quy ước: L1 - <Tên P&L> - <Tên hệ thống>. P&L: chưa chỉ định. Hệ thống: Collector, tầng thu nhận và xử lý số liệu của nền tảng giám sát máy chủ. Tài liệu này độc lập, chỉ mô tả Collector. Access Hub (control plane) và Agent (tác nhân trên máy chủ) là hệ thống ngoài, mỗi bên có bộ tài liệu riêng trong dự án của mình. Tài liệu này chỉ nói về chúng ở mức hợp đồng giao tiếp.
Thông tin tài liệu đầy đủ
| Trạng thái | BẢN NHÁP (tài liệu chưa sẵn sàng trình thẩm định) |
| Phiên bản | 0.2 (2026-09-30): tách thành L1 độc lập của Collector, dựng từ docs/00 đến docs/14, ADR 0001 đến 0015 và mã nguồn hiện có. Bản 0.1 cùng ngày là L1 chung cho cả nền tảng, đã bỏ. |
| Tên dự án | Collector cho nền tảng giám sát máy chủ của Access Hub |
| Bên thẩm định / Phê duyệt | Chưa chỉ định. Không có ai đã sign-off. Xem mục 0. |
| Tài liệu tầng trên (Parent) | IT Landscape và KHHĐ: chưa có liên kết, cần bổ sung khi tổ chức cung cấp. |
| Tài liệu tầng dưới (Child) | L2 Collector, cùng 5 tài liệu L3 của nó (xem L2 mục 2.3) |
| Tài liệu liên quan | Báo cáo lựa chọn TSDB, Báo cáo rủi ro ANBM, Chỉ mục ADR, Hợp đồng giao thức |
| Mục lục | 0 Front matter, 1 Hoàn cảnh, 2 Mục tiêu, 3 KPI, 4 Chất lượng, 5 Bên liên quan, 6 Định hướng, 7 Ngữ cảnh hệ thống, 8 Giả định và ràng buộc, 9 Phương án thay thế, 10 Rủi ro, 11 Giai đoạn, 12 Cấp độ quan trọng, A Thuật ngữ, B Phụ lục |
Quy ước đánh dấu trong tài liệu này: nội dung có nguồn trong tài liệu thiết kế hoặc mã hiện có được ghi kèm tham chiếu (ví dụ docs/02, NFR-01). Nội dung chưa có nguồn xác nhận được gắn nhãn đề xuất, chưa xác nhận.
Phân công tài liệu: mỗi dự án (Collector, Access Hub, Agent) giữ bộ L1, L2, L3 riêng và không dẫn chiếu đường dẫn sang dự án khác. Ranh giới giữa các dự án được mô tả bằng hợp đồng giao tiếp: hợp đồng agent, collector ở docs/03-protocol.md, hợp đồng collector, Access Hub ở docs/06-access-hub-integration.md.
0. Front Matter & Approvals
Cổng phê duyệt (Sign-off gate)
Chưa có cơ quan thẩm định nào được chỉ định. Các dòng dưới đây là vai trò theo mẫu, tên và ngày để trống cho đến khi có quyết định của tổ chức. Không dòng nào được ghi APPROVED.
| Vai trò | Tên | Trách nhiệm duyệt | Trạng thái | Ngày |
|---|---|---|---|---|
| EA (Enterprise Architect) | chưa chỉ định | Toàn vẹn thiết kế, đúng chuẩn, khả thi implement | PROCESSING (chưa trình) | |
| Chủ sở hữu sản phẩm | chưa chỉ định | Phạm vi, mục tiêu, thứ tự ưu tiên | PROCESSING (chưa trình) | |
| Bảo mật | chưa chỉ định | Mô hình đe dọa, quản lý token và khóa, kết quả ANBM | PROCESSING (chưa trình) | |
| Vận hành (SRE/DevOps) | chưa chỉ định | Khả năng vận hành, sao lưu, giám sát chính collector | PROCESSING (chưa trình) |
Cổng câu hỏi mở: mọi câu hỏi ở mục 10 phải được giải quyết hoặc chuyển thành rủi ro có theo dõi trước khi tài liệu L2 được phê duyệt.
Chu kỳ rà soát: tối đa 12 tháng, hoặc khi có thay đổi phạm vi, cấp độ quan trọng hay ranh giới hệ thống.
1. Hoàn cảnh nghiệp vụ (Problem Statement / Background)
Bối cảnh nền tảng. Access Hub là ứng dụng đa công ty (mỗi công ty là một tenant) quản lý kiểm kê máy chủ, kết nối, quản trị truy cập đặc quyền, hạ tầng dạng mã và quy trình phê duyệt. Nền tảng giám sát bổ sung khả năng biết máy chủ đang sống hay chết và khỏe hay yếu (docs/00). Nền tảng gồm ba hệ thống với ranh giới rõ (ADR 0004):
- Access Hub là control plane và là nguồn sự thật cho công ty, máy chủ, danh tính agent, luật, cảnh báo và giao diện. Hệ thống ngoài đối với Collector.
- Agent là chương trình nhỏ trên mỗi máy chủ, chỉ kết nối đi ra, đẩy số liệu gauge. Hệ thống ngoài đối với Collector.
- Collector là data plane, đối tượng của tài liệu này: nhận số liệu từ agent, lưu trữ, phát hiện mất tín hiệu, đẩy sự kiện lên Access Hub và phục vụ truy vấn cho Access Hub.
Vấn đề mà Collector giải quyết
Quy mô dự kiến là hàng nghìn máy chủ mỗi công ty, tổng tới hàng chục nghìn máy, thuộc nhiều mạng, thường sau NAT hoặc tường lửa (ADR 0001). Cơ sở dữ liệu nghiệp vụ của Access Hub là MySQL có tách đọc và ghi khi triển khai thật (docs/00), không phù hợp để hấp thụ dòng số liệu ghi liên tục (ADR 0004, ADR 0005).
| Vấn đề hiện tại | Hệ quả |
|---|---|
| Không có tầng nào đủ sức hấp thụ số liệu tần suất cao từ hàng chục nghìn máy | Đưa thẳng số liệu vào ứng dụng nghiệp vụ có thể làm nghẽn ứng dụng và MySQL (ADR 0004 phương án 1) |
| Không có nơi gắn danh tính tenant đáng tin cho từng mẫu số liệu | Nếu tin nhãn do agent gửi, một agent độc hại có thể ghi lẫn vào dữ liệu công ty khác (docs/07) |
| Không có tín hiệu sống hay chết của máy chủ | Quản trị viên chỉ biết máy hỏng khi người dùng báo, thời gian phát hiện không đo được (chưa có baseline, xem mục 3) |
| Không có kho chuỗi thời gian có truy vấn theo tenant | Không xem được biểu đồ lịch sử, không đánh giá được ngưỡng |
| Sự kiện cảnh báo chưa có đường đi bền vững tới Access Hub | Access Hub tạm lỗi hoặc mất kết nối là mất cảnh báo |
Lý do ưu tiên: yêu cầu mới của sản phẩm là giám sát máy chủ gần thời gian thực, mở rộng tới hàng chục nghìn máy mà không làm nghẽn ứng dụng nghiệp vụ (docs/00). Chưa có số liệu định lượng về tổn thất hiện tại; bổ sung khi có KHHĐ và dữ liệu sự cố (OQ-2).
2. Mục tiêu & Phi mục tiêu (Goals & Non-Goals)
Nguồn: docs/00-overview.md, docs/02-requirements.md.
Mục tiêu (Goals)
| STT | Mục tiêu của Collector | Link tài liệu L2 |
|---|---|---|
| G1 | Cho biết trạng thái từng máy chủ gần thời gian thực: phát hiện mất tín hiệu và phục hồi (agent.down, agent.up), cập nhật lần thấy cuối | L2 Collector mục 3 |
| G2 | Tiếp nhận, xác thực và lưu số liệu nền tảng từ agent (CPU, RAM, swap, đĩa, mạng, tải, uptime, dịch vụ, cổng, chứng chỉ) theo lô | L2 Collector mục 3, 7 |
| G3 | Đẩy sự kiện cảnh báo lên Access Hub qua đường bền vững, gửi lại an toàn, không trùng | L2 Collector mục 3, 8 |
| G4 | Scale ngang tới hàng chục nghìn agent bằng cách thêm bản sao ingest và worker, không đụng MySQL của Access Hub | L2 Collector mục 11, 12 |
| G5 | Cô lập dữ liệu giữa các công ty tuyệt đối: danh tính do Collector gắn từ registry, không PromQL thô | L2 Collector mục 7, 9 |
| G6 | Vận hành được bằng một binary nhiều vai trò, dựng lại đủ môi trường sản xuất ở dev | L2 Collector mục 10, 14 |
Phi mục tiêu (Non-Goals)
| Nội dung | Thuộc về | Lý do và giai đoạn |
|---|---|---|
| Quản lý công ty, máy chủ, người dùng, luật, thông báo, chuông realtime, audit | Access Hub | Control plane, nguồn sự thật (ADR 0004) |
| Thu thập số liệu trên máy chủ, đệm đĩa, kiểm tra cổng, HTTP, chứng chỉ | Agent | Chạy trên máy được giám sát |
| Gửi email, webhook | Access Hub | Collector chỉ phát sự kiện |
| Thực thi lệnh từ xa trên máy chủ | Không làm ở giai đoạn 1 đến 3 | Giảm bề mặt tấn công (ADR 0010) |
| Ghi kiểm kê từ agent vào bảng máy chủ | Không làm | Kiểm kê chỉ chuyển tiếp, Access Hub quyết định (ADR 0011) |
| Truy vấn PromQL thô từ bên ngoài | Không cung cấp | Cô lập tenant |
| Thu thập log tập trung, APM, giám sát không cần agent, dự đoán bất thường bằng ML | Giai đoạn 4 | Quyết định theo giá trị kinh doanh |
| Nhiều vùng dữ liệu | Chưa quyết định (Q13, docs/13) | Thiết kế có chừa chỗ, chưa cam kết |
3. Chỉ số đo lường cần đạt (Success Metrics / KPIs)
Hệ thống mới, chưa có baseline vận hành. Các mục tiêu lấy từ yêu cầu phi chức năng đã có (docs/02). Giá trị nào không có nguồn được gắn nhãn đề xuất, chưa xác nhận. Collector tự xuất chỉ số ahc_* để đo (docs/10).
KPI kinh doanh
| Chỉ số | Baseline | Mục tiêu | Ghi chú |
|---|---|---|---|
| Thời gian phát hiện máy chủ mất tín hiệu | Không đo được (chưa có giám sát) | Không quá 3 x chu kỳ gửi + 30 s (NFR-03); mã hiện dùng ngưỡng max(3 x interval, 90 s) (docs/11, COL-6) | Chu kỳ mặc định 30 s (Q5 còn mở) |
| Độ trễ từ lúc thỏa điều kiện đến lúc sự kiện tới Access Hub | Không áp dụng | Không quá 60 s (NFR-04) | Luật ngưỡng (COL-8) đánh giá ngay khi lô vào worker, độ trễ bám chu kỳ thu thập cộng for_seconds |
| Độ tươi của giá trị mới nhất | Không áp dụng | Không quá 45 s sau lúc thu thập (NFR-05) | Đo ở đầu truy vấn qua Admin API |
| Số sự cố hạ tầng được phát hiện bằng cảnh báo trước khi người dùng báo | Không đo được | đề xuất, chưa xác nhận | Cần quy trình ghi nhận sự cố |
KPI công nghệ
| Chỉ số | Baseline | Mục tiêu (nguồn) |
|---|---|---|
| Số agent phục vụ được | 0 | 10.000 agent ở chu kỳ 30 s trên 3 node ingest 4 vCPU, 8 GB; p99 ingest không quá 250 ms (NFR-01) |
| Độ sẵn sàng đường ingest | Không áp dụng | 99,9% mỗi tháng; mất một node không mất dữ liệu đã xác nhận (NFR-02) |
| Chịu mất kho chuỗi thời gian | Không áp dụng | Đệm tối thiểu 2 giờ (NFR-07, đầy đủ ở giai đoạn 3 với JetStream) |
| Chịu mất Access Hub | Không áp dụng | Outbox giữ sự kiện tối thiểu 24 giờ, ingest vẫn chạy bằng registry cache (NFR-08) |
| Truy vấn | Không áp dụng | Chuỗi 24 giờ một máy p95 không quá 500 ms; 30 ngày dùng rollup p95 không quá 1,5 s (NFR-06) |
| Lưu trữ số liệu | Không áp dụng | 30 ngày dữ liệu thô, 400 ngày dữ liệu rollup (Q4 xác nhận sau) |
| Khôi phục | Không áp dụng | Khởi động lại toàn bộ collector không mất cảnh báo đang mở (NFR-13) |
| Cô lập tenant | Không áp dụng | Có kiểm thử tự động hai tenant, không rò rỉ (NFR-12) |
Trạng thái đạt được thực tế hiện chưa đo: kiểm thử tải 1.000 đến 10.000 agent mô phỏng (X-5, X-7, X-9) và soak 7 ngày (X-6) chưa làm (docs/11).
4. Chỉ số chất lượng cần đạt (Quality Attribute Expectation)
Nguồn: docs/02-requirements.md, docs/07, docs/08. Là cơ sở cho NFR chi tiết ở L2.
| Thuộc tính | Ngưỡng kỳ vọng |
|---|---|
| Scalability (mở rộng) | Từ 1.000 tới hàng chục nghìn agent bằng cách thêm bản sao ingest và worker. 10.000 agent ở 30 s tương đương khoảng 333 request/s và khoảng 23.000 mẫu/s, khoảng 2 GB/ngày. 50.000 agent cần VM cluster hoặc nhiều collector (docs/08) |
| Performance (hiệu năng) | p99 ingest không quá 250 ms ở 10.000 agent (NFR-01). Truy vấn theo NFR-06 |
| Availability (sẵn sàng) | Đường ingest 99,9% (NFR-02). Mất một node ingest hoặc worker không làm mất dữ liệu đã xác nhận (thiết kế docs/08; HA đầy đủ thuộc giai đoạn 3) |
| Reliability (độ bền) | Sự kiện cảnh báo đi qua outbox bền vững và gửi lại idempotent theo event_id (NFR-08, ADR 0008, ADR 0012). Từ chối có kiểm soát (503 kèm Retry-After) thay vì nhận rồi mất |
| Security (bảo mật) | Kênh TLS từ 1.2 trở lên (NFR-11), token agent dạng mờ chỉ lưu băm (ADR 0007), token quản trị riêng cho Admin API, cô lập tenant (NFR-12), không thực thi mã từ xa (ADR 0010) |
| Compatibility | Hỗ trợ giao thức agent phiên bản N và N-1 (NFR-14) |
| Observability | Mọi vai trò có /metrics, /healthz, /readyz, log JSON có request_id (NFR-15). Chỉ số ahc_* và cảnh báo về chính Collector (docs/10) |
| Compliance | Chưa có yêu cầu pháp lý hoặc SLA khách hàng được nêu trong tài liệu hiện có. Cần xác nhận (OQ-4) |
| Maintainability | Hợp đồng agent, collector là một tệp .proto có phiên bản, kiểm tra tương thích (docs/03). Một binary, chọn vai trò khi chạy (ingest, worker, admin, all) |
5. Các bên liên quan & Người dùng chính (Stakeholders & Personas)
Tài liệu hiện có không nêu tên bộ phận hay cá nhân. Cột "Bộ phận" để chưa chỉ định cho đến khi tổ chức xác nhận. Vai trò và RACI dưới đây là đề xuất, chưa xác nhận.
Các bên liên quan (Stakeholders)
| Vai trò | Bộ phận | Trách nhiệm đối với Collector |
|---|---|---|
| Chủ sở hữu sản phẩm | chưa chỉ định | Phạm vi, thứ tự ưu tiên, giải các câu hỏi mở về sản phẩm |
| Phát triển Collector (Go) | chưa chỉ định | Thiết kế, mã, kiểm thử, phát hành Collector |
| Chủ sở hữu hệ thống ngoài: Access Hub | chưa chỉ định | Cung cấp và giữ ổn định hợp đồng mà Collector gọi (enroll, đồng bộ registry, nhận sự kiện, seen, heartbeat) và gọi Admin API của Collector |
| Chủ sở hữu hệ thống ngoài: Agent | chưa chỉ định | Giữ đúng hợp đồng giao thức agent, collector |
| Vận hành (SRE/DevOps) | chưa chỉ định | Triển khai Redis, VictoriaMetrics, các vai trò collector, cân tải, giám sát chính hệ thống |
| Bảo mật | chưa chỉ định | Rà soát mô hình đe dọa, token, TLS, kết quả ANBM |
RACI (đề xuất, chưa xác nhận): R = thực hiện, A = chịu trách nhiệm cuối, C = tư vấn, I = được thông báo.
| Hoạt động | Chủ sở hữu sản phẩm | Dev Collector | Chủ hệ thống ngoài (Access Hub, Agent) | Vận hành | Bảo mật |
|---|---|---|---|---|---|
| Phạm vi và mục tiêu | A | C | C | C | C |
| Thiết kế và mã Collector | I | A/R | C | C | C |
| Thay đổi hợp đồng giao tiếp | I | A/R | C | I | C |
| Hạ tầng và triển khai | I | C | I | A/R | C |
| Token, ANBM | I | R | C | C | A |
Người dùng chính (Personas)
| Persona | Loại | Nhu cầu và hành vi liên quan đến Collector |
|---|---|---|
| Quản trị nền tảng | Người | Triển khai và quay vòng token quản trị, theo dõi sức khỏe collector (/readyz, ahc_*), thực hiện purge dữ liệu khi cần |
| Access Hub | Hệ thống ngoài (máy) | Nhận enroll được chuyển tiếp, đẩy registry xuống, thu hồi agent, truy vấn số liệu theo công ty, xóa dữ liệu tenant, nhận sự kiện và seen |
| Agent trên máy chủ | Hệ thống ngoài (máy) | Enroll, gửi số liệu và kiểm kê qua HTTPS, kéo cấu hình định kỳ |
| Quản trị viên và kỹ sư của công ty khách | Người, gián tiếp | Không gọi Collector trực tiếp; thấy kết quả qua giao diện Access Hub |
6. Định hướng thiết kế tổng quan (High-Level Solution Overview)
Mô tả giải pháp
Collector là dịch vụ Go viết theo nguyên tắc: danh tính chỉ đến từ registry, trạng thái dùng chung nằm ở Redis nên ingest không trạng thái, từ chối có kiểm soát thay vì nhận rồi mất, và sự kiện đi qua outbox bền vững (docs/01, L2 mục 2.1). Một binary chạy được ba vai trò tách rời, scale độc lập:
- Ingest: nhận HTTP từ agent (
ping,enroll,metrics,config,inventory), kiểm tra đầu vào, xác thực token qua registry, đẩy lô mẫu lên bus theo shard. Việc enroll được chuyển tiếp sang Access Hub, vì Access Hub là nơi cấp danh tính. - Worker: lấy lô mẫu từ bus, ghi vào kho chuỗi thời gian theo lô với nhãn
company_id,server_iddo Collector gắn. Quét phát hiện mất tín hiệu, tạo sự kiện vào outbox và gửi lên Access Hub. - Admin: cổng nội bộ cho Access Hub: đẩy registry, thu hồi agent, xem trạng thái, truy vấn số liệu theo công ty, xóa dữ liệu tenant.
Hạ tầng dùng chung: Redis (registry, presence, bus Streams, outbox, lease của bộ gửi) và VictoriaMetrics hai instance, một thô và một dài hạn (ADR 0012, ADR 0014, ADR 0015).
Tiến độ thực tế tại 2026-09-30, theo docs/11: đã xong COL-1 đến COL-7 và COL-R (ingest, enroll proxy, registry, bus, worker, ghi TSDB, phát hiện mất tín hiệu, outbox, Admin API, tách tiến trình). Đã làm thêm COL-8 (luật ngưỡng, POST /internal/v1/reload/rules). Chưa làm: chống nhiễu nâng cao và silence (COL-9), cài đặt theo công ty (reload/settings trả 501), bus JetStream, cấp lại token (renew trả 503). Môi trường dev là bản dựng giống sản xuất gồm 14 đơn vị systemd người dùng do deploy/dev/devctl.sh quản lý (hai Redis, hai VictoriaMetrics, vmalert, mockhub, hai ingest, hai worker, admin, cân tải nginx, một agent). Từ 2026-09-30 dev stack kết nối được với Access Hub thật qua tệp hub.url và đã kiểm chứng: Collector gọi Access Hub thành công, Access Hub đẩy registry xuống thành công, một agent enroll qua chuỗi đầy đủ, số liệu vào kho chuỗi thời gian đúng nhãn công ty và máy, lô seen cập nhật lần thấy cuối. Xóa tệp hub.url để quay lại mockhub.
Các thành phần chính và phân loại năng lực
| Năng lực | Phân loại |
|---|---|
| Tiếp nhận, kiểm tra, xác thực số liệu và kiểm kê từ agent | Core |
| Lưu số liệu theo tenant và truy vấn theo công ty (chọn nguồn thô hoặc rollup) | Core |
| Phát hiện mất tín hiệu, tạo và gửi sự kiện bền vững lên Access Hub | Core |
| Registry danh tính agent, chuyển tiếp enroll, thu hồi | Core |
| Admin API cho Access Hub, xóa dữ liệu theo tenant | Management |
Quan sát chính Collector (ahc_*, /readyz), vận hành, triển khai | Management |
| Luật ngưỡng (COL-8) | Core (đã làm) |
| Chống nhiễu nâng cao, silence (COL-9) | Core (chưa làm) |
| Thông báo, webhook, giao diện | Hệ ngoài (Access Hub) |
| Kho chuỗi thời gian, kho trạng thái chung | Supporting (hạ tầng) |
Luồng nghiệp vụ tổng quan
%%{init: {"flowchart": {"curve": "basis"}}}%%
flowchart LR
classDef bc fill:#1f3a5f,stroke:#4a90d9,color:#fff
classDef infra fill:#444,stroke:#aaa,color:#fff
A[Xác thực và nhận số liệu]:::bc
B[Lưu theo công ty và máy]:::bc
C[Phát hiện mất tín hiệu]:::bc
D[Gửi sự kiện lên Access Hub]:::bc
E[Truy vấn và quản trị]:::bc
R[[Kênh HTTPS từ agent]]:::infra
H[[Kênh gọi Access Hub]]:::infra
R -.-> A
A --> B
B --> C
C --> D
D -.-> H
H -.-> E
E --> BChú thích: xanh dương = năng lực nghiệp vụ của Collector, xám = kênh dùng chung, nét liền = bước tuần tự, nét đứt = bất đồng bộ.
| Bước | Diễn giải nghiệp vụ |
|---|---|
| Xác thực và nhận số liệu | Agent gửi số liệu ra ngoài qua HTTPS, Collector kiểm tra đầu vào và xác định agent thuộc công ty nào, máy nào từ registry, bỏ qua mọi danh tính do agent tự khai |
| Lưu theo công ty và máy | Số liệu được ghi theo lô vào kho chuỗi thời gian, gắn nhãn công ty và máy do Collector quyết định |
| Phát hiện mất tín hiệu | Collector quét định kỳ, máy quá ngưỡng thì phát sự kiện agent.down, có tín hiệu lại thì agent.up |
| Gửi sự kiện lên Access Hub | Sự kiện đổi trạng thái vào outbox bền vững, gửi lô idempotent, Access Hub khử trùng theo event_id |
| Truy vấn và quản trị | Access Hub gọi Admin API để đẩy registry, thu hồi agent, lấy số liệu theo công ty, xóa dữ liệu tenant |
Giá trị mang lại: tầng số liệu gần thời gian thực tách khỏi ứng dụng nghiệp vụ, scale ngang độc lập, danh tính tenant không thể bị giả mạo từ phía agent, không mất cảnh báo khi Access Hub tạm lỗi, và bề mặt tấn công nhỏ (agent chỉ kết nối đi ra, không chạy lệnh từ xa).
Chi tiết cấu trúc, công nghệ và luồng dữ liệu thuộc L2 và L3 của Collector, không lặp lại ở đây.
7. Sơ đồ hệ thống tổng quan (System Context / Scope Boundary)
%%{init: {"flowchart": {"curve": "basis"}}}%%
flowchart LR
classDef bc fill:#1f3a5f,stroke:#4a90d9,color:#fff
classDef entity fill:#3a3320,stroke:#d9b84a,color:#fff
AGT([Agent trên máy chủ]):::entity
HUB([Access Hub]):::entity
OPS([Quản trị nền tảng]):::entity
STO([Hạ tầng lưu trữ]):::entity
COL[Collector]:::bc
AGT -.->|Đẩy số liệu, enroll| COL
COL -.->|Gửi sự kiện, lần thấy cuối| HUB
HUB -->|Registry, truy vấn, xóa dữ liệu| COL
OPS -->|Triển khai, theo dõi| COL
COL -->|Ghi và đọc số liệu, trạng thái| STOChú thích: xanh dương = hệ thống trung tâm, vàng = tác nhân và hệ ngoài, nét liền = tương tác hai chiều, nét đứt = một chiều, mũi tên từ bên khởi xướng tới bên nhận.
Bảng mô tả
| Tác nhân / Hệ thống | Loại | Trong (Internal) | Ngoài (External) | Vai trò |
|---|---|---|---|---|
| Collector | Software System | X | Data plane: ingest, worker, admin. Thay đổi trong phạm vi tài liệu này | |
| Agent trên máy chủ | Hệ thống ngoài | X | Chạy trên máy được giám sát, đẩy số liệu ra ngoài. Giao tiếp theo hợp đồng docs/03-protocol.md | |
| Access Hub | Hệ thống ngoài | X | Control plane và nguồn sự thật. Cấp danh tính agent, giữ luật, nhận sự kiện, hiển thị. Giao tiếp theo docs/06-access-hub-integration.md | |
| Quản trị nền tảng | Người dùng | X | Triển khai, quay vòng token, theo dõi sức khỏe collector | |
| Hạ tầng lưu trữ | Hệ ngoài (hạ tầng) | X | Redis (trạng thái dùng chung) và VictoriaMetrics (kho chuỗi thời gian). Do vận hành cấp, Collector là bên sử dụng |
Bảng biên (boundary)
| Hệ ngoài | Chiều | Protocol / đảm bảo | Dữ liệu qua biên |
|---|---|---|---|
| Agent trên máy chủ | Vào (agent gửi ra) | HTTPS TLS 1.2 trở lên, protobuf, token agent riêng chỉ lưu băm, giới hạn tốc độ | Số liệu gauge, kết quả kiểm tra nhẹ, kiểm kê phần cứng và hệ điều hành, yêu cầu enroll và cấu hình |
| Access Hub, chiều ra | Ra | HTTPS, token dịch vụ với quyền riêng cho collector, gửi lại idempotent | Sự kiện agent.down và agent.up, lô last_seen, heartbeat, chuyển tiếp enroll, tra ngược token |
| Access Hub, chiều vào | Vào | HTTP nội bộ tới Admin API, token quản trị riêng, tùy chọn IP allowlist (Q15) | Đẩy registry, thu hồi agent, truy vấn số liệu theo công ty, xóa dữ liệu tenant |
| Quản trị nền tảng | Vào | Kênh vận hành: /healthz, /readyz, /metrics, cổng ops riêng | Trạng thái sức khỏe, chỉ số ahc_* |
| Hạ tầng lưu trữ | Ra và vào | Giao thức của Redis và API HTTP của VictoriaMetrics, mạng nội bộ | Registry, presence, bus, outbox, lease; mẫu số liệu và truy vấn |
Chi tiết giao thức và các kết nối nội bộ thuộc L2.
8. Assumptions, Constraints, Dependencies
Giả định (Assumptions)
- A1. Access Hub là nguồn sự thật cho danh tính và luật, Collector không giữ dữ liệu nghiệp vụ lâu dài (
docs/00, ADR 0004). - A2. Máy chủ được giám sát có thể kết nối HTTPS đi ra tới collector (ADR 0001). Mạng chặn hoàn toàn đường ra nằm ngoài phạm vi.
- A3. Chu kỳ gửi mặc định 30 s là đủ cho giai đoạn đầu (Q5 còn mở).
- A4. Retention mặc định 30 ngày dữ liệu thô và 400 ngày dữ liệu rollup phù hợp (Q4 còn mở).
- A5. Access Hub giữ đúng hợp đồng collector, Access Hub đã mô tả ở
docs/06, gồm cả việc đồng bộ registry hai chiều và khử trùng sự kiện theoevent_id. - A6. Nhóm thực hiện nhỏ: 2 đến 3 kỹ sư Go, DevOps bán thời gian (
docs/11). Cần xác nhận khớp thực tế (OQ-5).
Ràng buộc (Constraints)
- C1. Không thực thi mã từ xa trên máy chủ trong giai đoạn 1 đến 3 (ADR 0010).
- C2. Mọi ghi và truy vấn số liệu phải mang
company_iddo Collector gắn, không tin nhãn do agent gửi, không nhận truy vấn thô từ bên ngoài (CLAUDE.md,docs/07). - C3. Hợp đồng agent, collector là
docs/03-protocol.mdcùng tệp.proto. Sửa hợp đồng phải sửa ở dự án Collector trước, sau đó bên Agent cập nhật theo. - C4. Kho chuỗi thời gian hiện tại là VictoriaMetrics (ADR 0014, xem báo cáo lựa chọn TSDB). Bản mã nguồn mở không có downsampling và retention toàn cục (ADR 0005, R11), nên dùng hai instance và vmalert.
- C5. Ghi vào VictoriaMetrics bằng JSON import, không dùng remote-write (ADR 0015, lệch ADR 0005).
- C6. Ngân sách: chưa có thông tin. Timeline: theo
docs/11(mục 11). Yêu cầu tuân thủ pháp lý: chưa có (OQ-4).
Phụ thuộc (Dependencies)
| Phụ thuộc | Loại | Trạng thái / Rủi ro |
|---|---|---|
Access Hub: enroll, tra ngược token, nhận sự kiện, seen, heartbeat, đẩy registry và gọi Admin API | Hệ thống ngoài, theo hợp đồng docs/06 | Đã kiểm chứng chạy với Access Hub thật ở dev từ 2026-09-30; mockhub giữ làm bản mô phỏng hợp đồng để kiểm thử. Cấp lại token chờ endpoint phía Access Hub (renew trả 503) |
| Redis (registry, bus, outbox, presence, lease) hoặc bản tương thích | Hạ tầng | Sẵn sàng ở dev (master và replica). Giấy phép Redis đổi (R10), dùng Valkey được. Độ bền outbox phụ thuộc AOF |
VictoriaMetrics (vm-raw, vm-long, vmalert) | Hạ tầng | Chạy ở dev. Giới hạn bản OSS (R11) |
| Cân tải HTTPS phía trước các ingest | Hạ tầng | Nginx ở dev. Giới hạn tốc độ hiện tính theo từng instance ingest |
| Agent tuân thủ hợp đồng giao thức | Hệ thống ngoài | Sai lệch hợp đồng bị chặn bằng .proto có phiên bản và kiểm tra tương thích |
| Nơi lưu mã (module path Go, host git) | Tổ chức | Q1: hướng đi đã nêu, mã đã nằm trên host git của tổ chức |
9. Giải pháp thay thế có thể (Solution Alternatives Considered)
Quyết định cấp kiến trúc đã ghi ở các ADR (xem chỉ mục ADR). Phần này tóm tắt ở mức L1.
| Phương án | Hướng tiếp cận | Ưu điểm | Nhược điểm | Kết luận |
|---|---|---|---|---|
| A. Collector Go riêng làm data plane, agent đẩy (push) tới collector, Access Hub là control plane (đề xuất) | Build + Extend | Không mở cổng vào máy chủ, xuyên NAT, scale độc lập, MySQL được bảo vệ (ADR 0001, 0003, 0004) | Thêm dịch vụ để vận hành, nhóm chưa có kinh nghiệm Go (R12) | CHỌN. Khớp mục tiêu quy mô và bảo mật |
| B. Agent gửi thẳng vào Access Hub | Extend | Ít thành phần | PHP-FPM và MySQL không hợp đường ingest tần suất cao, tải giám sát có thể kéo sập ứng dụng nghiệp vụ (ADR 0004 phương án 1) | KHÔNG. Rủi ro cho ứng dụng nghiệp vụ |
| C. Collector kéo (scrape) từ từng máy | Build | Mô hình Prometheus quen thuộc, mất tín hiệu nhận ra bằng lần thu thập thất bại | Cần mở cổng vào và giữ thông tin đăng nhập từng máy, khó với máy sau NAT (ADR 0001 phương án 1) | KHÔNG. Bề mặt tấn công lớn hơn |
| D. Mua hoặc dùng sản phẩm giám sát có sẵn | Buy hoặc Rent | Trưởng thành, có sẵn tính năng | Chưa được đánh giá trong tài liệu hiện có, cần đánh giá về chi phí, đa tenant, tích hợp với Access Hub và chủ quyền dữ liệu | CHƯA KẾT LUẬN. Cần xác nhận (OQ-6) |
Ghi chú tính trung thực: tài liệu hiện có cho thấy A đã được chọn qua ADR 0001 đến 0004 (Chấp nhận, 2026-09-30). Phương án D chưa có bằng chứng đã được cân nhắc, nên L1 này không tự kết luận thay cho người quyết định.
10. Rủi ro & Câu Hỏi Mở (Risks & Open Questions)
Rủi ro (Risks)
Đăng ký đầy đủ 18 rủi ro (R1 đến R18) nằm ở docs/13-risks-open-questions.md. Bảng dưới chọn các rủi ro ảnh hưởng trực tiếp đến Collector; mức ảnh hưởng lấy từ đó. Chủ sở hữu rủi ro: chưa chỉ định (cần gán). Đánh giá bảo mật chi tiết ở báo cáo ANBM.
| Rủi ro | Mức độ ảnh hưởng | Phương án giảm thiểu |
|---|---|---|
| R1. Sức chứa thật thấp hơn ước tính, kiểm thử tải muộn | Cao | Mô phỏng agent (agentsim) từ giai đoạn 1, kiểm thử tải theo mốc 1k, 5k, 10k (X-5, X-7, X-9, chưa làm) |
| R2. Bùng nổ cardinality làm sập kho số liệu | Cao | Danh sách nhãn trắng, giới hạn max_series mỗi agent |
| R5. Tải lên MySQL của Access Hub khi có sự kiện diện rộng | Cao | Gom nhóm sự kiện, seen theo lô, chỉ gửi sự kiện đổi trạng thái (ADR 0008) |
| R6. Lệch đồng hồ giữa agent, collector, Access Hub làm sai cửa sổ thời gian | Trung bình | server_time trong mọi phản hồi, seq tăng chặt |
| R9. Phụ thuộc nhiều thành phần (Redis, VM, bus) làm tăng độ phức tạp vận hành | Trung bình | Một binary nhiều vai trò, gói triển khai thống nhất, tài liệu vận hành (docs/14) |
| R10. Giấy phép Redis thay đổi | Thấp | Dùng Valkey hoặc bản tương thích, chỉ dùng lệnh cơ bản |
| R11. Giới hạn VictoriaMetrics OSS (không downsampling, retention toàn cục) | Trung bình, chắc chắn xảy ra | Hai instance và luật rollup (vm-raw, vm-long), xem báo cáo TSDB |
| R15. Access Hub lỗi làm mất cảnh báo | Cao | Outbox bền vững 24 giờ, gửi lại idempotent |
| R16. Đồng bộ registry sai làm agent hợp lệ bị từ chối hoặc agent thu hồi vẫn được nhận | Cao | Đồng bộ đầy đủ định kỳ, thu hồi chủ động, kiểm thử hợp đồng |
R17. Mã dùng chung .proto giữa các dự án lệch nhau | Thấp | Một chủ sở hữu ở Collector, CI kiểm tra tương thích |
| R18. Chi phí lưu trữ TSDB vượt dự kiến | Trung bình | Theo dõi dung lượng thực, điều chỉnh interval và retention |
| Rủi ro mới R-A. Hợp đồng với Access Hub lệch khiến chuỗi enroll, registry hoặc sự kiện vỡ | Cao | Giữ mockhub làm kiểm thử hợp đồng; đã chạy với Access Hub thật ở dev; thay đổi hợp đồng theo docs/06 (đề xuất, chưa xác nhận) |
| Rủi ro mới R-B. Sự kiện resolve đến trước sự kiện open bị bỏ phía nhận | Trung bình | Sửa thứ tự hoặc xử lý chờ ở bên nhận; ghi nhận là lỗ hổng đã biết, chưa có mã sửa |
Các rủi ro còn lại (R3, R4, R7, R8, R12, R13, R14) thiên về Agent hoặc tổ chức, theo dõi ở docs/13.
Câu hỏi mở (Open Questions)
Câu hỏi sản phẩm gốc Q1 đến Q17 nằm ở docs/13. Các câu hỏi có ảnh hưởng trực tiếp tới Collector và các câu hỏi mới phát sinh khi viết tài liệu này. Số hiệu OQ giữ nguyên theo bản L1 chung trước đây để các tham chiếu không vỡ; OQ-1 (nơi đặt tài liệu) và OQ-3 (độ phủ agent) không còn thuộc L1 này:
| Mã | Câu hỏi | Cần ai trả lời | Thời hạn |
|---|---|---|---|
| Q4 | Retention mặc định 30 ngày dữ liệu thô và 400 ngày rollup có phù hợp, có yêu cầu theo công ty? | Chủ sở hữu sản phẩm | Đã chốt: trần toàn cụm 30 và 400 ngày, theo gói ở đọc và xóa theo ngày (ADR 0016) |
| Q17 | Có phải xóa vật lý dữ liệu cũ hơn retention của gói không? | Chủ sở hữu sản phẩm | Đã chốt 01/10/2026: khóa chỉ đọc 30 ngày rồi xóa, ADR 0016 |
| Q5 | Chu kỳ mặc định 30 s có đủ, có nhu cầu 10 s cho máy quan trọng? | Chủ sở hữu sản phẩm | Trước kiểm thử tải |
| Q13 | Có yêu cầu dữ liệu ở lại vùng địa lý, tức nhiều collector và kho dữ liệu theo vùng? | Chủ sở hữu sản phẩm | Trước giai đoạn 3 |
| Q15 | Có cần SSO hoặc IP allowlist cho cổng Admin API và endpoint phía Access Hub? | Bảo mật, Vận hành | Giai đoạn 1 |
| OQ-2 | Số liệu định lượng của vấn đề hiện tại (thời gian phát hiện sự cố, tổn thất) và KHHĐ liên quan? | Chủ sở hữu sản phẩm | Trước khi trình thẩm định |
| OQ-4 | Có yêu cầu SLA khách hàng hoặc tuân thủ pháp lý áp lên chính hệ thống giám sát không? | Bảo mật, Pháp chế | Trước khi chốt cấp độ ở mục 12 |
| OQ-5 | Nhóm và ngân sách thực tế có khớp giả định ở docs/11? | Chủ sở hữu sản phẩm | Trước khi chốt lộ trình |
| OQ-6 | Có cần đánh giá phương án mua hoặc dùng sản phẩm có sẵn (phương án D) và ai quyết? | EA, Chủ sở hữu sản phẩm | Trước khi trình thẩm định |
| OQ-7 | Cấp độ quan trọng đề xuất ở mục 12 có được chấp nhận? | EA | Khi thẩm định |
| OQ-8 | Mục tiêu quy mô thực tế: số agent mỗi công ty và tổng, để chốt số node ingest và worker? | Chủ sở hữu sản phẩm | Trước L2 được phê duyệt |
11. Giai đoạn triển khai & Thời gian tương ứng (Rough Timeline / Phasing)
Nguồn: docs/11-roadmap.md. Chỉ liệt kê các hạng mục thuộc Collector (mã COL) và hạng mục dùng chung (mã X) mà Collector tham gia. Thời gian là ước tính cho nhóm nhỏ, xem lại sau mỗi giai đoạn. Tổng đến hết giai đoạn 3: khoảng 23 đến 32 tuần.
| Giai đoạn | Đầu ra của Collector | Thời gian dự kiến | Trạng thái tại 2026-09-30 |
|---|---|---|---|
| 0. Nền tảng | Khung dự án Go (COL-1), dựng dev (COL-2), hợp đồng giao thức .proto (X-2), mock Access Hub (mockhub) | 1 đến 2 tuần | Khung, .proto, mockhub và dev stack đã có |
| 1. MVP | Ingest có xác thực và registry (COL-3), enroll proxy và thu hồi (COL-4), bus, worker, ghi TSDB (COL-5), mất tín hiệu, outbox (COL-6), Admin API (COL-7), tách tiến trình (COL-R), 1.000 agent mô phỏng (X-5), soak 7 ngày (X-6) | 6 đến 8 tuần | COL-1 đến COL-7 và COL-R xong. X-5 và X-6 chưa làm |
| 2. Đầy đủ | Luật ngưỡng (COL-8, xong), chống nhiễu (COL-9), rollup (COL-10), purge theo tenant và giới hạn cardinality (COL-11), kiểm thử hai tenant và fuzz (COL-12), kiểm thử tải 5.000 (X-7) | 8 đến 10 tuần | Chưa bắt đầu |
| 3. Quy mô lớn và an toàn | Bus JetStream (COL-13), Redis HA (COL-14), VM cluster (COL-15), endpoint cập nhật ký (COL-16), mTLS (COL-17), nhiều collector (COL-18), Helm và HPA (COL-19), kiểm thử tải 10.000+ (X-9) | 8 đến 12 tuần | Chưa bắt đầu |
| 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 | Ngoài phạm vi hiện tại |
Phụ thuộc: các hạng mục phía hệ thống ngoài (Access Hub, Agent) có thể chạy song song khi hợp đồng đã chốt. Kiểm thử soak 7 ngày (X-6) cần máy thật, chưa làm.
12. Cấp độ quan trọng của hệ thống
Đề xuất, chưa xác nhận: Cấp độ 3, Business Operational. Đây là đề xuất của tác giả bản nháp, cần EA và chủ sở hữu sản phẩm xác nhận (OQ-7).
| Căn cứ | Đánh giá |
|---|---|
| Tác động kinh doanh | Khi Collector dừng, các luồng nghiệp vụ chính của Access Hub (kiểm kê, PAM, IaC, phê duyệt) vẫn chạy vì giám sát tách riêng ở data plane (ADR 0004). Mất khả năng nhìn thấy sự cố, không mất doanh thu trực tiếp. Chưa có số liệu doanh thu để định lượng |
| Tác động người dùng | Ảnh hưởng theo từng tenant: thấy trạng thái cũ hoặc "không có dữ liệu", không thấy cảnh báo mới. Agent đệm khi mất kết nối và outbox giữ sự kiện 24 giờ nên gián đoạn ngắn không làm mất dữ liệu (NFR-07, NFR-08) |
| SLA và tuân thủ | Chưa có SLA khách hàng hay quy định pháp lý được nêu trong tài liệu (OQ-4). NFR-02 đặt mục tiêu nội bộ 99,9% cho đường ingest |
| Luồng nghiệp vụ cốt lõi | Không nằm trên luồng cốt lõi của Access Hub. Là năng lực bổ trợ tăng giá trị vận hành |
Điều kiện xem xét nâng lên Cấp độ 2, Business Critical: khi khách hàng dùng hệ thống làm nguồn cảnh báo duy nhất cho hạ tầng sản xuất, khi có cam kết SLA với khách hàng, hoặc khi thêm hành động từ xa (giai đoạn 4). Khi đó cần HA đầy đủ theo giai đoạn 3.
| Cấp độ | Tên | Mô tả | Chọn |
|---|---|---|---|
| 1 | Mission Critical | Sống còn: ngừng gây thiệt hại tài chính cực lớn hoặc sụp đổ luồng chính ngay | Không |
| 2 | Business Critical | Quan trọng: ảnh hưởng lớn nhưng chịu được vài phút | Không, xem xét khi đổi điều kiện |
| 3 | Business Operational | Cần thiết: ảnh hưởng hiệu quả công việc, không làm gián đoạn luồng chính | Đề xuất |
| 4 | Administrative | Phụ trợ: nội bộ, thử nghiệm | Không |
A. Định Nghĩa Thuật Ngữ & Chữ Viết Tắt
| Thuật ngữ | Giải thích |
|---|---|
| Collector | Dịch vụ Go, data plane: nhận, lưu, đánh giá, truy vấn số liệu. Đối tượng của tài liệu này |
| Access Hub | Ứng dụng đa tenant đóng vai control plane. Hệ thống ngoài đối với Collector |
| Agent | Chương trình cài trên mỗi máy chủ, thu thập và đẩy số liệu. Hệ thống ngoài đối với Collector |
| Enroll, License | Đăng ký agent mới bằng mã dùng một lần, có hạn, do Access Hub cấp, đổi lấy token riêng của agent. Collector chuyển tiếp yêu cầu enroll sang Access Hub |
| Control plane, data plane | Mặt phẳng điều khiển (danh tính, luật, giao diện) và mặt phẳng dữ liệu (số liệu khối lượng lớn) |
| Ingest, Worker, Admin | Ba vai trò của cùng một binary Collector, scale độc lập |
| Tenant | Một công ty khách hàng, dữ liệu cô lập bằng company_id |
| Gauge | Số liệu tại một thời điểm. Tốc độ do phía đọc tính, không do agent (ADR 0006) |
| Outbox | Hàng đợi bền vững của sự kiện chờ gửi lên Access Hub |
| Rollup | Dữ liệu tổng hợp theo thời gian (5 phút, 1 giờ) cho lưu trữ dài hạn |
| Cardinality | Số chuỗi số liệu riêng biệt, nguy cơ làm quá tải kho số liệu |
| Registry | Bản sao trong Collector của danh sách agent hợp lệ do Access Hub đẩy xuống |
| Presence | Theo dõi lần thấy cuối của từng agent |
| mockhub | Bản mô phỏng Access Hub dùng ở dev và kiểm thử hợp đồng |
| Viết tắt | Chữ đầy đủ | Giải thích |
|---|---|---|
| HLD | High Level Design | Thiết kế tổng quan (L1) |
| SAD | Solution Architecture Document | Thiết kế kiến trúc giải pháp (L2) |
| ADR | Architecture Decision Record | Bản ghi quyết định kiến trúc |
| ANBM | An ninh bảo mật | Báo cáo phân tích và đánh giá rủi ro an ninh |
| TSDB | Time Series Database | Cơ sở dữ liệu chuỗi thời gian |
| VM | VictoriaMetrics | Kho chuỗi thời gian đang dùng |
| NFR, FR | Non-Functional / Functional Requirement | Yêu cầu phi chức năng, chức năng (docs/02) |
| HA | High Availability | Tính sẵn sàng cao |
| KHHĐ | Kế Hoạch Hành Động | Kế hoạch hành động của tổ chức |
| NA | Not Applicable | Không áp dụng |
B. Phụ lục
Tài liệu tham chiếu (trong dự án Collector)
| Tên tài liệu | Đường dẫn |
|---|---|
| Tổng quan, phạm vi, mục tiêu | docs/00-overview.md |
| Kiến trúc hệ thống | docs/01-architecture.md |
| Yêu cầu chức năng và phi chức năng | docs/02-requirements.md |
| Giao thức agent, collector | docs/03-protocol.md |
| Mô hình dữ liệu | docs/04-data-model.md |
| Cảnh báo | docs/05-alerting.md |
| Tích hợp Access Hub (hợp đồng collector, Access Hub) | docs/06-access-hub-integration.md |
| Bảo mật | docs/07-security.md |
| Mở rộng và HA | docs/08-scaling-ha.md |
| Triển khai | docs/09-deployment.md |
| Quan sát hệ thống | docs/10-observability.md |
| Lộ trình | docs/11-roadmap.md |
| Kiểm thử | docs/12-testing.md |
| Rủi ro và câu hỏi mở | docs/13-risks-open-questions.md |
| Hướng dẫn triển khai sản xuất | docs/14-production-deployment-guide.md |
| Chỉ mục ADR | adr/README.md |
| Báo cáo lựa chọn TSDB | reports/solution-selection-tsdb.md |
| Báo cáo rủi ro ANBM | reports/risk-assessment-anbm.md |
| Khung tài liệu kiến trúc (L1, L2, L3, STD-DIAG) | Bộ tài liệu khung do người dùng cung cấp (tệp PRD), chưa có đường dẫn Confluence |
Phân loại năng lực
| Phân loại | Giải thích |
|---|---|
| Core | Chuyên môn: năng lực chính của hệ thống |
| Supporting | Hỗ trợ: tích hợp bên ngoài hoặc bên thứ ba |
| Management | Quản trị: administration, configuration, setting |
Sơ đồ bắt buộc ở L1: System Context (mục 7) và High-level workflow (mục 6). Cả hai theo STD-DIAG (Mermaid, màu và hình theo danh mục, không quá 7 nút, không lộ thành phần nội bộ).
Truy vết: mỗi mục tiêu ở mục 2 có L2 tương ứng ở cột liên kết. Bảng truy vết chi tiết từ mục L2 về mục tiêu L1 nằm ở đầu L2 Collector.