L1 - Giám sát máy chủ - Access Hub Agent
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: Access Hub Agent (tác nhân giám sát chạy trên máy chủ).
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.1 (2026-09-30): bản nháp đầu tiên, dựng từ docs/00 đến docs/10, ADR 0001 đến 0005 và mã nguồn hiện có của repo này. Tài liệu độc lập, không cần đọc repo khác. |
| Tên dự án | Access Hub Agent: tác nhân thu thập số liệu và gửi về Collector |
| 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 - Agent - SAD, và bốn L3: Bộ thu, Enroll, thông tin đăng nhập, cấu hình, WAL và Sender, Dịch vụ và đóng gói |
| Tài liệu liên quan | Hợp đồng Agent - Collector, Chỉ mục ADR |
| 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, ANFR-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. Mã câu hỏi mở Q2, Q3, Q11 giữ nguyên nhãn đang dùng ở docs/ và L2, L3 của repo này, được định nghĩa ở mục 10.
Bối cảnh nền tảng (tự chứa). Agent là một trong ba thành phần của nền tảng giám sát máy chủ. Hai thành phần còn lại là hệ thống ngoài đối với tài liệu này: Access Hub (ứng dụng Laravel đa công ty, là control plane: phát hành License, biết máy chủ nào thuộc công ty nào, hiển thị trạng thái và cảnh báo) và Collector (dịch vụ Go, là data plane: nhận số liệu của hàng nghìn agent, xác thực token, lưu, đánh giá cảnh báo). Agent chỉ nói chuyện trực tiếp với Collector qua HTTPS, theo hợp đồng tóm tắt ở docs/10. Agent không bao giờ gọi Access Hub.
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 của agent, lưu token, chuỗi cung ứng gói | PROCESSING (chưa trình) | |
| Vận hành (SRE/DevOps) | chưa chỉ định | Phát hành gói, kho gói, triển khai hàng loạt, hỗ trợ | 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 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)
Access Hub quản lý kiểm kê máy chủ, quản trị truy cập đặc quyền, hạ tầng dạng mã và phê duyệt cho nhiều công ty, mỗi công ty có thể có hàng nghìn máy chủ thuộc nhiều mạng, thường sau NAT hoặc tường lửa. Ứng dụng biết máy chủ nào tồn tại và ai được truy cập, nhưng chưa biết máy chủ đang sống hay chết và khỏe hay yếu (docs/00). Muốn có dữ liệu đó cần một chương trình chạy ngay trên từng máy chủ.
Vấn đề hiện tại và hệ quả
| Vấn đề hiện tại | Hệ quả |
|---|---|
| Không có nguồn số liệu sức khỏe từ chính máy chủ (CPU, RAM, đĩa, mạng, uptime) | Quản trị viên chỉ biết máy hỏng khi người dùng báo, không đo được thời gian phát hiện (chưa có baseline, xem mục 3) |
| Máy chủ đặt sau NAT hoặc tường lửa, không thể mở cổng vào để thu | Mô hình kéo (scrape) không dùng được, cần chương trình chủ động gửi ra ngoài |
| Mạng chập chờn làm mất số liệu | Có lỗ hổng dữ liệu đúng lúc sự cố, cần đệm bền trên máy |
| Không có cách cài và cập nhật tác nhân hàng loạt, an toàn trên Linux và Windows | Triển khai thủ công, khó kiểm soát phiên bản và thu hồi |
| Tác nhân giám sát thường là bề mặt tấn công (chạy quyền cao, nhận lệnh) | Chiếm được hệ thống trung tâm có thể thành chiếm được mọi máy (xem ADR 0005) |
Lý do ưu tiên: yêu cầu sản phẩm là giám sát máy chủ gần thời gian thực ngay trong Access Hub, 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ụ. 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ố (Q14).
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 | Link tài liệu L2 |
|---|---|---|
| 1 | Cho biết máy chủ còn sống hay không và tài nguyên đang thế nào, bằng số liệu gauge đều đặn và gói rỗng làm heartbeat | L2 Agent |
| 2 | Thu thập số liệu nền tảng: CPU, tải, RAM, swap, đĩa, mạng, uptime (Linux đã có). Kiểm tra dịch vụ, cổng, chứng chỉ và kiểm kê (chưa có) | L2 Agent (mục 2.3, 3), L3 Bộ thu |
| 3 | Chạy nhẹ và dự đoán được: CPU, RAM, binary, băng thông có trần cứng, không ảnh hưởng máy sản xuất | L2 Agent (mục 4, 11) |
| 4 | Không mất số liệu vì mất mạng ngắn hạn: đệm đĩa có giới hạn, gửi bù đúng thứ tự | L2 Agent, L3 WAL và Sender |
| 5 | Không mở cổng vào máy, không nhận lệnh, không tự khai danh tính công ty hay máy (danh tính do trung tâm cấp qua token) | L2 Agent (mục 10), L3 Enroll |
| 6 | Cài đặt hàng loạt dễ dàng, an toàn trên Linux và Windows. Cập nhật, thu hồi và xoay token từ trung tâm | L2 Agent (mục 6, 12), L3 Dịch vụ và đóng gói |
Phi mục tiêu (Non-Goals)
| Nội dung | Lý do và giai đoạn |
|---|---|
| Thực thi lệnh hoặc script từ xa | Cố ý không làm ở giai đoạn 1 đến 3 (ADR 0005) |
| Thu log, APM, dấu vết ứng dụng, giám sát tiến trình theo dòng lệnh | Giai đoạn 4, quyết định theo giá trị kinh doanh |
| Nhận kết nối vào, đóng vai máy chủ | Trái nguyên tắc chỉ đi ra (ANFR-08) |
| Giám sát trong container, Kubernetes, macOS, BSD | Ngoài phạm vi (docs/00) |
| Windows Server 2012 R2 trở xuống, Windows 7 và 8 | Không hỗ trợ mặc định, chờ quyết định (OQ-3) |
| Lưu trữ số liệu dài hạn, đánh giá cảnh báo, giao diện người dùng | Thuộc hệ thống ngoài (Collector, Access Hub) |
3. Chỉ số đo lường cần đạt (Success Metrics / KPIs)
Agent 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ủa agent (docs/02, mã ANFR-). Giá trị nào không có nguồn được gắn nhãn đề xuất, chưa xác nhận. Cách đo do agent tự xuất qua chỉ số agent_* và AgentStats trong mỗi lô (docs/03).
KPI kinh doanh
| Mã | Chỉ số | Baseline | Mục tiêu | Ghi chú |
|---|---|---|---|---|
| K1 | Tỷ lệ máy chủ đã quản lý có agent hoạt động | 0% | đề xuất, chưa xác nhận | Cần chốt phạm vi máy cần giám sát (Q15) |
| K2 | 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 chu kỳ gửi cộng 30 s. Phía Collector phát hiện, agent đóng góp bằng heartbeat mỗi chu kỳ (AFR-24) | Chu kỳ mặc định 30 s (Q5) |
| K3 | 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ố |
| K4 | Thời gian cài agent lên một máy mới (từ lúc có token đến lúc có số liệu) | Không đo được | đề xuất, chưa xác nhận | Đo được sau AGT-6 |
KPI công nghệ
| Mã | Chỉ số | Baseline | Mục tiêu (nguồn) |
|---|---|---|---|
| T1 | CPU trung bình | Không áp dụng | Không quá 1% một lõi ở cấu hình chuẩn (70 series, 30 s), ANFR-01 |
| T2 | Bộ nhớ | Không áp dụng | RSS không quá 50 MB, GOMEMLIMIT mặc định 64 MiB, ANFR-02 |
| T3 | Kích thước binary, băng thông, đĩa | Không áp dụng | Binary không quá 20 MB (ANFR-03), lô không quá 10 KB sau nén (ANFR-05), WAL 50 MB mặc định (ANFR-04) |
| T4 | Khởi động và dừng | Không áp dụng | Sẵn sàng thu thập dưới 3 s (ANFR-06), dừng êm trong 10 s (ANFR-11) |
| T5 | Độ bền số liệu khi mất kết nối và mất điện | Không áp dụng | Đệm tối thiểu 2 giờ (WAL mặc định 24 giờ hoặc 50 MiB). Mất điện đột ngột không hỏng WAL, mất tối đa lô đang ghi (ANFR-07, AFR-22) |
| T6 | Cách ly lỗi | Không áp dụng | Panic ở một bộ thu không làm dừng agent (ANFR-10) |
| T7 | Bảo mật kênh truyền và bề mặt | Không áp dụng | TLS 1.2 trở lên và xác minh chứng chỉ bắt buộc (AFR-26), không mở cổng (ANFR-08), không bao giờ ghi token vào log (ANFR-14) |
| T8 | Nền tảng hỗ trợ | Không áp dụng | Binary tĩnh không CGO (ANFR-09), Linux chính thức (Ubuntu 18.04+, Debian 10+, RHEL và họ hàng 7+, Amazon Linux 2+), Windows 10 1809+, 11, Server 2016+ (chưa có mã) |
Trạng thái đạt được thực tế: T1 đến T4 chưa đo trên máy thật (nợ D-16 ở L2), kiểm thử tải mô phỏng 200 agent và soak 7 ngày thuộc tiêu chí thoát giai đoạn 1 (docs/07), chưa chạy.
4. Chỉ số chất lượng cần đạt (Quality Attribute Expectation)
Nguồn: docs/02-requirements.md, docs/08. Là cơ sở cho NFR chi tiết ở L2.
| Thuộc tính | Ngưỡng kỳ vọng |
|---|---|
| Performance (hiệu năng) | CPU không quá 1% một lõi, RSS không quá 50 MB, khởi động dưới 3 s (T1, T2, T4). Giới hạn cứng: 500 series, 20.000 điểm mỗi request, 1 MiB nén mỗi lô |
| Scalability (mở rộng) | Một tiến trình mỗi máy, không mở rộng theo chiều dọc. Đội agent mở rộng theo số máy: agent phân pha gửi lệch theo agent_id và backoff có jitter để không dồn tải lên Collector. 10.000 agent ở chu kỳ 30 s tạo khoảng 333 request mỗi giây phía Collector |
| Availability (sẵn sàng) | Systemd tự khởi động lại khi lỗi. Lỗi agent chỉ ảnh hưởng một máy |
| Reliability (độ bền) | WAL trên đĩa có CRC, phục hồi sau mất điện, gửi at-least-once, gửi bù có giới hạn tốc độ (T5) |
| Security (bảo mật) | Chỉ kết nối đi ra, TLS 1.2 trở lên, token lưu quyền 0600, không thực thi mã từ xa (ADR 0005), chạy tài khoản hệ thống không đăng nhập, sandbox systemd (T7) |
| Compliance | Chưa có yêu cầu pháp lý hoặc dữ liệu cá nhân được nêu trong tài liệu hiện có. Agent giảm thiểu dữ liệu theo thiết kế (danh sách trắng tên chỉ số và nhãn, băm machine_id). Cần xác nhận (Q16) |
| Observability | Agent tự báo cáo qua bộ chỉ số agent_* và AgentStats trong mỗi lô. Cảnh báo trên các chỉ số này do Collector đánh giá. status và diag chưa có |
| Maintainability | Hợp đồng với Collector là một tệp .proto có phiên bản (X-AH-Proto), kiểm tra lệch hợp đồng bằng make proto-check. Mọi thay đổi hành vi kèm kiểm thử và cập nhật tài liệu |
| Portability | Một mã nguồn cho mọi bản phân phối Linux và Windows (binary tĩnh, ADR 0001). Ma trận hệ điều hành ở docs/02 |
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 trong dự án |
|---|---|---|
| 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 agent (Go) | chưa chỉ định | Bộ thu, gửi, WAL, đóng gói, kiểm thử |
| Phát triển Collector và Access Hub (hệ thống ngoài) | chưa chỉ định | Giữ hợp đồng HTTPS với agent, cấp License, thu hồi agent |
| Vận hành (SRE/DevOps) | chưa chỉ định | Phát hành gói, kho gói, khóa ký, hỗ trợ triển khai hàng loạt |
| Bảo mật | chưa chỉ định | Rà soát mô hình đe dọa, khóa ký, cách lưu token |
| Quản trị viên máy chủ của khách hàng | các tenant | Người dùng cuối của agent: cài, cấu hình cục bộ, xử lý sự cố trên máy |
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 agent | Dev Collector, Access Hub | 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ã agent | I | A/R | C | C | C |
| Hợp đồng agent - Collector | I | R | A/R | I | C |
| Đóng gói và phát hành gói | I | R | I | A/R | C |
| Khóa ký, cách lưu token | I | R | C | C | A |
Người dùng chính (Personas)
| Persona | Vai trò | Nhu cầu và hành vi liên quan |
|---|---|---|
| Quản trị viên máy chủ | Người cài agent trên máy của công ty mình | Cài bằng gói hoặc install.sh, đưa License, chỉnh agent.yaml (proxy, CA, chu kỳ), xem log, xử lý sự cố (docs/09) |
| Đội triển khai hàng loạt | Người dùng công cụ tự động hóa của khách hàng | Gọi install.sh với biến ACCESSHUB_*, đưa image vào máy, cần enroll ở lần chạy đầu thay vì lúc dựng image |
| Quản trị viên công ty (qua Access Hub) | Người phát hành License và thu hồi agent | Agent nhận và tôn trọng thu hồi (HTTP 403 agent_revoked thì dừng hẳn) |
| Hệ thống chủ (Collector) | Tác nhân tự động | Nhận lô, trả ack, cấu hình, hạn mức tốc độ |
6. Định hướng thiết kế tổng quan (High-Level Solution Overview)
Mô tả giải pháp
Agent là một chương trình Go nhỏ, tĩnh, chạy như dịch vụ hệ thống trên mỗi máy chủ (docs/01, ADR 0001):
- Thu thập: mỗi chu kỳ (mặc định 30 s) đọc
/proc,/sysvàstatfsđể lấy gauge: CPU, tải, RAM, swap, đĩa, mạng, uptime, cộng bộ chỉ số tự thânagent_*. Tốc độ được tính ngay trong agent (bỏ mẫu đầu). - Đệm và gửi: mỗi lô được ghi vào WAL trên đĩa rồi gửi ra Collector qua HTTPS, protobuf nén gzip. Mất mạng thì giữ lô và gửi bù đúng thứ tự khi có lại. Backoff nhân đôi, có jitter, tôn trọng
Retry-After. - Danh tính: lần đầu agent đổi License (dùng một lần, do Access Hub cấp) lấy agent token riêng, lưu quyền 0600. Agent không tự khai công ty hay máy, danh tính gắn vào token phía trung tâm.
- Đóng gói: gói
.deb,.rpm,install.shcó kiểm checksum và chữ ký, unit systemd được sandbox.
Tiến độ thực tế tại 2026-09-30 (docs/07): đã có bộ thu Linux, enroll, gửi, WAL, cấu hình YAML, CLI và dịch vụ systemd (AGT-1 đến AGT-5). Đóng gói AGT-6 một phần: có mã, gói và kiểm thử cục bộ, chưa chạy trên ma trận distro thật và chưa kiểm .rpm bằng công cụ rpm. Ba sai lệch đã biết (AR5 đến AR7) đã được sửa ở mã, xem mục 10. Chưa có: Windows (AGT-7), kiểm tra chủ động (AGT-8), kiểm kê (AGT-9), xoay token và cấu hình từ xa (AGT-10), ký gói và kho gói (AGT-11), cập nhật tự động (AGT-12), mTLS (AGT-13).
Các thành phần chính và phân loại năng lực
| Thành phần | Năng lực | Phân loại |
|---|---|---|
| Bộ thu số liệu (Linux) và chỉ số tự thân | Thu gauge, cách ly lỗi, giới hạn series | Core |
| WAL và Sender | Đệm bền, gửi bù, backoff, xử lý mã trạng thái | Core |
| Enroll và thông tin đăng nhập | Đổi token, lưu an toàn, kiểm tra danh tính máy | Core |
| Cấu hình cục bộ và CLI | run, enroll, check-config, collect-once, service, version | Management |
| Dịch vụ và đóng gói | systemd, .deb, .rpm, install.sh, gỡ cài | Management |
| Cấu hình từ xa, kiểm tra chủ động, kiểm kê, cập nhật tự động | Chưa xây | Management (kế hoạch) |
| Kho gói, ký gói | Bên ngoài (chưa chọn, Q2, Q3) | Supporting |
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[Cài và đăng ký agent]:::bc
B[Thu thập số liệu]:::bc
C[Đệm bền trên máy]:::bc
D[Gửi về Collector]:::bc
E[Thu hồi hoặc xoay token]:::bc
R[[Kênh gửi ra ngoài HTTPS]]:::infra
A --> B
B --> C
C -.-> D
D -.-> R
R -.-> E
E --> AChú thích: xanh dương = năng lực nghiệp vụ, 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ụ |
|---|---|
| Cài và đăng ký agent | Quản trị viên cài gói, đưa License một lần, agent đổi lấy token riêng |
| Thu thập số liệu | Mỗi chu kỳ agent lấy gauge của máy, không bao giờ chạy lệnh ngoài |
| Đệm bền trên máy | Lô được ghi xuống WAL trước khi gửi, mất điện hoặc mất mạng không mất số liệu |
| Gửi về Collector | Agent chủ động gửi ra ngoài, nhận ack, theo dõi mã trạng thái |
| Thu hồi hoặc xoay token | Trung tâm thu hồi thì agent dừng hẳn. Xoay token và đăng ký lại khi cần (xoay tự động chưa xây) |
Giá trị mang lại: cho nền tảng biết máy còn sống hay không và tài nguyên ra sao, với chi phí tài nguyên nhỏ và bề mặt tấn công nhỏ (không mở cổng, không chạy lệnh từ xa, binary tĩnh không phụ thuộc thư viện hệ thống).
Chi tiết cấu trúc, công nghệ và luồng dữ liệu thuộc L2 và L3, 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
ADM([Quản trị viên máy chủ]):::entity
OS([Hệ điều hành máy chủ]):::entity
COL([Collector]):::entity
HUB([Access Hub]):::entity
REPO([Kho phân phối bản cài]):::entity
AG[Access Hub Agent]:::bc
ADM -->|Cài và cấu hình| AG
OS -.->|Số liệu hệ thống| AG
AG -.->|Lô số liệu HTTPS| COL
HUB -.->|License qua quản trị viên| ADM
REPO -.->|Gói cài| ADMChú 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. Access Hub không có đường nối trực tiếp tới agent: token đi qua quản trị viên.
Bảng mô tả
| Tác nhân / Hệ thống | Loại | Trong (Internal) | Ngoài (External) | Vai trò |
|---|---|---|---|---|
| Access Hub Agent | Software System | X | Chương trình chạy trên máy chủ: thu thập, đệm, gửi. Thay đổi trong phạm vi tài liệu này | |
| Quản trị viên máy chủ | Người dùng | X | Cài agent, đưa License, sửa agent.yaml, xử lý sự cố | |
| Hệ điều hành máy chủ | Hệ của khách hàng | X | Nguồn số liệu (/proc, /sys, statfs), nơi chạy dịch vụ systemd, nơi lưu WAL và token | |
| Collector | Hệ ngoài | X | Dịch vụ nhận lô, xác thực token agent, trả ack, cấp cấu hình. Hợp đồng ở docs/10 | |
| Access Hub | Hệ ngoài | X | Phát hành License và thu hồi agent. Agent không gọi trực tiếp, chỉ biết qua Collector | |
| Kho phân phối bản cài | Hệ ngoài | X | Lưu gói .deb, .rpm, .msi, SHA256SUMS, chữ ký. Chưa chọn nhà cung cấp (Q2), ký gói chưa quyết định (Q3) |
Bảng biên (boundary)
| Hệ ngoài | Chiều | Protocol / đảm bảo | Dữ liệu qua biên |
|---|---|---|---|
| Quản trị viên máy chủ | Vào | Dòng lệnh, agent.yaml, biến môi trường hoặc tệp hoặc stdin cho License | License, cấu hình cục bộ, lệnh service, check-config |
| Hệ điều hành máy chủ | Vào | Đọc /proc, /sys, statfs, /etc/machine-id. Ghi state_dir | Số liệu tài nguyên, danh tính máy (băm), WAL, credentials.json 0600 |
| Collector | Ra (agent khởi xướng) | HTTPS TLS 1.2 trở lên, protobuf nén gzip, header Authorization: Bearer, X-AH-Proto | Lô số liệu gauge, thống kê tự thân, yêu cầu enroll. Nhận ack, cấu hình (chưa dùng), thông báo thu hồi |
| Kho phân phối bản cài | Vào (người cài kéo về) | Chưa chốt: gói được ký, tải qua HTTPS hoặc file:// (chờ Q2, Q3) | Gói cài và siêu dữ liệu phiên bản. install.sh kiểm checksum, kiểm chữ ký khi có khóa công khai |
Chi tiết giao thức, cấu trúc nội bộ và các kết nối trên máy thuộc L2.
8. Assumptions, Constraints, Dependencies
Giả định (Assumptions)
- A1. Danh tính công ty và máy do trung tâm quyết định qua token, agent không tự khai (
docs/00, nguyên tắc 7). - A2. Máy chủ được giám sát có thể kết nối HTTPS đi ra tới Collector, trực tiếp hoặc qua proxy (
proxy_url). 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. Collector cung cấp đúng hợp đồng ở
docs/10(kể cả ack idempotent theoseq, xử lý lô gửi lặp) và chịu trách nhiệm thu hồi, hạn mức tốc độ. - A5. Quản trị viên máy chủ chịu trách nhiệm về máy của mình: quyền root khi cài, bảo vệ
agent.yaml, cấu hình tường lửa cho phép egress. - A6. Nhóm thực hiện nhỏ (vài kỹ sư Go, DevOps bán thời gian). Cần xác nhận khớp thực tế (Q17).
Ràng buộc (Constraints)
- C1. Không thực thi mã từ xa, không lắng nghe cổng, cấu hình từ xa chỉ nhận khóa trong danh sách trắng (ADR 0003, ADR 0005, ANFR-08).
- C2. Agent không bao giờ tự đặt nhãn
company_id,server_id,agent_id. Đó là tên dành riêng do Collector gán từ danh tính token. - C3. Binary tĩnh, không CGO, Linux và Windows (ADR 0001, ANFR-09).
- C4. Hợp đồng với Collector là tệp
.protocó phiên bản, tóm tắt ởdocs/10. Thay đổi hợp đồng phải thống nhất hai phía và tăngX-AH-Protokhi phá vỡ tương thích, Collector hỗ trợ N và N-1. - C5. Chỉ số chỉ là gauge, tên và nhãn nằm trong danh sách trắng ở
docs/03-metrics-catalog.md. Giới hạn cứng 500 series mỗi agent. - C6. Ngân sách tài nguyên ở mục 3 (T1 đến T4) là ràng buộc cứng, có trần systemd (
MemoryMax=96M,CPUQuota=25%). - C7. Ngân sách tiền và timeline: chưa có thông tin. Yêu cầu tuân thủ pháp lý: chưa có (Q16).
Phụ thuộc (Dependencies)
| Phụ thuộc | Loại | Trạng thái / Rủi ro |
|---|---|---|
| Collector (hợp đồng HTTPS, xác thực token, hạn mức, ack) | Hệ ngoài, nhóm khác | Đã chạy ở môi trường dev. Agent kiểm thử bằng internal/mockcollector (mô phỏng 401, 403, 413, 429, 5xx, mất kết nối) |
| Access Hub (phát hành License, thu hồi) | Hệ ngoài, nhóm khác | Agent chỉ phụ thuộc gián tiếp: token đúng định dạng ahet_..., thu hồi phản ánh qua Collector |
| Kho gói và ký gói (apt, yum, MSI) | Bên ngoài hoặc vận hành | Chưa quyết định (Q2, Q3). install.sh mặc định trỏ URL giữ chỗ |
systemd (Linux), công cụ nfpm (dựng gói), shellcheck | Hạ tầng dựng và chạy | Có trong CI và gói |
| Windows: PDH, dịch vụ Windows, MSI, ký mã, SmartScreen | Kỹ thuật, mua sắm | Rủi ro AR2, spike ở ADR 0004, chưa làm |
| Nơi lưu mã và CI (GitLab, module path Go) | Tổ chức | Đã có, CI chạy fmt-vet, lint, govulncheck, test -race, fuzz-smoke, cross-build, proto-drift (thủ công) |
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. Agent tự viết bằng Go, binary tĩnh, đẩy (push) tới Collector, có đệm đĩa (đề xuất) | Build | Không mở cổng vào máy, xuyên NAT, nhẹ, một binary cho mọi distro, kiểm soát hoàn toàn bề mặt tấn công (ADR 0001, 0002, 0005) | Phải tự xây bộ thu và đóng gói cho hai hệ điều hành, nhóm chưa có nhiều kinh nghiệm Go | CHỌN. Khớp mục tiêu nhẹ và an toàn |
| B. Agent viết bằng ngôn ngữ có runtime (Python, Java, .NET) | Build | Viết nhanh | Cần runtime trên máy khách, nặng hơn, khó đáp ứng RSS 50 MB và cài hàng loạt | KHÔNG |
| C. Dùng thư viện cgo hoặc gopsutil | Build + Extend | Ít mã tự viết | Mất binary tĩnh không CGO, thêm phụ thuộc và kích thước. Đọc /proc trực tiếp đủ cho phạm vi hiện tại (ADR 0001) | KHÔNG ở giai đoạn 1 |
| D. Collector kéo (scrape) từng máy, không agent chủ động gửi | Build | Mô hình quen thuộc | 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 | KHÔNG. Bề mặt tấn công lớn hơn |
| E. Dùng agent có sẵn (node exporter, Telegraf, agent thương mại) | 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ó: phù hợp danh tính theo token, đóng gói và thu hồi từ trung tâm, đa tenant, giấy phép | CHƯA KẾT LUẬN. Cần xác nhận (Q18) |
Ghi chú tính trung thực: tài liệu hiện có cho thấy phương án A đã được chọn qua ADR 0001 đến 0005 (Chấp nhận, 2026-09-30). Phương án E 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)
Rủi ro mức L1. Chi tiết hơn (R-01 đến R-10) và nợ kỹ thuật (D-01 đến D-16) ở mục 16 của L2. Chủ sở hữu rủi ro: chưa chỉ định (cần gán).
| Rủi ro | Mức độ ảnh hưởng | Phương án giảm thiểu |
|---|---|---|
| AR1. Ngân sách tài nguyên (CPU 1%, RSS 50 MB, lô 10 KB) chưa được đo trên máy thật | Trung bình | Trần cứng (số series, mount, giao diện, systemd). Đo trong tiêu chí thoát giai đoạn 1 |
| AR2. Windows: PDH, đa ngôn ngữ, MSI, ký mã, SmartScreen (chưa có mã) | Cao | Dùng bộ đếm tiếng Anh (ADR 0004), spike sớm |
AR3. Gói chưa được ký, chưa có kho, install.sh trỏ URL giữ chỗ (Q2, Q3, L2 R-03) | Cao | install.sh bắt buộc chữ ký hoặc --allow-unsigned tường minh, luôn kiểm checksum. AGT-11 |
| AR4. Lộ khóa ký cập nhật về sau đẩy mã độc lên hàng nghìn máy | Rất cao (xác suất thấp) | Khóa tách biệt, cập nhật theo đợt (giai đoạn 3, chưa xây) |
AR5. service install chưa ghi agent.yaml, cấu hình cục bộ chỉ có khi cài bằng gói | Trung bình | Dùng gói hoặc install.sh. Sửa mã trong AGT-6 (L3 Dịch vụ và đóng gói) |
AR6. (ĐÃ SỬA) agent.yaml từng là 0644 trong khi có thể chứa mật khẩu trong proxy_url | Thấp | Nay gói, service install và postinstall đặt 0640 root:accesshub-agent (L3 OQ-P1). Máy đã cài từ bản cũ được siết khi nâng cấp |
| AR7. (ĐÃ SỬA) Thông báo CLI cho Windows từng ghi "AGT-8" thay vì AGT-7 (L2 D-05) | Thấp | Thông báo nay ghi AGT-7 |
| AR8. Mô tả cấu hình từ xa, kiểm tra, Windows, kiểm kê, xoay token vượt xa mã hiện có (L2 R-01) | Trung bình | Nhãn trạng thái ở mọi tài liệu, cập nhật khi mã đổi |
| AR9. Bản phát hành lỗi ảnh hưởng mọi máy đã cài, chưa có cập nhật tự động, quay lui, phát hành theo đợt (L2 R-05) | Trung bình | Phát hành gói thủ công theo đợt nhỏ, giữ gói cũ trong kho |
AR10. Sao chép máy ảo cùng machine-id làm agent dừng hoặc hai máy dùng chung danh tính (L2 R-06) | Trung bình | Kiểm tra lúc khởi động, enroll ở lần chạy đầu thay vì trong image |
Câu hỏi mở (Open Questions)
| Mã | Câu hỏi | Cần ai trả lời | Thời hạn |
|---|---|---|---|
| Q2 | Ai lưu trữ kho gói (apt, yum, MSI)? Hiện chỉ có tư vấn. Chủ dự án xác nhận 2026-10-01: sẽ quyết sau, vì còn đang phát triển | Chủ sở hữu sản phẩm, Vận hành | Hoãn, trước AGT-11 và phát hành công khai đầu tiên |
| Q3 | Chứng chỉ ký mã Windows và khóa ký gói (GPG hoặc cosign) do ai giữ? Hiện chỉ có tư vấn. Chủ dự án xác nhận 2026-10-01: sẽ mua sau | Bảo mật, Vận hành | Hoãn, trước AGT-7, AGT-11 và phát hành công khai đầu tiên |
| Q5 | Chu kỳ gửi mặc định 30 s có phù hợp? (cho phép 10 s đến 300 s) | Chủ sở hữu sản phẩm | Trước khi chốt lộ trình |
| Q11 | Kiểm tra dịch vụ (service) trên Linux chạy không đặc quyền có cần polkit chỉ đọc hay chạy đặc quyền? | Đã giải (AGT-8): đọc cgroup.events của unit trong /sys/fs/cgroup, đọc được không cần quyền, không cần polkit hay D-Bus | |
| OQ-3 | Phạm vi ngoài ma trận chính thức: Windows Server 2012 R2 trở xuống, container, Kubernetes có được hỗ trợ không? | Chủ sở hữu sản phẩm | Khi có nhu cầu |
| Q14 | 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 |
| Q15 | Mục tiêu độ phủ agent (tỷ lệ máy chủ đã quản lý phải có agent)? | Chủ sở hữu sản phẩm | Trước L2 |
| Q16 | Có yêu cầu SLA khách hàng hoặc tuân thủ pháp lý (kể cả dữ liệu cá nhân trong số liệu) áp lên agent không? | Bảo mật, Pháp chế | Trước khi chốt cấp độ ở mục 12 |
| Q17 | Nhóm và ngân sách thực tế có khớp giả định A6? | Chủ sở hữu sản phẩm | Trước khi chốt lộ trình |
| Q18 | Có cần đánh giá phương án dùng agent có sẵn (phương án E) 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 |
11. Giai đoạn triển khai & Thời gian tương ứng (Rough Timeline / Phasing)
Nguồn: docs/07-roadmap.md. Thời gian là ướ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), xem lại sau mỗi giai đoạn.
| Giai đoạn | Đầu ra của agent | Thời gian dự kiến | Trạng thái tại 2026-09-30 |
|---|---|---|---|
| 0. Nền tảng | Khung Go, CLI, cấu hình nghiêm ngặt, CI đa nền tảng (AGT-1, AGT-2) | 1 đến 2 tuần | Xong |
| 1. MVP (Linux, đầu cuối) | Bộ thu Linux, enroll, gửi, backoff, WAL, systemd, .deb, .rpm, install.sh (AGT-3 đến AGT-6) | 6 đến 8 tuần | AGT-3, 4, 5 xong. AGT-6 một phần (chưa ma trận distro thật, chưa kiểm .rpm bằng rpm). Tiêu chí thoát (200 agent mô phỏng cộng 10 agent thật chạy 7 ngày, cắt mạng 30 phút, 20 lần mất điện) chưa chạy |
| 2. Windows, checks, kiểm kê, vận hành | Windows (AGT-7), checks (AGT-8), kiểm kê (AGT-9), xoay token và cấu hình từ xa (AGT-10), ký gói và kho gói (AGT-11) | 8 đến 10 tuần | Chưa bắt đầu |
| 3. An toàn quy mô lớn | Cập nhật tự động có ký, quay lui, theo đợt (AGT-12), mTLS (AGT-13), arm64 hoàn chỉnh (AGT-14) | 8 đến 12 tuần | Chưa bắt đầu |
| 4. Mở rộng (tùy chọn) | Thu log, hành động từ xa có kiểm soát (cần ADR đảo ngược ADR 0005), hỗ trợ container | Theo nhu cầu | Ngoài phạm vi hiện tại |
Phụ thuộc ngoài: AGT-10 (xoay token) cần Access Hub có endpoint renew, AGT-12 cần Collector hiện thực update (xem docs/10). AGT-11 cần quyết định Q2, Q3.
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 agent dừng, máy chủ vẫn chạy bình thường vì agent chỉ quan sát, không nằm trên luồng nghiệp vụ. Mất khả năng nhìn thấy sự cố của máy đó, 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 máy: Collector thấy máy mất tín hiệu sau một thời gian. Đệm WAL (mặc định 24 giờ hoặc 50 MiB) giữ số liệu qua gián đoạn ngắn |
| 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 (Q16) |
| Luồng nghiệp vụ cốt lõi | Không nằm trên luồng cốt lõi của máy chủ. Là năng lực bổ trợ tăng giá trị vận hành |
| Blast radius | Một máy chủ. Bản phát hành lỗi có thể ảnh hưởng mọi máy đã cài (AR9) |
Đ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, hoặc khi thêm hành động từ xa (giai đoạn 4).
| 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 |
|---|---|
| Agent | Chương trình accesshub-agent chạy như dịch vụ trên máy chủ được giám sát |
| Collector | Dịch vụ nhận số liệu từ agent, xác thực token, lưu và đánh giá cảnh báo (hệ ngoài) |
| Access Hub | Ứng dụng Laravel đa công ty, phát hành License, hiển thị trạng thái (hệ ngoài) |
| Enroll, License | Đăng ký agent mới bằng mã dùng một lần, có hạn (ahet_...), đổi lấy token riêng của agent |
| Agent token | Token dài hạn của agent sau enroll (ahat_...), dùng trong header Bearer, lưu quyền 0600 |
| 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) |
| Gauge | Số liệu tại một thời điểm. Tốc độ do agent tính cục bộ rồi gửi dưới dạng gauge |
| Series | Một chuỗi thời gian xác định bởi tên chỉ số và nhãn |
| WAL | Nhật ký ghi trước trên đĩa của agent để giữ lô chưa gửi khi mất kết nối |
| Heartbeat | Lô rỗng gửi đúng lịch để Collector biết agent còn sống |
| Catch-up | Gửi bù lô cũ trong WAL, có giới hạn số lô mỗi lượt |
| Tenant | Một công ty khách hàng, dữ liệu cô lập bằng company_id ở phía trung tâm |
| 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 |
| AFR, ANFR | Agent (Non-)Functional Requirement | Yêu cầu chức năng, phi chức năng của agent (docs/02) |
| AGT | Mã việc của agent | Hạng mục lộ trình (docs/07) |
| PDH | Performance Data Helper | Thư viện bộ đếm hiệu năng Windows |
| 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
| 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 nội bộ agent | docs/01-architecture.md |
| Yêu cầu chức năng và phi chức năng | docs/02-requirements.md |
| Danh mục chỉ số | docs/03-metrics-catalog.md |
| Cấu hình và CLI | docs/04-config-and-cli.md |
| Bảo mật | docs/05-security.md |
| Đóng gói và cài đặt | docs/06-packaging-install.md |
| Lộ trình | docs/07-roadmap.md |
| Kiểm thử | docs/08-testing.md |
| Vận hành | docs/09-operations.md |
| Hợp đồng Agent - Collector | docs/10-wire-contract.md |
| Chỉ mục ADR | adr/README.md |
| L2 Agent | L2-SAD-agent.md |
| L3 Agent | Bộ thu, Enroll, thông tin đăng nhập, cấu hình, WAL và Sender, Dịch vụ và đóng gói |
| 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. Các KPI công nghệ T1 đến T8 ở mục 3 là mã mà L2 và L3 dùng khi truy vết lên L1.