迁移到 `agenteye-collector`

迁移过程不会破坏任何现有内容：无需停机，不会造成数据丢失，同时将短名称 agenteye 释放给 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`）	已提供	已移除：请直接下载二进制文件（参见采集器安装）
`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），并将其放置到 /usr/local/bin/agenteye-collector。Docker 用户：执行 docker pull ghcr.io/agenteye-enterprise/collector:beta-latest（或指定版本标签 :v<version>，推荐使用固定版本；:latest 仅适用于稳定版本）。验证安装：

agenteye-collector --version

2. 更新您的部署配置

systemd（Linux）

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

[Service]
ExecStart=/usr/local/bin/agenteye-collector start

然后重新加载并重启：

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，然后重新加载：

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

supervisord

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

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

livenessProbe:
  exec:
    command: ["agenteye-collector", "health"]

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

Cron / 手动脚本

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

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

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

sudo rm /usr/local/bin/agenteye

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

后续升级方式

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

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

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

验证

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` 处残留的旧采集器二进制文件。

​变更内容

​开始之前

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

​2. 更新您的部署配置

​systemd（Linux）

​launchd（macOS）

​supervisord

​Docker / Kubernetes

​Cron / 手动脚本

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

​后续升级方式

​验证

​回滚

​故障排查