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

# 迁移到 `agenteye-collector`

> AgentEye 迁移到 `agenteye-collector` 的文档说明。

迁移过程不会破坏任何现有内容：无需停机，不会造成数据丢失，同时将短名称 `agenteye` 释放给 [AgentEye CLI](/zh/agenteye/cli) 使用，从而让采集器守护进程与 CLI 可以在同一台机器上共存。

采集器二进制文件已**从 `agenteye` 更名为 `agenteye-collector`**。短名称 `agenteye` 现在归属于 AgentEye CLI，这是一个独立工具，用于在终端中查询会话、事件和评估结果。

本指南将引导您完成现有采集器安装的迁移流程。

***

## 变更内容

|                         | 变更前                               | 变更后                                                                |
| ----------------------- | --------------------------------- | ------------------------------------------------------------------ |
| 命令 / 二进制文件              | `agenteye`                        | `agenteye-collector`                                               |
| 默认安装路径                  | `/usr/local/bin/agenteye`         | `/usr/local/bin/agenteye-collector`                                |
| 子命令                     | `start`、`flush`、`health`、`update` | `start`、`flush`、`health`                                           |
| 自动更新（`agenteye update`） | 内置                                | **已移除**：请直接下载新二进制文件或拉取新镜像                                          |
| 安装脚本（`install.sh`）      | 已提供                               | **已移除**：请直接下载二进制文件（参见[采集器安装](/zh/agenteye/collector-installation)） |
| `AGENTEYE_TOKEN`        | 下载**及**后台更新检查均需要                  | 仅**下载**二进制文件 / 镜像时需要                                               |

配置文件保持不变：相同的 `~/.agenteye/config.json`、相同的 `AGENTEYE_URL` / `AGENTEYE_KEY` / `AGENTEYE_HOME` / TLS 环境变量，以及相同的 `~/.agenteye/events/` 缓冲队列目录。**无需修改任何配置。**

> 如果您以旧名称 `agenteye` 运行已更名的二进制文件，程序仍可正常工作，但会向 stderr 输出一行弃用警告，提示您切换到 `agenteye-collector`。

***

## 开始之前

* **现有的 `agenteye` 安装会继续运行**；升级操作不会立即造成任何中断。请有计划地执行迁移，最后再移除旧的二进制文件。
* 请按以下顺序操作，以避免停机：
  1. 安装新的 `agenteye-collector` 二进制文件（或拉取新镜像）。
  2. 更新您的服务定义 / 健康检查探针 / 脚本，使其调用 `agenteye-collector`。
  3. 重新加载并重启服务，确认服务健康运行。
  4. **完成上述步骤后**，再移除旧的 `/usr/local/bin/agenteye` 二进制文件。

***

## 1. 安装新的二进制文件

