Migrazione a `agenteye-collector`

La migrazione è non-distruttiva: non comporta downtime e non comporta perdita di dati, e libera il breve nome agenteye per la CLI AgentEye in modo che il daemon collector e la CLI possono coesistere sulla stessa macchina. Il binario del collector è stato rinominato da agenteye a agenteye-collector. Il breve nome agenteye ora appartiene alla CLI AgentEye, uno strumento separato per interrogare sessioni, eventi e valutazioni dal tuo terminale. Questa guida ti accompagna attraverso la migrazione di un’installazione collector esistente.

Cosa è cambiato

	Prima	Dopo
Comando / binario	`agenteye`	`agenteye-collector`
Percorso di installazione predefinito	`/usr/local/bin/agenteye`	`/usr/local/bin/agenteye-collector`
Sottocomandi	`start`, `flush`, `health`, `update`	`start`, `flush`, `health`
Auto-aggiornamento (`agenteye update`)	integrato	rimosso: scarica il nuovo binario o tira la nuova immagine
Script di installazione (`install.sh`)	fornito	rimosso: scarica il binario direttamente (vedi Collector Installation)
`AGENTEYE_TOKEN`	necessario per scaricare e per controlli di aggiornamento in background	necessario solo per scaricare binari/immagini

La configurazione è invariata: lo stesso ~/.agenteye/config.json, le stesse variabili d’ambiente AGENTEYE_URL / AGENTEYE_KEY / AGENTEYE_HOME / TLS, e lo stesso spool ~/.agenteye/events/. Non sono richieste modifiche di configurazione.

Se esegui il binario rinominato con il vecchio nome agenteye, funziona comunque ma stampa un avviso di deprecazione su una riga su stderr ricordandoti di passare a agenteye-collector.

Prima di iniziare

La tua installazione agenteye esistente continua a funzionare; nulla si rompe nel momento in cui aggiorni. Esegui la migrazione deliberatamente, poi rimuovi il vecchio binario per ultimo.
Segui questo ordine per evitare downtime:
1. Installa il nuovo binario agenteye-collector (o tira la nuova immagine).
2. Aggiorna la tua definizione di servizio / health probe / script per chiamare agenteye-collector.
3. Ricarica e riavvia il servizio; conferma che sia in salute.
4. Solo allora rimuovi il vecchio binario /usr/local/bin/agenteye.

1. Installa il nuovo binario

Scarica l’artefatto per la tua piattaforma (agenteye-collector-linux-x86_64, agenteye-collector-darwin-arm64, e così via; vedi Collector Installation → Option A per l’elenco completo) dall’ultima release collector/v<version> e posizionalo in /usr/local/bin/agenteye-collector. Utenti Docker: docker pull ghcr.io/agenteye-enterprise/collector:beta-latest (o un tag :v<version> fisso, che è preferibile; :latest esiste solo per release stabili). Verifica:

agenteye-collector --version

2. Aggiorna il tuo deployment

systemd (Linux)

Modifica /etc/systemd/system/agenteye-collector.service in modo che ExecStart punti al nuovo binario:

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

Quindi ricarica e riavvia:

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

launchd (macOS)

Cambio di marca: Se il tuo plist esistente si trova nel percorso più vecchio ~/Library/LaunchAgents/host.exosphere.agenteye-collector.plist, rinomina il file in ai.befailproof.agenteye-collector.plist e cambia anche il valore <key>Label</key> all’interno del file al nuovo identificatore prima di ricaricare.

In ~/Library/LaunchAgents/ai.befailproof.agenteye-collector.plist, cambia la prima voce ProgramArguments da /usr/local/bin/agenteye a /usr/local/bin/agenteye-collector, quindi ricarica:

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

supervisord

Nel tuo blocco programma supervisord, imposta command al nuovo binario:

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

Quindi supervisorctl reread && supervisorctl update.

Docker / Kubernetes

