> ## 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. # Collector 安装 > AgentEye Collector 安装文档。 `agenteye-collector` 守护进程确保您的 Agent 遥测数据能够安全送达 AgentEye，且绝不会阻塞您的应用程序。您的代码将事件写入本地目录后即可继续运行；collector 接管后续工作，在毫秒级内完成每个文件的上传，并能在重启、网络中断和临时服务器错误后自动恢复。上传失败会以指数退避策略进行重试，定期的恢复扫描会将因崩溃或部署遗留的文件重新加入队列。最终实现持久可靠的"即发即忘"投递：您的 Agent 保持全速运行，同时 collector 确保没有任何事件在传输过程中丢失。 从机制上看，collector 是一个轻量级守护进程，它监听 `$AGENTEYE_HOME/events/`（默认：`~/.agenteye/events/`）目录中由 Python SDK 写入的 `.jsonl` 文件，并将其上传至 AgentEye 服务器。 > **名称变更：** collector 命令现已更名为 **`agenteye-collector`**（原名为 `agenteye`）。短名称 `agenteye` 现属于 AgentEye CLI。如果您正在升级现有安装，请参阅 [enterprise-docs/collector-migration.md](/zh/agenteye/collector-migration)。 *** ## 前置条件 * 您的 `AGENTEYE_TOKEN`：自行生成的 GitHub PAT（参见 [enterprise-docs/github-token.md](/zh/agenteye/github-token)） * 服务器 URL 和 collector API 密钥（参见 [enterprise-docs/api-keys.md](/zh/agenteye/api-keys)） *** ## 方案 A：二进制文件（推荐） 预编译的静态二进制文件适用于 Linux、macOS 和 Windows（x86\_64 和 arm64）。请从 `agenteye-enterprise/releases` 仓库的最新 `collector/v` 发布标签中直接下载适合您平台的二进制文件。 可用的制品名称： | 平台 | 制品 | | --------------- | --------------------------------------- | | 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` | **使用 `gh` CLI 下载**（替换版本号并选择您平台对应的制品）： ```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 ``` **或使用 `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 ``` *** ## 方案 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 ``` > 当前 beta 构建发布浮动标签 `:beta-latest`；`:latest` 仅分配给稳定版本。对于可重现的部署，建议使用固定版本标签，例如 `:v0.0.1-beta.13`。 **运行：** ```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 ``` 官方镜像以非 root 用户运行，因此请显式设置 `AGENTEYE_HOME` 并将主机队列目录挂载到该路径。卷挂载与主机上 Python SDK 写入的 `~/.agenteye/` 目录共享。如果您在主机上已将 `AGENTEYE_HOME` 设置为其他位置，请挂载该目录而非 `$HOME/.agenteye`。 *** ## 配置 所有选项均可通过以下三种方式设置（优先级从高到低）： 1. CLI 标志：`agenteye-collector start --url https://...` 2. 环境变量：`AGENTEYE_URL=https://...` 3. 配置文件：`~/.agenteye/config.json` ### 必填选项 | 选项 | CLI 标志 | 环境变量 | config.json 键 | | ------ | ------------- | -------------- | ------------- | | 后端 URL | `--url ` | `AGENTEYE_URL` | `"url"` | | API 密钥 | `--key ` | `AGENTEYE_KEY` | `"key"` | ### 可选选项（含默认值） | 选项 | CLI 标志 | 环境变量 | config.json 键 | 默认值 | | ----------- | ------------------------------ | --------------------------------- | -------------------------- | ------ | | 最大并发上传数 | `--max-concurrent-uploads ` | `AGENTEYE_MAX_CONCURRENT_UPLOADS` | `"max_concurrent_uploads"` | `64` | | 扫描间隔（秒） | `--sweep-interval ` | `AGENTEYE_SWEEP_INTERVAL` | `"sweep_interval_secs"` | `60` | | 扫描最小文件年龄（秒） | `--sweep-min-age ` | `AGENTEYE_SWEEP_MIN_AGE` | `"sweep_min_age_secs"` | `120` | | 每次扫描最大文件数 | `--sweep-max-files ` | `AGENTEYE_SWEEP_MAX_FILES` | `"sweep_max_files"` | `64` | | 最大上传尝试次数 | `--max-retries ` | `AGENTEYE_MAX_RETRIES` | `"max_retries"` | `5` | | 重试基础延迟（毫秒） | `--retry-base-delay ` | `AGENTEYE_RETRY_BASE_DELAY` | `"retry_base_delay_ms"` | `1000` | ### mTLS 选项（可选） 对于需要双向 TLS（mTLS）的部署，collector 可在 TLS 握手期间出示客户端证书。若未设置这些选项，collector 将使用标准 HTTPS。 | 选项 | CLI 标志 | 环境变量 | config.json 键 | | -------------- | ------------------- | ------------------- | ------------- | | 客户端证书（PEM） | `--tls-cert ` | `AGENTEYE_TLS_CERT` | `"tls_cert"` | | 客户端私钥（PEM） | `--tls-key ` | `AGENTEYE_TLS_KEY` | `"tls_key"` | | 自定义 CA 证书（PEM） | `--tls-ca ` | `AGENTEYE_TLS_CA` | `"tls_ca"` | `--tls-cert` 和 `--tls-key` 必须同时设置，且文件必须为 PEM 编码格式。 `--tls-ca` 为独立选项，仅在 AgentEye 服务器使用非公开信任 CA 颁发的 TLS 证书时才需要（例如，在没有真实 DNS 域名的情况下，由集群内 `cert-manager` 颁发机构签发的自签名证书）。collector 会将所提供的 CA 作为额外的信任锚点添加；标准公共根证书仍然受信，因此现有部署不受影响。该文件可包含单个 PEM 证书或完整证书链（多个连续的 PEM 块）。 **是否在应用程序 Pod 中以 sidecar 方式运行 collector？** 请参阅 [enterprise-docs/single-pod-deployment.md](/zh/agenteye/single-pod-deployment) 了解完整的 EKS 方案：通过 AWS Secrets Manager + Secrets Store CSI Driver + IRSA 交付 mTLS 证书包，并支持自动轮换。 在 Kubernetes 中使用 Secret 交接模式运行时，将证书 Secret 挂载为卷，并将这些路径指向挂载的文件： ```yaml theme={null} # 示例：collector Deployment 片段 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 # 仅当服务器证书不受公开信任时需要（例如集群内 # 自签名 CA）。该 Secret 通常在 tls.crt/tls.key # 旁边同时包含 ca.crt。 - name: AGENTEYE_TLS_CA value: /etc/agenteye/tls/ca.crt volumeMounts: - name: mtls-certs mountPath: /etc/agenteye/tls readOnly: true ``` ### `~/.agenteye/config.json` 示例 ```json theme={null} { "url": "https://ingest.example.com/events", "key": "sk-...", "max_concurrent_uploads": 16, "sweep_interval_secs": 30 } ``` 启用 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" } ``` 启用 mTLS 并使用自定义 CA（AgentEye 服务器使用自签名证书）： ```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" } ``` 如果设置了 `AGENTEYE_HOME`，则使用该目录替代 `~/.agenteye`。 *** ## 初次设置 安装完成后，使用服务器 URL 和 API 密钥配置 collector： ```bash theme={null} mkdir -p ~/.agenteye cat > ~/.agenteye/config.json <<'EOF' { "url": "https://ingest.example.com/events", "key": "YOUR_COLLECTOR_KEY" } EOF ``` > 对于任何跨越不受信网络的部署，请使用 `https`，以避免事件以明文形式传输。明文形式 `http://your-server-host:8080/events` 仅适用于针对同一主机上服务器的纯本地测试。 **测试连接**（单次刷新，排空待发事件后退出）： ```bash theme={null} agenteye-collector flush ``` `flush` 将进度输出到 stdout。当队列为空时，打印 `No pending files.` 并以退出码 `0` 退出。否则，每个文件打印一行（`[UPLOADED] ` 或 `[FAILED] ()`），最后输出 `Done: / uploaded, failed.` 汇总信息。这使 `flush` 成为启动守护进程前验证 URL、密钥和 TLS 配置是否正确的便捷单次检查工具。 *** ## 作为守护进程运行 ### 直接运行 ```bash theme={null} agenteye-collector start ``` ### 容器 / Docker 当 collector 与您的应用程序共用一个容器时，请使用进程管理器来运行它们。最简单的选择是 `supervisord`；它在各主流发行版中均有提供，能重启崩溃的进程、转发信号，并等待优雅关闭。 **`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/* # 从官方镜像中拉取 agenteye-collector 二进制文件。 # 固定特定标签（当前 beta 使用 :beta-latest，或使用 :v 标签）； # :latest 仅在稳定版本发布时使用。 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 ``` 各配置项说明： * agenteye-collector 的 `autorestart=true`：任何退出（崩溃、panic、OOM）均自动重启。 * 应用程序的 `autorestart=unexpected`：仅在非零退出时重启，避免以退出码 0 结束的单次 Agent 陷入循环。 * `stopwaitsecs=30`：在 supervisord 升级为 SIGKILL 之前，为 collector 在收到 SIGTERM 后排空待发上传留出空间。 * `stdout_logfile=/dev/stdout`，`*_maxbytes=0`：将两个程序的输出流式传输到容器 stdout，容器内不产生日志文件。 如前所述，在 `docker run -e` 中传递 `AGENTEYE_URL` / `AGENTEYE_KEY`（及任何 TLS 环境变量）；supervisord 会继承这些环境变量。 > **使用独立容器？** 如果您将 collector 作为独立容器运行（Docker Compose 服务、Kubernetes sidecar 等），无需使用 supervisord；容器运行时的重启策略已承担此职责。EKS sidecar 方案请参阅 [enterprise-docs/single-pod-deployment.md](/zh/agenteye/single-pod-deployment)。 **Kubernetes 存活探针**（无论 collector 是独立运行还是在 supervisord 下运行均适用）： ```yaml theme={null} livenessProbe: exec: command: ["agenteye-collector", "health"] initialDelaySeconds: 10 periodSeconds: 30 ``` 运行中的守护进程每 30 秒向 `$AGENTEYE_HOME/health.json` 写入一次心跳。`agenteye-collector health` 读取该文件，仅在心跳新鲜且上传任务正常运行时以退出码 `0`（健康）退出；当心跳超过 90 秒未更新（例如守护进程已停止）或监视器和扫描器在意外退出后正在重启时，以退出码 `1`（不健康）退出。心跳仅由 `start` 写入，因此请针对长期运行的守护进程而非单次 `flush` 命令配置探针。 ### systemd（Linux，生产环境推荐） ```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 ``` 创建 `/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 ``` *** ## 升级 Collector Collector 不会自动更新。升级步骤如下： * **二进制文件：** 从最新的 `collector/v` 发布版本下载新的 `agenteye-collector--` 制品（参见[方案 A](#option-a-binary-recommended)），替换 `/usr/local/bin/agenteye-collector`，然后重启服务（`sudo systemctl restart agenteye-collector`、重新 `launchctl load`，或重启您的进程管理器）。 * **Docker：** 执行 `docker pull ghcr.io/agenteye-enterprise/collector:beta-latest`（或固定的 `:v` 标签；`:latest` 仅存在于稳定版本），然后重新创建容器。 下载私有发布仓库中的新二进制文件/镜像需要 `AGENTEYE_TOKEN`，但运行中的守护进程**不需要**该令牌。 *** ## 子命令 | 命令 | 描述 | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `agenteye-collector start` | 启动长期运行的守护进程。启动时会刷新上次运行遗留的所有事件，然后监视新文件并上传。监视器和扫描器在意外退出后自动重启，心跳每 30 秒写入 `health.json`。 | | `agenteye-collector flush` | 单次执行：上传所有待处理文件后退出。队列为空时打印 `No pending files.`，否则输出每个文件的 `[UPLOADED]`/`[FAILED]` 日志及 `Done: / uploaded, failed.` 汇总信息。 | | `agenteye-collector health` | 读取守护进程的 `health.json` 心跳。心跳新鲜且健康时以退出码 `0` 退出；心跳过期（超过 90 秒）或任务正在重启时以退出码 `1` 退出。 | *** ## 目录结构 ``` ~/.agenteye/ ├── config.json <- 可选配置文件 ├── events/ <- SDK 写入的 .jsonl 文件，由 collector 拾取 └── failed/ <- 所有上传尝试均失败的文件 ``` `failed/` 目录中的文件不会自动重试。如需手动重新加入队列，请将其移回 `events/` 目录并运行 `agenteye-collector flush`。