Migration zu `agenteye-collector`

Die Migration ist nicht-destruktiv: Es gibt keine Ausfallzeiten und keinen Datenverlust. Außerdem wird der kurze Name agenteye für die AgentEye CLI freigegeben, sodass der Collector-Daemon und die CLI auf demselben Rechner koexistieren können. Das Collector-Binary wurde von agenteye in agenteye-collector umbenannt. Der kurze Name agenteye gehört nun zur AgentEye CLI, einem separaten Werkzeug zum Abfragen von Sessions, Events und Evaluierungen über das Terminal. Diese Anleitung führt Sie durch die Migration einer bestehenden Collector-Installation.

Was sich geändert hat

	Vorher	Nachher
Befehl / Binary	`agenteye`	`agenteye-collector`
Standard-Installationspfad	`/usr/local/bin/agenteye`	`/usr/local/bin/agenteye-collector`
Unterbefehle	`start`, `flush`, `health`, `update`	`start`, `flush`, `health`
Selbst-Update (`agenteye update`)	eingebaut	entfernt: neues Binary herunterladen oder neues Image pullen
Installationsskript (`install.sh`)	vorhanden	entfernt: Binary direkt herunterladen (siehe Collector-Installation)
`AGENTEYE_TOKEN`	zum Herunterladen und für Hintergrund-Update-Prüfungen erforderlich	nur zum Herunterladen von Binaries/Images erforderlich

Die Konfiguration bleibt unverändert: dasselbe ~/.agenteye/config.json, dieselben Umgebungsvariablen AGENTEYE_URL / AGENTEYE_KEY / AGENTEYE_HOME / TLS sowie derselbe ~/.agenteye/events/-Spool. Es sind keine Konfigurationsänderungen erforderlich.

Wenn Sie das umbenannte Binary unter dem alten Namen agenteye ausführen, funktioniert es weiterhin, gibt aber eine einzeilige Deprecation-Warnung auf stderr aus, die Sie auf den Wechsel zu agenteye-collector hinweist.

Bevor Sie beginnen

Ihre bestehende agenteye-Installation läuft weiter; beim Upgrade passiert sofort nichts. Führen Sie die Migration bewusst durch und entfernen Sie das alte Binary zuletzt.
Halten Sie diese Reihenfolge ein, um Ausfallzeiten zu vermeiden:
1. Das neue agenteye-collector-Binary installieren (oder das neue Image pullen).
2. Ihre Service-Definition, Health-Probe und Skripte auf agenteye-collector umstellen.
3. Den Service neu laden und starten; prüfen, ob er gesund ist.
4. Erst dann das alte Binary /usr/local/bin/agenteye entfernen.

1. Das neue Binary installieren

Laden Sie das Artefakt für Ihre Plattform herunter (agenteye-collector-linux-x86_64, agenteye-collector-darwin-arm64 usw.; die vollständige Liste finden Sie unter Collector-Installation → Option A) aus dem neuesten collector/v<version>-Release und legen Sie es unter /usr/local/bin/agenteye-collector ab. Docker-Nutzer: docker pull ghcr.io/agenteye-enterprise/collector:beta-latest (oder ein gepinnter :v<version>-Tag, was bevorzugt wird; :latest existiert nur für stabile Releases). Überprüfung:

agenteye-collector --version

2. Ihr Deployment aktualisieren

systemd (Linux)

Bearbeiten Sie /etc/systemd/system/agenteye-collector.service, sodass ExecStart auf das neue Binary zeigt:

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

Dann neu laden und neu starten:

sudo systemctl daemon-reload
sudo systemctl restart agenteye-collector
sudo systemctl status agenteye-collector

launchd (macOS)

Brand-Umbenennung: Wenn Ihre bestehende Plist-Datei unter dem älteren Pfad ~/Library/LaunchAgents/host.exosphere.agenteye-collector.plist liegt, benennen Sie die Datei in ai.befailproof.agenteye-collector.plist um und ändern Sie außerdem den <key>Label</key>-Wert in der Datei auf den neuen Bezeichner, bevor Sie sie neu laden.

Ändern Sie in ~/Library/LaunchAgents/ai.befailproof.agenteye-collector.plist den ersten ProgramArguments-Eintrag von /usr/local/bin/agenteye auf /usr/local/bin/agenteye-collector und laden Sie dann neu:

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

supervisord

Setzen Sie in Ihrem supervisord-Programmblock command auf das neue Binary:

[program:agenteye-collector]
command=/usr/local/bin/agenteye-collector start

Dann supervisorctl reread && supervisorctl update.

Docker / Kubernetes

