Hợp đồng giao tiếp Agent và Collector

Tài liệu này mô tả đầy đủ những gì agent cần biết về giao thức với Collector, đủ để đọc và kiểm thử agent mà không cần mở repo khác. Collector là hệ thống ngoài: nhóm phát triển Collector giữ phía máy chủ của cùng hợp đồng. Bản sao hợp đồng dạng .proto nằm trong repo này tại internal/wire/accesshub/agent/v1/agent.proto.ref (package accesshub.agent.v1), mã Go sinh ra ở internal/wire/accesshub/agent/v1/agent.pb.go.

5 phút đọcCập nhật 02/10/2026access-hub-agent, docs/10-wire-contract.md

Nguyên tắc

• Agent chỉ đi ra, không mở cổng. Mọi yêu cầu do agent khởi xướng qua HTTPS (TLS 1.2 trở lên, xác minh chứng chỉ).
• Thân yêu cầu và phản hồi là protobuf. Thân của POST /metrics nén gzip. Không dùng gRPC.
• Chỉ gửi gauge. Tốc độ do agent tính từ bộ đếm, mẫu đầu sau khởi động bị bỏ.
• Danh tính (công ty, máy) do Collector gán từ token. Agent không tự đặt nhãn company_id, server_id, agent_id.
• Agent không thực thi bất cứ thứ gì nhận về (ADR 0005). Dữ liệu nhận về chỉ được phân tích theo lược đồ dưới đây.

Endpoint (/agent/v1)

Endpoint	Dùng khi	Trạng thái ở agent
GET /ping	Kiểm tra kết nối, thử độ lệch giờ, diag	Có (enroll và kiểm tra)
POST /enroll	Lần đầu, đổi License lấy agent token	Có
POST /metrics	Mỗi chu kỳ, thân MetricsBatch, trả MetricsAck	Có
GET /config	Định kỳ khoảng 300 giây +-20%, hoặc khi config_etag khác, dùng If-None-Match. Trường 0 hoặc vắng: giữ giá trị cục bộ	Có (AGT-10)
POST /inventory	Khi khởi động (lệch ngẫu nhiên theo agent_id trong 1 phút), khi nội dung đổi (kiểm tra mỗi 10 phút), và tối thiểu mỗi inventory.interval (mặc định 6 giờ). Thân InventoryFacts protobuf không nén, trả 202	Có (AGT-9)
POST /credentials/renew	Xoay token trước hạn (30 ngày, chồng 24 giờ)	Agent đã gọi (AGT-10, internal/renew). Collector trả 503 vì Access Hub chưa có endpoint (đặc tả HUB ở repo collector, docs/06 mục 4.7): agent giữ token cũ và thử lại mỗi giờ
GET /update	Kiểm tra bản mới (giai đoạn 3)	Chưa xây (AGT-12). Đề xuất làm rõ ở 11-auto-update-proposal.md

Header mọi yêu cầu: Authorization: Bearer <agent_token> (riêng enroll dùng License trong thân), X-AH-Proto: 1, X-AH-Agent-Version, X-Request-Id.

Thông điệp protobuf

Thông điệp	Trường chính
OsInfo	family (linux hoặc windows), name, version, kernel, arch (amd64 hoặc arm64)
EnrollRequest	license, hostname, ip_addresses, machine_id (băm SHA-256, không gửi giá trị gốc), os, agent_version
EnrollResponse	agent_id, agent_token (chỉ hiện một lần), collector_url, config, server_time_ms
Point	Thời điểm (ms) và giá trị
Series	Tên chỉ số (không có tiền tố ah_), nhãn thuộc danh sách trắng, các Point
AgentStats	cpu_percent, rss_bytes, wal_bytes, wal_batches, dropped_samples_total, send_failures_total, clock_skew_seconds
MetricsBatch	seq, sent_at_ms, series, stats. Lô rỗng là heartbeat
MetricsAck	server_time_ms, ack_seq, config_etag, accepted_points, dropped_points, warnings
CollectorsConfig, Check, CheckType, Limits	Thành phần của cấu hình từ xa. CheckType: service, port, tcp, http, cert
AgentConfig	etag, interval_seconds, collectors, checks (tối đa 50), limits, min_agent_version, collector_url, log_level
InventoryFacts	os, CPU, tổng RAM, đĩa, card mạng, thời điểm khởi động, múi giờ, thông tin bản dựng agent
RenewResponse	agent_token, old_token_valid_until_ms, server_time_ms
UpdateManifest	version, url, sha256, signature_ed25519, min_version, rollout_percent, released_at_ms
ErrorResponse	code, message, retry_after_seconds

Tên chỉ số và nhãn hợp lệ nằm trong danh sách trắng ở 03-metrics-catalog.md. Nhãn company_id, server_id, agent_id là tên dành riêng, agent không được gửi.

Giới hạn

Thân nén tối đa 1 MiB, giải nén 8 MiB, 500 series mỗi agent, 20.000 điểm mỗi yêu cầu. Thời gian mẫu trong khoảng 24 giờ quá khứ đến 5 phút tương lai. Tần suất: 4 yêu cầu metrics mỗi phút (burst 10) và 2 config mỗi phút. Chu kỳ gửi mặc định 30 giây (cho phép 10 đến 300).

Xử lý mã trạng thái

Mã	Hành vi của agent
400	Bỏ lô
401	Dừng gửi, kiểm tra lại mỗi 10 phút
403 agent_revoked	Dừng hẳn, không thử lại
409	Lô trùng, coi như đã nhận
413	Tách đôi lô một lần rồi gửi lại
422	Bỏ lô. Khi enroll: binding_failed (không ghép được máy chủ) hoặc quota_exceeded (gói của công ty đã đủ số agent), báo lỗi, mã thoát 5, không thử lại
426	Đánh dấu cần nâng cấp agent, giữ lô
429	Theo Retry-After (tối đa 1 giờ)
5xx, lỗi mạng	Backoff: cơ sở 5 giây, nhân đôi, trần 300 giây, full jitter

Quy tắc đồng bộ

• Collector hỗ trợ phiên bản giao thức N và N-1. Mọi thay đổi phá vỡ tăng X-AH-Proto, agent xử lý 426.
• Khi hợp đồng đổi (thay đổi ở phía Collector), cập nhật agent.proto.ref, sinh lại agent.pb.go, rồi cập nhật tài liệu này và 03-metrics-catalog.md nếu ảnh hưởng chỉ số.
• make proto-check so agent.proto.ref với tệp .proto do nhóm Collector cung cấp. Đường dẫn tệp truyền qua tham số hoặc biến COLLECTOR_PROTO. Nếu không có tệp đối chiếu, script thoát với mã 2. Đây là bước thủ công, các kiểm thử thường dùng internal/mockcollector và không cần tệp này.
• Danh mục chỉ số ở 03-metrics-catalog.md phải khớp danh mục mà Collector chấp nhận. Lệch danh mục làm Collector bỏ điểm, thể hiện ở dropped_points và warnings trong MetricsAck.