从最新的 `collector/v<version>` 版本中下载适合您平台的文件（`agenteye-collector-linux-x86_64`、`agenteye-collector-darwin-arm64` 等；完整列表请参见[采集器安装 → 选项 A](/zh/agenteye/collector-installation#option-a-binary-recommended)），并将其放置到 `/usr/local/bin/agenteye-collector`。Docker 用户：执行 `docker pull ghcr.io/agenteye-enterprise/collector:beta-latest`（或指定版本标签 `:v<version>`，推荐使用固定版本；`:latest` 仅适用于稳定版本）。

验证安装：

```bash theme={null}
agenteye-collector --version
```

***

## 2. 更新您的部署配置

### systemd（Linux）

编辑 `/etc/systemd/system/agenteye-collector.service`，将 `ExecStart` 指向新的二进制文件：

```ini theme={null}
[Service]
ExecStart=/usr/local/bin/agenteye-collector start
```

然后重新加载并重启：

```bash theme={null}
sudo systemctl daemon-reload
sudo systemctl restart agenteye-collector
sudo systemctl status agenteye-collector
```

### launchd（macOS）

> **品牌更名提示：** 如果您现有的 plist 文件位于旧路径
> `~/Library/LaunchAgents/host.exosphere.agenteye-collector.plist`，请将
> 该文件重命名为 `ai.befailproof.agenteye-collector.plist`，并在重新加载前
> 将文件内部的 `<key>Label</key>` 值也改为新的标识符。

在 `~/Library/LaunchAgents/ai.befailproof.agenteye-collector.plist` 中，将第一个 `ProgramArguments` 条目从 `/usr/local/bin/agenteye` 改为 `/usr/local/bin/agenteye-collector`，然后重新加载：

```bash theme={null}
launchctl unload ~/Library/LaunchAgents/ai.befailproof.agenteye-collector.plist
launchctl load   ~/Library/LaunchAgents/ai.befailproof.agenteye-collector.plist
```

### supervisord

在您的 `supervisord` 程序块中，将 `command` 设置为新的二进制文件：

```ini theme={null}
[program:agenteye-collector]
command=/usr/local/bin/agenteye-collector start
```

然后执行 `supervisorctl reread && supervisorctl update`。

### Docker / Kubernetes

拉取新镜像（`ghcr.io/agenteye-enterprise/collector:beta-latest` 或固定版本标签 `:v<version>`，推荐使用固定版本；`:latest` 仅适用于稳定版本）。镜像的入口点已经是 `agenteye-collector`，因此原有带 `start` 子命令的 `docker run` 命令无需任何修改即可继续使用。

**重要：请更新健康检查探针。** 如果您使用 Kubernetes 存活/就绪探针（或任何 `docker exec`）通过名称调用二进制文件，请将命令改为 `agenteye-collector`：

```yaml theme={null}
livenessProbe:
  exec:
    command: ["agenteye-collector", "health"]
```

新镜像**不**包含 `agenteye` 别名，因此仍调用 `agenteye` 的探针将会失败。请在部署新镜像的同一次发布中同步更新探针配置。

### Cron / 手动脚本

将所有 `agenteye start|flush|health` 调用替换为对应的 `agenteye-collector start|flush|health` 命令。**删除所有 `agenteye update` 的定时任务**；该子命令已不再存在（请参见[后续升级方式](#upgrades-from-now-on)）。

***

## 3. 移除旧的二进制文件（最后执行）

确认服务在 `agenteye-collector` 上正常运行且状态健康后，执行：

```bash theme={null}
sudo rm /usr/local/bin/agenteye
```

如果您同时使用 AgentEye CLI，此步骤尤为重要——CLI 会安装自己的 `agenteye` 命令；若旧的采集器二进制文件仍存留在 `/usr/local/bin/agenteye`，则 `agenteye` 这个名称在您的 `PATH` 中将产生歧义。

***

<a id="upgrades-from-now-on" />

## 后续升级方式

采集器不再自动更新。升级方式如下：

* **二进制文件：** 下载适合您平台的新文件（例如 `agenteye-collector-linux-x86_64`；完整列表请参见[采集器安装 → 选项 A](/zh/agenteye/collector-installation#option-a-binary-recommended)），替换 `/usr/local/bin/agenteye-collector`，然后重启服务。
* **Docker：** 执行 `docker pull ghcr.io/agenteye-enterprise/collector:beta-latest`（或固定版本标签 `:v<version>`，推荐使用；`:latest` 仅适用于稳定版本），然后重新创建容器。

`AGENTEYE_TOKEN` 仍然需要用于从私有发布仓库下载文件，但运行中的守护进程不再需要该令牌。

***

## 验证

```bash theme={null}
agenteye-collector --version    # 确认新二进制文件在 PATH 中
agenteye-collector health       # 退出码 0 表示健康
agenteye-collector flush        # 转发所有排队事件并正常退出
```

然后确认新事件出现在您的仪表盘中。

***

## 回滚

迁移过程不会破坏任何内容。如需回滚，只需将服务定义重新指向旧的 `/usr/local/bin/agenteye` 二进制文件（前提是尚未将其删除）并重启服务即可。事件缓冲队列和配置文件为共享资源，不受影响。

***

## 故障排查

| 现象                                                                  | 原因                                  | 解决方法                                                                                             |
| ------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------ |
| 每次运行时出现 `warning: the collector binary is now agenteye-collector …` | 您仍在使用旧名称 `agenteye` 调用二进制文件         | 改为调用 `agenteye-collector`；更新服务文件和脚本。                                                             |
| systemd 报错：`.../agenteye: No such file or directory`                | 在更新 `ExecStart` 之前就删除了旧的二进制文件       | 将 `ExecStart` 设置为 `/usr/local/bin/agenteye-collector start`，然后执行 `sudo systemctl daemon-reload`。 |
| 镜像升级后 Kubernetes Pod 崩溃重启循环                                         | 存活探针仍在运行 `agenteye`                 | 将探针命令改为 `["agenteye-collector", "health"]`。                                                      |
| `agenteye: command not found`，但 `agenteye-collector` 可以正常使用         | 脚本 / 别名仍引用旧名称                       | 将其更新为 `agenteye-collector`。                                                                      |
| 运行 `agenteye` 启动的是 CLI 而非采集器                                        | 您已安装 AgentEye CLI，它拥有 `agenteye` 命令 | 使用 `agenteye-collector` 运行守护进程，并删除 `/usr/local/bin/agenteye` 处残留的旧采集器二进制文件。                      |