Pullen Sie das neue Image (ghcr.io/agenteye-enterprise/collector:beta-latest oder ein gepinnter :v<version>-Tag, was bevorzugt wird; :latest existiert nur für stabile Releases). Der Image-Entrypoint ist bereits agenteye-collector, sodass derselbe docker run-Befehl mit dem start-Unterbefehl ohne Änderungen weiterhin funktioniert. Wichtig: Health-Probes aktualisieren. Wenn Sie eine Kubernetes-Liveness/Readiness-Probe (oder ein docker exec) verwenden, das das Binary namentlich aufruft, ändern Sie den Befehl auf agenteye-collector:

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

Das neue Image liefert keinen agenteye-Alias, sodass eine Probe, die weiterhin agenteye aufruft, fehlschlägt. Aktualisieren Sie die Probe im selben Rollout wie das neue Image.

Cron / manuelle Skripte

Ersetzen Sie alle agenteye start|flush|health-Aufrufe durch den entsprechenden agenteye-collector start|flush|health-Befehl. Löschen Sie alle agenteye update-Cron-Jobs; dieser Unterbefehl existiert nicht mehr (siehe Zukünftige Upgrades).

3. Das alte Binary entfernen (zuletzt)

Sobald der Service auf agenteye-collector läuft und als gesund gemeldet wird:

sudo rm /usr/local/bin/agenteye

Dies ist besonders wichtig, wenn Sie auch die AgentEye CLI verwenden, die ihren eigenen agenteye-Befehl installiert; das alte Collector-Binary unter /usr/local/bin/agenteye zu belassen würde den Namen agenteye auf Ihrem PATH mehrdeutig machen.

Zukünftige Upgrades

Der Collector aktualisiert sich nicht mehr selbst. Für Upgrades gilt:

Binary: Laden Sie das neue Artefakt für Ihre Plattform herunter (z. B. agenteye-collector-linux-x86_64; die vollständige Liste finden Sie unter Collector-Installation → Option A), ersetzen Sie /usr/local/bin/agenteye-collector und starten Sie den Service neu.
Docker: docker pull ghcr.io/agenteye-enterprise/collector:beta-latest (oder ein gepinnter :v<version>-Tag, was bevorzugt wird; :latest existiert nur für stabile Releases) und den Container neu erstellen.

AGENTEYE_TOKEN ist weiterhin erforderlich, um aus dem privaten Release-Repository herunterzuladen, aber der laufende Daemon benötigt ihn nicht mehr.

Überprüfung

agenteye-collector --version    # neues Binary ist im PATH
agenteye-collector health       # Exit 0 = gesund
agenteye-collector flush        # leert alle gepufferten Events und beendet sich sauber

Prüfen Sie dann, ob neue Events in Ihrem Dashboard erscheinen.

Rollback

Die Migration ist nicht-destruktiv. Falls Sie ein Rollback benötigen, verweisen Sie Ihre Service-Definition zurück auf das alte Binary /usr/local/bin/agenteye (solange Sie es noch nicht entfernt haben) und starten Sie den Service neu. Der Event-Spool und die Konfiguration werden gemeinsam genutzt und sind nicht betroffen.

Fehlerbehebung

Symptom	Ursache	Lösung
`warning: the collector binary is now agenteye-collector …` bei jedem Aufruf	Das Binary wird unter dem alten Namen `agenteye` aufgerufen	Stattdessen `agenteye-collector` verwenden; Service-Dateien und Skripte aktualisieren.
systemd schlägt fehl: `.../agenteye: No such file or directory`	Das alte Binary wurde entfernt, bevor `ExecStart` aktualisiert wurde	`ExecStart=/usr/local/bin/agenteye-collector start` setzen, dann `sudo systemctl daemon-reload`.
Kubernetes-Pod crasht nach dem Image-Upgrade in einer Schleife	Liveness-Probe ruft weiterhin `agenteye` auf	Probe-Befehl auf `["agenteye-collector", "health"]` ändern.
`agenteye: command not found`, aber `agenteye-collector` funktioniert	Skripte/Aliases referenzieren noch den alten Namen	Diese auf `agenteye-collector` aktualisieren.
Das Ausführen von `agenteye` startet die CLI, nicht den Collector	Die AgentEye CLI ist installiert; sie besitzt `agenteye`	`agenteye-collector` für den Daemon verwenden und veraltete Collector-Binaries unter `/usr/local/bin/agenteye` entfernen.

​Was sich geändert hat

​Bevor Sie beginnen

​1. Das neue Binary installieren

​2. Ihr Deployment aktualisieren

​systemd (Linux)

​launchd (macOS)

​supervisord

​Docker / Kubernetes

​Cron / manuelle Skripte

​3. Das alte Binary entfernen (zuletzt)

​Zukünftige Upgrades

​Überprüfung

​Rollback

​Fehlerbehebung