Tira la nuova immagine (ghcr.io/agenteye-enterprise/collector:beta-latest o un tag :v<version> fisso, che è preferibile; :latest esiste solo per release stabili). L’entrypoint dell’immagine è già agenteye-collector, quindi lo stesso comando docker run con il sottocomando start continua a funzionare senza modifiche. Importante: aggiorna gli health probe. Se usi una probe liveness/readiness di Kubernetes (o qualsiasi docker exec) che esegue il binario per nome, cambia il comando in agenteye-collector:

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

La nuova immagine non fornisce un alias agenteye, quindi una probe che chiama ancora agenteye fallirà. Aggiorna la probe nello stesso rollout della nuova immagine.

Cron / script manuali

Sostituisci qualsiasi invocazione agenteye start|flush|health con il comando agenteye-collector start|flush|health corrispondente. Elimina qualsiasi cron job agenteye update; quel sottocomando non esiste più (vedi Upgrades from now on).

3. Rimuovi il vecchio binario (per ultimo)

Una volta che il servizio funziona su agenteye-collector e segnala buone condizioni:

sudo rm /usr/local/bin/agenteye

Questo è importante soprattutto se usi anche la CLI AgentEye, che installa il suo proprio comando agenteye; lasciare il vecchio binario del collector in /usr/local/bin/agenteye renderebbe il nome agenteye ambiguo nel tuo PATH.

Aggiornamenti da ora in poi

Il collector non si aggiorna più da solo. Per aggiornare:

Binario: scarica il nuovo artefatto per la tua piattaforma (ad esempio agenteye-collector-linux-x86_64; vedi Collector Installation → Option A per l’elenco completo), sostituisci /usr/local/bin/agenteye-collector e riavvia il servizio.
Docker: docker pull ghcr.io/agenteye-enterprise/collector:beta-latest (o un tag :v<version> fisso, che è preferibile; :latest esiste solo per release stabili) e ricrea il container.

AGENTEYE_TOKEN è ancora necessario per scaricare dal repo delle release private, ma il daemon in esecuzione non ne ha più bisogno.

Verifica

agenteye-collector --version    # nuovo binario è nel PATH
agenteye-collector health       # exit 0 = in salute
agenteye-collector flush        # inoltri gli eventi in coda e termina in modo pulito

Quindi conferma che i nuovi eventi appaiono nel tuo dashboard.

Rollback

La migrazione è non-distruttiva. Se hai bisogno di eseguire il rollback, fai puntare la tua definizione di servizio di nuovo al vecchio binario /usr/local/bin/agenteye (purché non l’abbia ancora rimosso) e riavvia. Lo spool degli eventi e la configurazione sono condivisi e non sono interessati.

Risoluzione dei problemi

Sintomo	Causa	Soluzione
`warning: the collector binary is now agenteye-collector …` ad ogni esecuzione	Stai invocando il binario con il vecchio nome `agenteye`	Chiama `agenteye-collector` invece; aggiorna file di servizio e script.
systemd fallisce: `.../agenteye: No such file or directory`	Hai rimosso il vecchio binario prima di aggiornare `ExecStart`	Imposta `ExecStart=/usr/local/bin/agenteye-collector start`, quindi `sudo systemctl daemon-reload`.
Il pod Kubernetes va in crash-loop dopo l’aggiornamento dell’immagine	Il probe liveness esegue ancora `agenteye`	Cambia il comando del probe in `["agenteye-collector", "health"]`.
`agenteye: command not found`, ma `agenteye-collector` funziona	Script/alias fanno ancora riferimento al vecchio nome	Aggiornali a `agenteye-collector`.
L’esecuzione di `agenteye` avvia la CLI, non il collector	Hai la CLI AgentEye installata; possiede `agenteye`	Usa `agenteye-collector` per il daemon e rimuovi qualsiasi vecchio binario collector rimasto in `/usr/local/bin/agenteye`.

​Cosa è cambiato

​Prima di iniziare

​1. Installa il nuovo binario

​2. Aggiorna il tuo deployment

​systemd (Linux)

​launchd (macOS)

​supervisord

​Docker / Kubernetes

​Cron / script manuali

​3. Rimuovi il vecchio binario (per ultimo)

​Aggiornamenti da ora in poi

​Verifica

​Rollback

​Risoluzione dei problemi