Kiến trúc agent

7 phút đọcCập nhật 01/10/2026access-hub-agent, docs/01-architecture.md

Sơ đồ khối

+---------------------------------------------------------------+
|                         accesshub-agent                       |
|                                                               |
|  +-----------+    +-----------+    +------------------------+ |
|  | Scheduler |--->| Collectors|--->| Normalizer / limiter   | |
|  | (interval |    | cpu mem   |    | tên, nhãn, giới hạn    | |
|  |  + jitter)|    | disk net  |    | series, làm tròn       | |
|  +-----------+    | uptime    |    +-----------+------------+ |
|        |          | checks    |                |              |
|        |          +-----------+                v              |
|        |                              +------------------+    |
|        |                              |  WAL (đĩa)       |    |
|        |                              |  hàng đợi lô     |    |
|        |                              +--------+---------+    |
|        v                                       |              |
|  +-------------+   +-------------+    +--------v---------+    |
|  | Config mgr  |   | Credentials |    |  Sender          |    |
|  | (local +    |   | store       |    |  (HTTP, backoff, |    |
|  |  remote,    |   | (0600/DPAPI)|    |   zstd, protobuf)|    |
|  |  ETag)      |   +-------------+    +--------+---------+    |
|  +------+------+                                |              |
|         |        +-------------+                |              |
|         +------->| Inventory   |----------------+              |
|                  +-------------+                               |
|  +-------------+   +-------------+                            |
|  | Updater     |   | Self-stats  |   (GĐ 3: Updater)          |
|  +-------------+   +-------------+                            |
+---------------------------------------------------------------+
                                | HTTPS (TLS 1.2+)
                                v
                            Collector

Thành phần

Thành phần	Trách nhiệm
Scheduler	Kích hoạt chu kỳ thu thập, pha lệch cố định theo `hash(agent_id) mod interval`, đồng hồ đơn điệu (monotonic) để không lệch khi đổi giờ
Collectors	Mỗi bộ thu (cpu, mem, disk, net, uptime, service, port...) là một mô-đun độc lập theo interface `Collector`, có thời gian chờ và cách ly lỗi (recover panic)
Normalizer	Đặt tên, lọc nhãn theo danh sách trắng, cắt giá trị nhãn, giới hạn số series, tính tốc độ từ bộ đếm (bỏ mẫu đầu tiên)
WAL	Hàng đợi lô trên đĩa: thêm cuối, đọc đầu, xóa khi được xác nhận, giới hạn dung lượng, bỏ lô cũ nhất khi đầy
Sender	Gom lô, mã hóa protobuf, nén, gửi, xử lý mã trạng thái, backoff full jitter, tôn trọng `Retry-After`
Config manager	Hợp nhất cấu hình cục bộ và từ xa, kiểm tra hợp lệ, giữ bản cấu hình từ xa gần nhất trên đĩa, dùng ETag
Credentials store	Đọc và ghi `agent_id`, `agent_token` với quyền tối thiểu (0600 trên Linux, ACL hoặc DPAPI trên Windows), xoay token
Inventory	Thu thập thông tin phần cứng và hệ điều hành ít đổi, gửi khi đổi hoặc mỗi 6 giờ
Updater (GĐ 3)	Kiểm tra bản mới, xác minh chữ ký, thay thế nguyên tử, quay lui
Self-stats	Đo chính agent (CPU, RSS, độ dài WAL, số lần thử lại) và gửi như các chỉ số `agent_*`
Service wrapper	Chạy như dịch vụ systemd hoặc Windows Service, xử lý tín hiệu dừng êm

Vòng đời

Khởi động: đọc cấu hình cục bộ, nạp thông tin đăng nhập, kiểm tra WAL, phát hiện đồng hồ.
Chưa enroll: nếu chưa có thông tin đăng nhập và có License (biến môi trường, tệp, hoặc tham số enroll), gọi POST /enroll, lưu agent_id và agent_token, xóa License khỏi nơi đọc nếu là tệp dùng một lần.
Vận hành: lặp: thu thập -> chuẩn hóa -> ghi WAL -> gửi. Song song: config định kỳ, inventory, credentials/renew.
Mất kết nối: tiếp tục thu thập, dồn vào WAL, gửi bù khi có lại (cũ trước, mới sau, có giới hạn tốc độ gửi bù để không dồn tải collector).
Lỗi xác thực 401: ngừng gửi, thử lại config mỗi 10 phút, hiển thị trạng thái unauthorized trong status.
Thu hồi 403: ngừng vĩnh viễn, trạng thái revoked, chờ enroll lại thủ công.
Dừng: nhận tín hiệu, hoàn tất lô đang gửi trong thời hạn, đảm bảo WAL nhất quán, thoát.

Luồng dữ liệu một chu kỳ

Scheduler đánh thức ở thời điểm đã định (kèm pha lệch).
Các bộ thu đọc số liệu song song với thời gian chờ mỗi bộ (mặc định 5 giây), trả về danh sách mẫu thô.
Normalizer tính gauge (tốc độ từ bộ đếm), áp lọc và giới hạn, gắn nhãn cho phép.
Lô (MetricsBatch) được ghi vào WAL với seq tăng dần.
Sender lấy lô đầu WAL, gửi. Thành công (2xx) thì xóa khỏi WAL. Lỗi tạm thời thì giữ và backoff. Lỗi vĩnh viễn (400, 413 không tách được, 422) thì bỏ lô và ghi nhận.
Phản hồi MetricsAck cho server_time (tính độ lệch đồng hồ) và config_etag (khác thì kéo config).

