> ## Documentation Index > Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt > Use this file to discover all available pages before exploring further. # Cài đặt Collector > Tài liệu cài đặt AgentEye Collector. Daemon `agenteye-collector` đảm bảo rằng telemetry của các agent của bạn đến AgentEye mà không bao giờ làm chậm ứng dụng của bạn. Mã của bạn ghi các sự kiện vào một thư mục cục bộ và tiếp tục; collector nhận trách nhiệm từ đó, tải lên từng file trong vài mili giây và tồn tại qua các lần khởi động lại, sự cố mạng và lỗi máy chủ tạm thời. Các lần tải lên thất bại được thử lại với exponential backoff, và một lần quét phục hồi định kỳ tái xếp hàng bất kỳ thứ gì bị bỏ lại do sự cố hoặc triển khai. Kết quả là truyền tải bền vững, fire-and-forget: các agent của bạn tiếp tục chạy ở tốc độ tối đa trong khi collector đảm bảo không có sự kiện nào bị mất trong quá trình truyền. Về mặt cơ học, collector là một daemon nhẹ theo dõi `$AGENTEYE_HOME/events/` (mặc định: `~/.agenteye/events/`) để tìm các file `.jsonl` được viết bởi Python SDK và tải chúng lên máy chủ AgentEye. > **Đã được đổi tên:** lệnh collector bây giờ là **`agenteye-collector`** (trước đó là `agenteye`). Tên ngắn `agenteye` bây giờ thuộc về CLI AgentEye. Nếu bạn đang nâng cấp cài đặt hiện có, xem [enterprise-docs/collector-migration.md](/vi/agenteye/collector-migration). *** ## Điều kiện tiên quyết * `AGENTEYE_TOKEN` của bạn: một GitHub PAT mà bạn tự tạo (xem [enterprise-docs/github-token.md](/vi/agenteye/github-token)) * URL máy chủ và một khóa API collector (xem [enterprise-docs/api-keys.md](/vi/agenteye/api-keys)) *** ## Tùy chọn A: Binary (được khuyến nghị) Các binary tĩnh được xây dựng sẵn có sẵn cho Linux, macOS và Windows (x86\_64 và arm64). Tải xuống binary cho nền tảng của bạn trực tiếp từ repo `agenteye-enterprise/releases` dưới tag phát hành mới nhất `collector/v`. Tên artifact có sẵn: | Nền tảng | Artifact | | --------------- | --------------------------------------- | | Linux x86\_64 | `agenteye-collector-linux-x86_64` | | Linux arm64 | `agenteye-collector-linux-arm64` | | macOS x86\_64 | `agenteye-collector-darwin-x86_64` | | macOS arm64 | `agenteye-collector-darwin-arm64` | | Windows x86\_64 | `agenteye-collector-windows-x86_64.exe` | | Windows arm64 | `agenteye-collector-windows-arm64.exe` | **Tải xuống với CLI `gh`** (thay đổi phiên bản và chọn artifact của nền tảng của bạn): ```bash theme={null} VERSION=0.0.1-beta.13 GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download "collector/v${VERSION}" \ --repo agenteye-enterprise/releases \ --pattern 'agenteye-collector-linux-x86_64' chmod +x agenteye-collector-linux-x86_64 sudo mv agenteye-collector-linux-x86_64 /usr/local/bin/agenteye-collector ``` **Hoặc với `curl`:** ```bash theme={null} VERSION=0.0.1-beta.13 ARTIFACT=agenteye-collector-linux-x86_64 curl -fsSL \ -H "Authorization: token $AGENTEYE_TOKEN" \ -L "https://github.com/agenteye-enterprise/releases/releases/download/collector%2Fv${VERSION}/${ARTIFACT}" \ -o agenteye-collector chmod +x agenteye-collector sudo mv agenteye-collector /usr/local/bin/agenteye-collector ``` *** ## Tùy chọn B: Docker ```bash theme={null} echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin docker pull ghcr.io/agenteye-enterprise/collector:beta-latest ``` > Các bản dựng beta hiện tại xuất bản tag nổi `:beta-latest`; `:latest` được gán chỉ cho các phát hành ổn định. Để triển khai có thể lặp lại, hãy ưu tiên một tag phiên bản được ghim như `:v0.0.1-beta.13`. **Chạy:** ```bash theme={null} docker run -d --restart unless-stopped \ --name agenteye-collector \ -e AGENTEYE_URL=https://ingest.example.com/events \ -e AGENTEYE_KEY="$AGENTEYE_KEY" \ -e AGENTEYE_HOME=/data \ -v "$HOME/.agenteye:/data" \ ghcr.io/agenteye-enterprise/collector:beta-latest \ start ``` Image chính thức chạy dưới dạng người dùng không phải root, vì vậy hãy đặt `AGENTEYE_HOME` rõ ràng và gắn kết spool máy chủ lưu trữ vào nó. Mount volume chia sẻ cùng một thư mục `~/.agenteye/` mà Python SDK ghi vào trên máy chủ. Nếu bạn đã đặt `AGENTEYE_HOME` ở nơi khác trên máy chủ, hãy gắn kết thư mục đó thay vì `$HOME/.agenteye`. *** ## Cấu hình Tất cả các tùy chọn có thể được đặt ba cách (ưu tiên cao nhất trước): 1. Cờ CLI: `agenteye-collector start --url https://...` 2. Biến môi trường: `AGENTEYE_URL=https://...` 3. File cấu hình: `~/.agenteye/config.json` ### Tùy chọn bắt buộc | Tùy chọn | Cờ CLI | Biến env | khóa config.json | | ----------- | ------------- | -------------- | ---------------- | | URL backend | `--url ` | `AGENTEYE_URL` | `"url"` | | Khóa API | `--key ` | `AGENTEYE_KEY` | `"key"` | ### Tùy chọn tùy chọn (với mặc định) | Tùy chọn | Cờ CLI | Biến env | khóa config.json | Mặc định | | -------------------------------- | ------------------------------ | --------------------------------- | -------------------------- | -------- | | Tối đa các lần tải lên đồng thời | `--max-concurrent-uploads ` | `AGENTEYE_MAX_CONCURRENT_UPLOADS` | `"max_concurrent_uploads"` | `64` | | Khoảng thời gian quét (s) | `--sweep-interval ` | `AGENTEYE_SWEEP_INTERVAL` | `"sweep_interval_secs"` | `60` | | Tuổi file tối thiểu của quét (s) | `--sweep-min-age ` | `AGENTEYE_SWEEP_MIN_AGE` | `"sweep_min_age_secs"` | `120` | | Tối đa file trên mỗi lần quét | `--sweep-max-files ` | `AGENTEYE_SWEEP_MAX_FILES` | `"sweep_max_files"` | `64` | | Tối đa lần thử tải lên | `--max-retries ` | `AGENTEYE_MAX_RETRIES` | `"max_retries"` | `5` | | Độ trễ cơ sở thử lại (ms) | `--retry-base-delay ` | `AGENTEYE_RETRY_BASE_DELAY` | `"retry_base_delay_ms"` | `1000` | ### Tùy chọn mTLS (tùy chọn) Đối với các triển khai yêu cầu TLS lẫn nhau (mTLS), collector có thể trình bày chứng chỉ máy khách trong bắt tay TLS. Khi các tùy chọn này không được đặt, collector sử dụng HTTPS tiêu chuẩn. | Tùy chọn | Cờ CLI | Biến env | khóa config.json | | ---------------------------- | ------------------- | ------------------- | ---------------- | | Chứng chỉ máy khách (PEM) | `--tls-cert ` | `AGENTEYE_TLS_CERT` | `"tls_cert"` | | Khóa riêng máy khách (PEM) | `--tls-key ` | `AGENTEYE_TLS_KEY` | `"tls_key"` | | Chứng chỉ CA tùy chỉnh (PEM) | `--tls-ca ` | `AGENTEYE_TLS_CA` | `"tls_ca"` | `--tls-cert` và `--tls-key` phải được đặt cùng nhau. Các file phải được mã hóa PEM. `--tls-ca` là độc lập và chỉ cần khi máy chủ AgentEye trình bày chứng chỉ TLS không được cấp bởi CA được tin cậy công khai (ví dụ: tự ký bởi một trình phát hành `cert-manager` trong cụm khi bạn không có tên miền DNS thực). Collector thêm CA được cung cấp làm một liên kết tin tưởng bổ sung; các gốc công khai tiêu chuẩn vẫn được tin tưởng, vì vậy các triển khai hiện có không bị ảnh hưởng. File có thể chứa một chứng chỉ PEM đơn lẻ hoặc một chuỗi đầy đủ (nhiều khối PEM được nối). **Chạy collector như một sidecar trong pod ứng dụng của bạn?** Xem [enterprise-docs/single-pod-deployment.md](/vi/agenteye/single-pod-deployment) để biết mẫu EKS end-to-end: gói mTLS được cung cấp thông qua AWS Secrets Manager + Secrets Store CSI Driver + IRSA, với xoay vòng tự động. Khi chạy trong Kubernetes với mẫu bàn giao Secret, gắn kết Secret chứng chỉ dưới dạng một volume và trỏ các đường dẫn này đến các file được gắn kết: ```yaml theme={null} # Ví dụ: collector Deployment snippet volumes: - name: mtls-certs secret: secretName: agenteye-collector-mtls containers: - name: collector env: - name: AGENTEYE_TLS_CERT value: /etc/agenteye/tls/tls.crt - name: AGENTEYE_TLS_KEY value: /etc/agenteye/tls/tls.key # Chỉ khi chứng chỉ máy chủ không được tin cậy công khai (ví dụ: CA tự ký trong cụm). # Secret tương tự thường mang ca.crt cùng với tls.crt/tls.key. - name: AGENTEYE_TLS_CA value: /etc/agenteye/tls/ca.crt volumeMounts: - name: mtls-certs mountPath: /etc/agenteye/tls readOnly: true ``` ### Ví dụ `~/.agenteye/config.json` ```json theme={null} { "url": "https://ingest.example.com/events", "key": "sk-...", "max_concurrent_uploads": 16, "sweep_interval_secs": 30 } ``` Với mTLS: ```json theme={null} { "url": "https://ingest.example.com/events", "key": "sk-...", "tls_cert": "/etc/agenteye/tls/tls.crt", "tls_key": "/etc/agenteye/tls/tls.key" } ``` Với mTLS cộng với CA tùy chỉnh (máy chủ AgentEye tự ký): ```json theme={null} { "url": "https://ingest.example.com/events", "key": "sk-...", "tls_cert": "/etc/agenteye/tls/tls.crt", "tls_key": "/etc/agenteye/tls/tls.key", "tls_ca": "/etc/agenteye/tls/ca.crt" } ``` Nếu `AGENTEYE_HOME` được đặt, thư mục đó được sử dụng thay vì `~/.agenteye`. *** ## Thiết lập lần đầu tiên Sau khi cài đặt, hãy cấu hình collector với URL máy chủ và khóa API của bạn: ```bash theme={null} mkdir -p ~/.agenteye cat > ~/.agenteye/config.json <<'EOF' { "url": "https://ingest.example.com/events", "key": "YOUR_COLLECTOR_KEY" } EOF ``` > Sử dụng `https` cho bất kỳ triển khai nào vượt qua một mạng không đáng tin cậy để các sự kiện không được gửi dưới dạng văn bản thuần. Dạng `http://your-server-host:8080/events` thuần túy chỉ thích hợp để kiểm tra cục bộ hoàn toàn chống lại máy chủ trên cùng một máy chủ. **Kiểm tra kết nối** (xả lần đầu tiên, thoát sau khi hết các sự kiện chờ): ```bash theme={null} agenteye-collector flush ``` `flush` báo cáo tiến độ của nó cho stdout. Khi spool trống, nó in `No pending files.` và thoát `0`. Ngược lại, nó in một dòng cho mỗi file (`[UPLOADED] ` hoặc `[FAILED] ()`), theo sau bởi tóm tắt `Done: / uploaded, failed.`. Điều này làm cho `flush` là một kiểm tra tiện lợi một lần để URL, khóa và cài đặt TLS của bạn đúng trước khi bạn bắt đầu daemon. *** ## Chạy như một Daemon ### Trực tiếp ```bash theme={null} agenteye-collector start ``` ### Container / Docker Khi collector và ứng dụng của bạn chia sẻ một container, hãy chạy chúng dưới một giám sát quy trình. Tùy chọn đơn giản nhất là `supervisord`; nó được cung cấp trong mỗi bản phân phối chính, khởi động lại các quy trình bị sự cố, chuyển tiếp các tín hiệu và chờ tắt một cách duyên dáng. **`Dockerfile`:** ```Dockerfile theme={null} FROM python:3.11-slim RUN apt-get update && apt-get install -y --no-install-recommends supervisor \ && rm -rf /var/lib/apt/lists/* # Kéo binary agenteye-collector từ image chính thức. # Ghim một tag cụ thể (:beta-latest cho beta hiện tại, hoặc tag :v); # :latest chỉ được xuất bản cho các phát hành ổn định. COPY --from=ghcr.io/agenteye-enterprise/collector:beta-latest \ /usr/local/bin/agenteye-collector /usr/local/bin/agenteye-collector COPY supervisord.conf /etc/supervisor/conf.d/agenteye.conf COPY my_agent.py /app/my_agent.py CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/supervisord.conf"] ``` **`supervisord.conf`:** ```ini theme={null} [supervisord] nodaemon=true user=root [program:agenteye-collector] command=/usr/local/bin/agenteye-collector start autorestart=true stopwaitsecs=30 stdout_logfile=/dev/stdout stdout_logfile_maxbytes=0 stderr_logfile=/dev/stderr stderr_logfile_maxbytes=0 [program:app] command=python /app/my_agent.py autorestart=unexpected stopwaitsecs=30 stdout_logfile=/dev/stdout stdout_logfile_maxbytes=0 stderr_logfile=/dev/stderr stderr_logfile_maxbytes=0 ``` Tại sao các cài đặt này: * `autorestart=true` trên agenteye-collector: khởi động lại khi thoát bất kỳ (sự cố, panic, OOM). * `autorestart=unexpected` trên ứng dụng: khởi động lại chỉ khi thoát không bằng 0, vì vậy một agent một lần thoát 0 không lặp lại. * `stopwaitsecs=30`: cung cấp phòng cho collector để hết các lần tải lên chờ đợi trên SIGTERM trước khi supervisord leo thang lên SIGKILL. * `stdout_logfile=/dev/stdout`, `*_maxbytes=0`: luồng đầu ra của cả hai chương trình đến container stdout; không có file nhật ký bên trong container. Chuyển `AGENTEYE_URL` / `AGENTEYE_KEY` (và bất kỳ biến env TLS nào) trên `docker run -e` như trước; supervisord kế thừa môi trường. > **Các container riêng biệt?** Nếu bạn chạy collector như một container của riêng nó (dịch vụ Docker Compose, sidecar Kubernetes, v.v.), đừng sử dụng supervisord; chính sách khởi động lại của vận hành container đã làm công việc này. Xem [enterprise-docs/single-pod-deployment.md](/vi/agenteye/single-pod-deployment) cho mẫu sidecar EKS. **Kubernetes liveness probe** (áp dụng cho dù collector chạy một mình hoặc dưới supervisord): ```yaml theme={null} livenessProbe: exec: command: ["agenteye-collector", "health"] initialDelaySeconds: 10 periodSeconds: 30 ``` Daemon đang chạy ghi một nhịp tim vào `$AGENTEYE_HOME/health.json` mỗi 30 giây. `agenteye-collector health` đọc file đó và thoát `0` (khỏe mạnh) chỉ khi nhịp tim tươi mới và các nhiệm vụ tải lên chạy bình thường; nó thoát `1` (không khỏe) khi nhịp tim cũ hơn 90 giây (ví dụ: daemon đã dừng) hoặc trong khi watcher và sweeper đang khởi động lại sau một lần thoát không mong muốn. Nhịp tim chỉ được viết bởi `start`, vì vậy hãy chạy probe chống lại daemon lâu dài thay vì lệnh `flush` một lần. ### systemd (Linux, được khuyến nghị cho sản xuất) ```ini theme={null} # /etc/systemd/system/agenteye-collector.service [Unit] Description=AgentEye Collector After=network.target [Service] ExecStart=/usr/local/bin/agenteye-collector start Restart=on-failure RestartSec=5 EnvironmentFile=/etc/agenteye/env [Install] WantedBy=multi-user.target ``` Tạo `/etc/agenteye/env`: ``` AGENTEYE_URL=https://ingest.example.com/events AGENTEYE_KEY=YOUR_COLLECTOR_KEY ``` ```bash theme={null} sudo systemctl daemon-reload sudo systemctl enable --now agenteye-collector sudo systemctl status agenteye-collector ``` ### launchd (macOS) ```xml theme={null} Label ai.befailproof.agenteye-collector ProgramArguments /usr/local/bin/agenteye-collector start EnvironmentVariables AGENTEYE_URL https://ingest.example.com/events AGENTEYE_KEY YOUR_COLLECTOR_KEY RunAtLoad KeepAlive ``` ```bash theme={null} launchctl load ~/Library/LaunchAgents/ai.befailproof.agenteye-collector.plist ``` *** ## Nâng cấp Collector Collector không tự cập nhật. Để nâng cấp: * **Binary:** tải xuống artifact `agenteye-collector--` mới từ phát hành `collector/v` mới nhất (xem [Tùy chọn A](#option-a-binary-recommended)), thay thế `/usr/local/bin/agenteye-collector`, rồi khởi động lại dịch vụ (`sudo systemctl restart agenteye-collector`, `launchctl load` lại, hoặc khởi động lại supervisor của bạn). * **Docker:** `docker pull ghcr.io/agenteye-enterprise/collector:beta-latest` (hoặc một tag `:v` được ghim; `:latest` chỉ tồn tại cho các phát hành ổn định) và tạo lại container. `AGENTEYE_TOKEN` được yêu cầu để tải xuống các binary/image mới từ repo phát hành riêng, nhưng **không** được cần bởi daemon đang chạy. *** ## Các lệnh phụ | Lệnh | Mô tả | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agenteye-collector start` | Bắt đầu daemon lâu dài. Khi khởi động, nó xả bất kỳ sự kiện nào còn lại từ lần chạy trước, sau đó theo dõi các file mới và tải chúng lên. Watcher và sweeper tự động khởi động lại khi thoát không mong muốn, và một nhịp tim được viết vào `health.json` mỗi 30 giây. | | `agenteye-collector flush` | Một lần: tải lên tất cả các file chờ đợi và thoát. In `No pending files.` khi spool trống, ngược lại một nhật ký `[UPLOADED]`/`[FAILED]` cho mỗi file và một tóm tắt `Done: / uploaded, failed.`. | | `agenteye-collector health` | Đọc nhịp tim `health.json` của daemon. Thoát `0` khi tươi mới và khỏe mạnh; thoát `1` khi nhịp tim cũ (cũ hơn 90 giây) hoặc các nhiệm vụ đang khởi động lại. | *** ## Bố cục thư mục ``` ~/.agenteye/ ├── config.json <- file cấu hình tùy chọn ├── events/ <- file .jsonl được viết bởi SDK, được nhặt lên bởi collector └── failed/ <- file đã thất bại tất cả các lần thử tải lên ``` Các file trong `failed/` không được tự động thử lại. Để tái xếp hàng chúng theo cách thủ công, hãy di chuyển chúng trở lại `events/` và chạy `agenteye-collector flush`.