Yêu cầu hệ thống

Yêu cầu chung

Thành phần	Yêu cầu
Kiến trúc	x86_64 — dự án chỉ phát hành bản x86_64 (Linux glibc/musl, Windows MSVC). Không có bản ARM64 hay 32-bit.
Quyền	Administrator (Windows) hoặc root (Linux) để cài service
Init system	systemd hoặc OpenRC nếu muốn chạy Agent dưới dạng service trên Linux
Mạng	Kết nối tới Registry nếu bạn dùng xác thực và cấu hình từ xa
Journal	journalctl phải có sẵn nếu thu thập system log trên Linux

Chưa có ngưỡng RAM, disk hay CPU tối thiểu nào được áp dụng trong code. Khi cần ước lượng tài nguyên, tham khảo các giá trị mặc định của pipeline:

Thông số	Giá trị mặc định
Channel buffer	100.000 sự kiện ở mỗi phía (collector và shipper)
Gói gửi (batch)	500 message / 1000 ms / 10 MB
Persistent queue	Tối đa 100.000 message hoặc 256 MB
Database cache	512 MB

Windows

• Windows 10/11 hoặc Windows Server 2016 trở lên, bản x64.
• Quyền Administrator để cài service.
• PowerShell để chạy các lệnh trong hướng dẫn này.

Linux

• Bản phân phối có systemd hoặc OpenRC nếu cần cài service. Không có init system này thì chỉ chạy foreground được.
• journalctl phải có sẵn để thu thập system log.
• Quyền root để cài service.
• Thư viện runtime: glibc, libz, libsasl2, libzstd, zlib và CA certificates. Không cần cài OpenSSL riêng.

Cài đặt trên Windows

Có hai cách: cài bằng gói MSI, hoặc chạy bộ cài đặt PowerShell tải từ GitHub Releases.

Phương pháp 1: Gói MSI

1. Tải file .msi trong phần Assets của bản release mới nhất trên GitHub Releases.
2. Chạy file .msi và chọn cài đặt cho máy (per-machine).

MSI cài vào C:\Program Files\blackhole-agt\, đặt executable trong thư mục con bin\ và thêm thư mục đó vào PATH của hệ thống.

⚠️

Gói MSI chỉ cài binary. Nó không đăng ký service, không tạo file cấu hình, không mở firewall, không tạo thư mục log và không xác thực với Registry. Các bước đó bạn phải tự làm, xem [Quickstart](./quickstart).

Phương pháp 2: Bộ cài đặt PowerShell

1. Tải file cài đặt powershell trong phần Assets của bản release trên GitHub Releases.
2. Chạy file đó trong PowerShell:

powershell -ExecutionPolicy Bypass -File ".\<tên file cài đặt>.ps1"

Bộ cài đặt đặt binary vào %USERPROFILE%\.cargo\bin.

Xác minh

Mở PowerShell mới để nạp lại PATH, rồi chạy:

# Nếu cài bằng MSI
& "C:\Program Files\blackhole-agt\bin\blackhole-agt.exe" --version

# Nếu cài bằng bộ cài đặt PowerShell
& "$env:USERPROFILE\.cargo\bin\blackhole-agt.exe" --version

Kết quả mong đợi: dòng in tên binary kèm phiên bản, dạng blackhole-agt <phiên bản>.

Cài đặt trên Linux

Phương pháp 1: Bộ cài đặt shell (khuyến nghị)

1. Tải file cài đặt shell trong phần Assets của bản release trên GitHub Releases.
2. Chạy lệnh sau, thay <URL cài đặt> bằng URL của file vừa tải:

curl --proto '=https' --tlsv1.2 -LsSf "<URL cài đặt>" | sh

Binary được đặt vào ~/.cargo/bin.

Nếu bản phân phối dùng glibc quá cũ, tải bản x86_64-unknown-linux-musl từ release và dùng trực tiếp.

Phương pháp 2: Tải binary trực tiếp

chmod +x ./blackhole-agt
./blackhole-agt --version

⚠️

Agent không có image container. Chỉ Forwarder mới được phát hành dưới dạng image; collector system log của Agent cần `journalctl` nên không chạy được trong image distroless. Hãy cài Agent native trên host.

Xác minh

~/.cargo/bin/blackhole-agt --version

Kết quả mong đợi: dòng in tên binary kèm phiên bản, dạng blackhole-agt <phiên bản>.

Cài đặt thủ công

Tải binary tương ứng kiến trúc x86_64 từ GitHub Releases rồi copy vào bất kỳ thư mục nào bạn muốn.

Windows

New-Item -ItemType Directory -Path "C:\blackhole" -Force
Copy-Item .\blackhole-agt.exe -Destination "C:\blackhole\blackhole-agt.exe"

& "C:\blackhole\blackhole-agt.exe" --version

Linux

mkdir -p "$HOME/blackhole"
install -m 0755 ./blackhole-agt "$HOME/blackhole/blackhole-agt"

"$HOME/blackhole/blackhole-agt" --version

⚠️

Thư mục chứa executable quyết định đường dẫn làm việc mặc định: cấu hình tìm ở `blackhole-agt.yml`, rồi `config.yml`, rồi `config.yaml`; log ghi vào `./logs`; database ghi vào `./blackhole-agt.db`. Đổi thư mục làm việc là đổi luôn vị trí cả ba.

💡

Sau khi viết file cấu hình, chạy `blackhole-agt --config <đường dẫn cấu hình> configure schema` để tạo file `config.jsonschema` ngay cạnh file cấu hình, dùng cho trình soạn thảo YAML.

Gỡ cài đặt

Windows

& "C:\Program Files\blackhole-agt\bin\blackhole-agt.exe" service stop
& "C:\Program Files\blackhole-agt\bin\blackhole-agt.exe" service uninstall

Gỡ gói MSI bằng Apps & Features (Windows Settings).

Linux

"$HOME/.cargo/bin/blackhole-agt" service uninstall

Xóa binary khỏi thư mục bạn đã copy nó vào.

Khắc phục sự cố cài đặt

Vấn đề	Nguyên nhân	Giải pháp
Service already exists. Use --force to overwrite.	Service đã được cài trước đó	Chạy lại với service install --force
Failed to read file for hashing: blackhole-agt.yml khi start	File cấu hình không tồn tại ở đường dẫn truyền cho --config	Tạo file cấu hình tại đúng đường dẫn đó trước khi start
No registry configured khi chạy auth	Cấu hình chưa có section registry: (ít nhất api_url)	Thêm registry.api_url vào cấu hình rồi chạy lại auth
device token not available, you need to authenticate first khi push	Chưa chạy auth	Chạy auth --key <KEY> trước khi push
Không cài được service trên Linux	Không chạy bằng root, hoặc hệ thống thiếu systemd/OpenRC	Dùng root; nếu không có init system thì chạy foreground
journalctl -u blackhole-agt không có gì	Ở chế độ service, stdout bị tắt, log ghi ra file	Đọc logs/default.log và logs/default-error.log trong thư mục chứa executable
Binary không chạy trên Linux (lỗi thư viện hoặc Exec format error)	Sai kiến trúc (dùng nhầm ARM64) hoặc thiếu thư viện runtime	Dùng bản x86_64 đúng; cài libz, libsasl2, libzstd, zlib và CA certificates
Access denied khi cài service	Phiên bản shell không có quyền Administrator/root	Mở PowerShell bằng Administrator hoặc chạy lệnh với sudo

Bước tiếp theo:

• Quickstart
• Cấu hình
• Vận hành
• Xử lý sự cố