> ## 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](/ko/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`) | 내장 기능                                | **제거됨**: 새 바이너리를 다운로드하거나 새 이미지를 pull                                                      |
| 설치 스크립트 (`install.sh`)      | 제공됨                                  | **제거됨**: 바이너리를 직접 다운로드 ([Collector Installation](/ko/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` 바이너리를 설치합니다(또는 새 이미지를 pull).
  2. 서비스 정의 / 헬스 프로브 / 스크립트를 `agenteye-collector`를 호출하도록 업데이트합니다.
  3. 서비스를 리로드하고 재시작한 후 정상 상태를 확인합니다.
  4. **그런 다음에만** 이전 `/usr/local/bin/agenteye` 바이너리를 제거합니다.

***

## 1. 새 바이너리 설치

플랫폼에 맞는 아티팩트(`agenteye-collector-linux-x86_64`, `agenteye-collector-darwin-arm64` 등; 전체 목록은 [Collector Installation → Option A](/ko/agenteye/collector-installation#option-a-binary-recommended) 참고)를 최신 `collector/v<version>` 릴리스에서 다운로드하여 `/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

새 이미지를 pull합니다(`ghcr.io/agenteye-enterprise/collector:beta-latest` 또는 고정된 `:v<version>` 태그 사용을 권장하며, `:latest`는 안정 릴리스에만 존재합니다). 이미지 엔트리포인트가 이미 `agenteye-collector`이므로, `start` 서브커맨드와 함께 기존 `docker run` 명령을 변경 없이 그대로 사용할 수 있습니다.

**중요: 헬스 프로브를 업데이트하세요.** 바이너리 이름으로 실행하는 Kubernetes liveness/readiness 프로브(또는 `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` cron 작업은 모두 삭제하세요.** 해당 서브커맨드는 더 이상 존재하지 않습니다([이후 업그레이드 방법](#upgrades-from-now-on) 참고).

***

## 3. 이전 바이너리 제거 (마지막 단계)

서비스가 `agenteye-collector`로 실행되고 정상 상태를 보고하면:

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

AgentEye CLI도 함께 사용하는 경우 이 단계가 특히 중요합니다. CLI는 자체적으로 `agenteye` 커맨드를 설치하며, 이전 컬렉터 바이너리가 `/usr/local/bin/agenteye`에 남아 있으면 `PATH`에서 `agenteye` 이름이 모호해집니다.

***

## 이후 업그레이드 방법

컬렉터는 더 이상 자체 업데이트를 지원하지 않습니다. 업그레이드 방법:

* **바이너리:** 플랫폼에 맞는 새 아티팩트(예: `agenteye-collector-linux-x86_64`; 전체 목록은 [Collector Installation → Option A](/ko/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 파드가 크래시 루프                                      | liveness 프로브가 여전히 `agenteye`를 실행하고 있음      | 프로브 커맨드를 `["agenteye-collector", "health"]`로 변경하세요.                                               |
| `agenteye: command not found`, 하지만 `agenteye-collector`는 동작함           | 스크립트/별칭이 이전 이름을 참조하고 있음                    | `agenteye-collector`로 업데이트하세요.                                                                    |
| `agenteye`를 실행하면 컬렉터가 아닌 CLI가 시작됨                                      | AgentEye CLI가 설치되어 있으며 `agenteye`를 소유하고 있음 | 데몬에는 `agenteye-collector`를 사용하고, `/usr/local/bin/agenteye`에 남아 있는 이전 컬렉터 바이너리를 제거하세요.             |