Xử lý thời gian

Mẫu mang thời điểm thu thập theo đồng hồ hệ thống UTC, điều chỉnh bởi độ lệch ước lượng từ server_time khi độ lệch vượt 2 giây (bù tại agent để máy sai giờ vẫn cho dữ liệu đúng thứ tự).
Khoảng giữa hai lần đo tính bằng đồng hồ đơn điệu để tốc độ không sai khi đồng hồ nhảy.
Nếu độ lệch quá lớn (vượt cửa sổ 24 giờ quá khứ hoặc 5 phút tương lai của collector) thì collector bỏ điểm, agent báo clock_skew_seconds trong self-stats.

Bộ đệm WAL

Định dạng: các đoạn tệp (segment) khoảng 1 MiB, tên là id bản ghi đầu (16 số hex) cộng đuôi .seg. Mỗi bản ghi gồm độ dài (4 byte), CRC32C (4), id (8), thời điểm ghi tính bằng ms (8), rồi lô protobuf nén bằng deflate. CRC phủ mọi thứ sau chính nó. Cài đặt ở internal/buffer/wal.go.
Ghi: thêm cuối và fsync sau mỗi lô (tần suất thấp nên không gộp nhóm). Ghi lỗi thì cắt về kích thước cũ.
Xác nhận: xóa một lô chỉ đánh dấu trong bộ nhớ. Khi đoạn đầu xong hết thì đoạn bị xóa. Mốc "đã xác nhận liên tục" lưu ở tệp checkpoint (ghi nguyên tử) để khởi động lại không gửi lại lô đã xong và id không bao giờ quay về 1. Xóa lệch thứ tự chỉ có tác dụng trong phiên chạy hiện tại, sau khởi động lại lô đó có thể được gửi lại (collector khử trùng theo seq).
Phục hồi khi khởi động: quét từng đoạn. Bản ghi sai CRC nhưng còn nằm giữa đoạn thì bỏ qua và đếm vào số lô bị bỏ. Đuôi dở (thiếu byte, sai CRC ở bản ghi cuối, toàn số 0) ở đoạn cuối thì bị cắt. Đuôi không đọc được ở đoạn giữa thì giữ phần đọc được. Bản ghi hỏng phát hiện lúc đọc cũng bị bỏ và đếm.
Giới hạn: buffer.max_bytes (mặc định 50 MB) và buffer.max_age (mặc định 24 giờ). Quá tuổi thì bỏ từng bản ghi. Vượt dung lượng thì bỏ đoạn cũ nhất, không bao giờ bỏ đoạn đang ghi. Số lô bị bỏ hiện được log và đếm trong Stats.Dropped, chưa quy ra số mẫu cho agent_dropped_samples_total.
Không mở được thư mục WAL (quyền, đĩa đầy) thì agent ghi log lỗi và dùng hàng đợi trong bộ nhớ, mất khi khởi động lại.
Đổi buffer.max_bytes hoặc buffer.max_age cần khởi động lại agent, catch_up_batches áp dụng ngay khi nạp lại cấu hình.
Nằm ở /var/lib/accesshub-agent/wal hoặc C:\ProgramData\AccessHubAgent\wal.

Cấu trúc mã nguồn dự kiến

cmd/accesshub-agent/        main, CLI (cobra hoặc urfave/cli tối giản)
internal/
  app/                      vòng đời, wiring
  config/                   nạp, hợp nhất, kiểm tra cấu hình
  creds/                    lưu thông tin đăng nhập (linux, windows)
  scheduler/
  collector/                interface + registry
    cpu/ mem/ disk/ net/ uptime/
    check/                  port tcp http cert service
    inventory/
    platform_linux/ platform_windows/   (build tags)
  normalize/
  wal/
  sender/
  proto/                    mã sinh từ .proto (hoặc gói dùng chung)
  update/                   GĐ 3
  selfstats/
  svc/                      systemd, windows service
  logx/
packaging/
  nfpm.yaml, systemd/, wix/, scripts/
test/
  fixtures/proc/            /proc và /sys ghi sẵn
  mockcollector/

Quy ước: mã đặc thù nền tảng dùng build tag (//go:build linux, //go:build windows) và tệp _linux.go, _windows.go. Giao diện chung ở gói cha, để phần lớn logic (chuẩn hóa, WAL, sender) chạy chung và kiểm thử được trên mọi hệ điều hành.

Thư viện dự kiến

Việc	Thư viện	Ghi chú
Số liệu hệ thống	`github.com/shirou/gopsutil/v3` hoặc tự đọc `/proc`	Spike S5: đo kích thước và CPU, có thể tự đọc `/proc` để giảm binary
Windows	`golang.org/x/sys/windows`, PDH qua syscall, `x/sys/windows/svc`	PDH English counters
Protobuf	`google.golang.org/protobuf`
Nén	`github.com/klauspost/compress/zstd`	Có thể gzip chuẩn để giảm phụ thuộc
CLI	`spf13/cobra` hoặc gói `flag` chuẩn	Ưu tiên nhẹ
Dịch vụ Windows	`golang.org/x/sys/windows/svc`
Log	`log/slog` (chuẩn)

Mọi phụ thuộc mới phải được xem xét (giấy phép, kích thước, bảo trì) và ghi vào tài liệu.

Kiến trúc agent ​

Sơ đồ khối ​

Thành phần ​

Vòng đời ​

Luồng dữ liệu một chu kỳ ​

Xử lý thời gian ​

Bộ đệm WAL ​

Cấu trúc mã nguồn dự kiến ​

Thư viện dự kiến ​