Vận hành và xử lý sự cố agent

Dành cho quản trị viên máy chủ và đội hỗ trợ. Vận hành Collector do nhóm Collector hướng dẫn, không thuộc tài liệu này.

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

Kiểm tra nhanh

accesshub-agent status

Đầu ra mẫu:

Trạng thái        : running
Phiên bản         : 1.0.0 (proto 1)
Enroll            : có (agent_id ...a1b2)
Collector         : https://collector.example.com  (kết nối tốt, RTT 42ms)
Lần gửi thành công: 12 giây trước
Hàng đợi WAL      : 0 lô (0 KB)
Cấu hình từ xa    : etag 9f3c..., nạp 4 phút trước
Độ lệch đồng hồ   : +0.3s
Lỗi gần nhất      : không

Linux: systemctl status accesshub-agent, journalctl -u accesshub-agent -n 200. Windows: Get-Service AccessHubAgent, Event Viewer (Application, nguồn AccessHubAgent), tệp log.

Bảng xử lý sự cố

Triệu chứng	Nguyên nhân thường gặp	Cách xử lý
status: not enrolled	Chưa enroll hoặc enroll bị từ chối	Chạy enroll với token hợp lệ. Xem mã thoát 5: token hết hạn, đã dùng, sai công ty
Enroll lỗi TLS	Collector dùng CA nội bộ, đồng hồ máy sai, proxy chặn	diag xem chi tiết TLS. Đặt ca_file. Kiểm tra giờ. Cấu hình proxy. Không dùng insecure_skip_verify trên sản xuất
unauthorized (401)	Token bị xoay sai, registry chưa đồng bộ, token bị thu hồi mềm	Chờ 10 phút (agent thử lại). Nếu kéo dài: kiểm tra trong Access Hub xem agent còn hoạt động, enroll lại nếu cần
revoked (403)	Quản trị viên đã thu hồi agent	Cố ý. Cần License mới nếu muốn giám sát lại
identity_mismatch	VM bị nhân bản, machine-id đổi	Xóa credentials.json, tạo machine-id mới, enroll lại
Máy hiển thị agent_down nhưng agent chạy	Chặn tường lửa ra ngoài, DNS, proxy, giờ sai, WAL đầy trì hoãn	diag: thử DNS, TCP 443, TLS, ping. Kiểm tra egress tới collector
Dữ liệu chậm hoặc có lỗ hổng	Mất mạng ngắn, gửi bù đang chạy	Bình thường, WAL sẽ bù. Xem wal trong status
WAL đầy, mẫu bị bỏ	Mất kết nối kéo dài hơn max_age hoặc dung lượng nhỏ	Khắc phục kết nối. Tăng buffer.max_bytes nếu cần
CPU agent cao	Quá nhiều mount hoặc giao diện, check chậm, interval quá ngắn	diag, xem agent_collect_duration_seconds. Tăng interval, thêm bộ lọc
RSS agent cao	Nhiều series, WAL trong bộ nhớ lớn	Kiểm tra limits.max_series. Báo lỗi kèm diag
Đĩa hiển thị thiếu	Mount bị lọc	Xem disk.exclude_mounts, include_network_fs
Windows: chỉ số bằng 0 hoặc thiếu	Bộ đếm PDH hỏng	Chạy lodctr /R (khôi phục bộ đếm), khởi động lại dịch vụ. Kiểm tra quyền nhóm Performance Monitor Users
Check service_up luôn 0 trên Linux	Agent chạy không đặc quyền, không đọc được systemd	Xem Q11, cấp quyền polkit chỉ đọc hoặc chạy đặc quyền theo tài liệu
Máy vừa khởi động lại báo sự cố giả	Bình thường trong thời gian ân hạn	Collector có ân hạn khởi động 2 lần interval, xem 05-alerting.md của collector
Nâng cấp bị treo	Quay lui tự động sau 5 phút	Xem log, gói lỗi được đánh dấu, báo lỗi

Chẩn đoán

accesshub-agent diag --output /tmp/ahdiag.zip

Gói chứa: phiên bản, cấu hình hiệu lực (đã che bí mật), trạng thái, thử DNS, TCP, TLS, ping, độ lệch giờ, 200 dòng log gần nhất, kích thước WAL, thông tin hệ điều hành, mã lỗi gần nhất. Không chứa token, nội dung số liệu hay bí mật. Được thiết kế để gửi cho đội hỗ trợ.

Thu thập một lần để so sánh với công cụ hệ điều hành:

accesshub-agent collect-once | jq .

Bật log chi tiết tạm thời

sudo systemctl edit accesshub-agent   # thêm Environment=AH_LOG_LEVEL=debug
sudo systemctl restart accesshub-agent

Log debug vẫn che token. Nhớ tắt sau khi xong.

Yêu cầu mạng

Hướng	Đích	Cổng	Ghi chú
Ra	Collector (và bản sao nếu có)	443/TCP	HTTPS TLS 1.2+
Ra	DNS	53	Phân giải tên collector
Ra	NTP (khuyến nghị)	123/UDP	Đồng hồ chính xác
Vào	Không có		Agent không lắng nghe

Proxy: dùng proxy_url hoặc biến HTTPS_PROXY của dịch vụ. Kiểm tra tường lửa cho phép egress tới tên hoặc dải IP của collector. Nếu tường lửa phân giải theo IP, cần dải IP ổn định của collector (Q15).

Kế hoạch dung lượng phía máy chủ

Tài nguyên	Ước tính mỗi agent
Đĩa	Tối đa 50 MB WAL + 20 MB log + binary khoảng 20 MB
RAM	Dưới 50 MB RSS
CPU	Dưới 1% một lõi trung bình
Băng thông	Khoảng 10 KB mỗi 30 giây sau nén, xấp xỉ 28 MB mỗi ngày mỗi máy

Sao lưu và khôi phục

Agent không có dữ liệu cần sao lưu ngoài thông tin đăng nhập (có thể enroll lại). Mất credentials thì enroll lại bằng token mới, lịch sử số liệu trên collector không mất (gắn với Server, không với agent), tùy chính sách gắn lại (xem collector 06).

Nâng cấp hàng loạt an toàn

1. Đưa bản mới lên kênh beta, triển khai cho nhóm thử (10 đến 20 máy đại diện các hệ điều hành).
2. Theo dõi 24 giờ: tỉ lệ agent gửi thành công, agent_*, log lỗi.
3. Mở rộng theo đợt 10%, 50%, 100% (công cụ triển khai của công ty, hoặc tự cập nhật ở GĐ 3).
4. Có sẵn kế hoạch quay lui: giữ gói phiên bản trước trong kho.

Quy trình xử lý sự cố nghiêm trọng

Tình huống	Hành động
Bản agent mới gây tải cao hàng loạt	Dừng đợt triển khai, hạ rollout_percent về 0 (GĐ 3) hoặc chặn phiên bản, quay lui bằng công cụ triển khai, thu thập diag từ vài máy
Token bị lộ	Thu hồi agent trong Access Hub, enroll lại với token mới. Nếu License bị lộ, thu hồi token đó
Collector ngừng phục vụ	Agent tự đệm vào WAL (tối đa 24 giờ hoặc 50 MB), không cần thao tác. Theo dõi thời gian gián đoạn so với buffer.max_age
Chứng chỉ collector sắp hết hạn	Gia hạn trước hạn. Nếu dùng CA nội bộ, đảm bảo agent có ca_file mới trước khi đổi