Collector 安装 - FailproofAI

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。

前置条件

您的 AGENTEYE_TOKEN：自行生成的 GitHub PAT（参见 enterprise-docs/github-token.md）
服务器 URL 和 collector API 密钥（参见 enterprise-docs/api-keys.md）

方案 A：二进制文件（推荐）

预编译的静态二进制文件适用于 Linux、macOS 和 Windows（x86_64 和 arm64）。请从 agenteye-enterprise/releases 仓库的最新 collector/v<version> 发布标签中直接下载适合您平台的二进制文件。可用的制品名称：

平台	制品
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 下载（替换版本号并选择您平台对应的制品）：

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：

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

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。

运行：

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。

配置

所有选项均可通过以下三种方式设置（优先级从高到低）：

CLI 标志：agenteye-collector start --url https://...
环境变量：AGENTEYE_URL=https://...
配置文件：~/.agenteye/config.json

必填选项

选项	CLI 标志	环境变量	config.json 键
后端 URL	`--url <URL>`	`AGENTEYE_URL`	`"url"`
API 密钥	`--key <KEY>`	`AGENTEYE_KEY`	`"key"`

可选选项（含默认值）

选项	CLI 标志	环境变量	config.json 键	默认值
最大并发上传数	`--max-concurrent-uploads <N>`	`AGENTEYE_MAX_CONCURRENT_UPLOADS`	`"max_concurrent_uploads"`	`64`
扫描间隔（秒）	`--sweep-interval <S>`	`AGENTEYE_SWEEP_INTERVAL`	`"sweep_interval_secs"`	`60`
扫描最小文件年龄（秒）	`--sweep-min-age <S>`	`AGENTEYE_SWEEP_MIN_AGE`	`"sweep_min_age_secs"`	`120`
每次扫描最大文件数	`--sweep-max-files <N>`	`AGENTEYE_SWEEP_MAX_FILES`	`"sweep_max_files"`	`64`
最大上传尝试次数	`--max-retries <N>`	`AGENTEYE_MAX_RETRIES`	`"max_retries"`	`5`
重试基础延迟（毫秒）	`--retry-base-delay <MS>`	`AGENTEYE_RETRY_BASE_DELAY`	`"retry_base_delay_ms"`	`1000`

mTLS 选项（可选）

对于需要双向 TLS（mTLS）的部署，collector 可在 TLS 握手期间出示客户端证书。若未设置这些选项，collector 将使用标准 HTTPS。

选项	CLI 标志	环境变量	config.json 键
客户端证书（PEM）	`--tls-cert <PATH>`	`AGENTEYE_TLS_CERT`	`"tls_cert"`
客户端私钥（PEM）	`--tls-key <PATH>`	`AGENTEYE_TLS_KEY`	`"tls_key"`
自定义 CA 证书（PEM）	`--tls-ca <PATH>`	`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 了解完整的 EKS 方案：通过 AWS Secrets Manager + Secrets Store CSI Driver + IRSA 交付 mTLS 证书包，并支持自动轮换。在 Kubernetes 中使用 Secret 交接模式运行时，将证书 Secret 挂载为卷，并将这些路径指向挂载的文件：

# 示例：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` 示例

{
  "url": "https://ingest.example.com/events",
  "key": "sk-...",
  "max_concurrent_uploads": 16,
  "sweep_interval_secs": 30
}

启用 mTLS：

{
  "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 服务器使用自签名证书）：

{
  "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：

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 仅适用于针对同一主机上服务器的纯本地测试。

测试连接（单次刷新，排空待发事件后退出）：

agenteye-collector flush

flush 将进度输出到 stdout。当队列为空时，打印 No pending files. 并以退出码 0 退出。否则，每个文件打印一行（[UPLOADED] <file> 或 [FAILED] <file> (<reason>)），最后输出 Done: <uploaded>/<total> uploaded, <failed> failed. 汇总信息。这使 flush 成为启动守护进程前验证 URL、密钥和 TLS 配置是否正确的便捷单次检查工具。

作为守护进程运行

直接运行

agenteye-collector start

容器 / Docker

当 collector 与您的应用程序共用一个容器时，请使用进程管理器来运行它们。最简单的选择是 supervisord；它在各主流发行版中均有提供，能重启崩溃的进程、转发信号，并等待优雅关闭。 Dockerfile：

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<version> 标签）；
# :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：

[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。

Kubernetes 存活探针（无论 collector 是独立运行还是在 supervisord 下运行均适用）：

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，生产环境推荐）

# /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

sudo systemctl daemon-reload
sudo systemctl enable --now agenteye-collector
sudo systemctl status agenteye-collector

launchd（macOS）

<!-- ~/Library/LaunchAgents/ai.befailproof.agenteye-collector.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>ai.befailproof.agenteye-collector</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/agenteye-collector</string>
    <string>start</string>
  </array>
  <key>EnvironmentVariables</key>
  <dict>
    <key>AGENTEYE_URL</key>
    <string>https://ingest.example.com/events</string>
    <key>AGENTEYE_KEY</key>
    <string>YOUR_COLLECTOR_KEY</string>
  </dict>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
</dict>
</plist>

launchctl load ~/Library/LaunchAgents/ai.befailproof.agenteye-collector.plist

升级 Collector

Collector 不会自动更新。升级步骤如下：

二进制文件： 从最新的 collector/v<version> 发布版本下载新的 agenteye-collector-<os>-<arch> 制品（参见方案 A），替换 /usr/local/bin/agenteye-collector，然后重启服务（sudo systemctl restart agenteye-collector、重新 launchctl load，或重启您的进程管理器）。
Docker： 执行 docker pull ghcr.io/agenteye-enterprise/collector:beta-latest（或固定的 :v<version> 标签；:latest 仅存在于稳定版本），然后重新创建容器。

下载私有发布仓库中的新二进制文件/镜像需要 AGENTEYE_TOKEN，但运行中的守护进程不需要该令牌。

子命令

命令	描述
`agenteye-collector start`	启动长期运行的守护进程。启动时会刷新上次运行遗留的所有事件，然后监视新文件并上传。监视器和扫描器在意外退出后自动重启，心跳每 30 秒写入 `health.json`。
`agenteye-collector flush`	单次执行：上传所有待处理文件后退出。队列为空时打印 `No pending files.`，否则输出每个文件的 `[UPLOADED]`/`[FAILED]` 日志及 `Done: <uploaded>/<total> uploaded, <failed> failed.` 汇总信息。
`agenteye-collector health`	读取守护进程的 `health.json` 心跳。心跳新鲜且健康时以退出码 `0` 退出；心跳过期（超过 90 秒）或任务正在重启时以退出码 `1` 退出。

目录结构

~/.agenteye/
├── config.json       <- 可选配置文件
├── events/           <- SDK 写入的 .jsonl 文件，由 collector 拾取
└── failed/           <- 所有上传尝试均失败的文件

failed/ 目录中的文件不会自动重试。如需手动重新加入队列，请将其移回 events/ 目录并运行 agenteye-collector flush。

​前置条件

​方案 A：二进制文件（推荐）

​方案 B：Docker

​配置

​必填选项

​可选选项（含默认值）

​mTLS 选项（可选）

​~/.agenteye/config.json 示例

​初次设置

​作为守护进程运行

​直接运行

​容器 / Docker

​systemd（Linux，生产环境推荐）

​launchd（macOS）

​升级 Collector

​子命令

​目录结构