Esegui un worker della flotta

Esegui cc_worker su una macchina libera per aggiungere capacità di esecuzione alla tua flotta. È un binario in puro Dart — senza motore Flutter — che si associa a un cc_server, dichiara le capacità dell’host, invia heartbeat, preleva i lavori in lease, li esegue e trasmette indietro gli eventi di processo. Non conserva alcuno stato durevole: un supervisore lo riavvia e lui si registra di nuovo.

Ti serve prima un cc_server in esecuzione — vedi Esegui un server headless.

Un worker abbinato si registra, invia heartbeat e attende i lavori in lease. Invia lavoro con fleet.submitJob. L’invio degli agenti su questo server non passa attraverso la flotta; il segnale di riuscita di questa guida è il worker che compare nel pannello della flotta con un heartbeat recente. Il worker registrato all’avvio nello stesso processo ha una mappa dei runner vuota, quindi un lavoro che gli viene assegnato restituisce No local runner for job kind ….

Prerequisiti

• Dart SDK. Questo repo fissa l’SDK con fvm, quindi anteponi fvm ai comandi.
• Questo repository, di cui hai fatto il checkout sulla macchina del worker.
• Un cc_server raggiungibile (loopback per lo sviluppo, LAN o remoto per la produzione).
• git nel PATH — il worker materializza i repo ed esegue sonde git.

Passaggio 1: compila il binario

cd apps/cc_worker
fvm dart build cli

Questo produce un bundle autonomo in ./build/cli/<os_arch>/bundle/bin/cc_worker.

Passaggio 2: conia la credenziale del worker

Un cc_server accetta solo un worker che presenta un id di dispositivo abbinato e una chiave pre-condivisa — anche nel caso di un server in loopback. Coniale sulla macchina server (pair può essere eseguito mentre il server è attivo; il nuovo dispositivo viene rilevato senza riavvio):

cc_server pair --data-dir <dir> --device my-worker --label "Build box"

Stampa un Device id e una Pairing key — sono i valori che accettano --device-id e --psk / --psk-file / CC_WORKER_PSK.

Passaggio 3: avvia il worker

Verso un server abbinato:

./build/cli/<os_arch>/bundle/bin/cc_worker \
  --server wss://host:9030 --device-id my-worker --psk-file /path/to/worker.psk

Verso un server in loopback (comunque abbinato — cc_server esegue sempre l’handshake PSK):

fvm dart run cc_worker --server ws://localhost:9030 \
  --device-id my-worker --psk-file /path/to/worker.psk

Flag	Descrizione	Predefinito
--server <url>	URL di cc_server (ws:///wss://; http(s) e un percorso /rpc mancante vengono normalizzati). Obbligatorio.	—
--name <name>	Nome del worker visibile all’operatore.	nome host
--device-id <id>	Id stabile del dispositivo abbinato, usato anche come id del worker.	cc-worker
--psk-file <path>	File la cui prima riga non vuota è la chiave di abbinamento. Preferito a --psk.	—
--psk <key>	Chiave di abbinamento sulla riga di comando. Visibile in ps e nella cronologia della shell — il binario avvisa.	—
--max-jobs <n>	Limite massimo di lavori eseguiti contemporaneamente da questo processo (intero positivo).	4

L’ordine di risoluzione della chiave è --psk-file → CC_WORKER_PSK → --psk. Se ometti ogni sorgente, il worker salta il proprio handshake di autenticazione; un cc_server reale rifiuta allora la sessione (auth_denied) invece di accettare un worker non autenticato. I flag sconosciuti sono un errore di utilizzo (exit 64) — a differenza di cc_server, questo binario usa package:args e non ignora i refusi.

CC_WORKER_CACHE sovrascrive la directory di cache della materializzazione dei worktree (predefinita: una directory cc_worker_cache sotto la directory temporanea di sistema).

Il worker si registra con fleet.registerWorker, poi invia un heartbeat ogni 20s e cerca nuovi lease ogni 2s. Resta in esecuzione fino a SIGINT/SIGTERM; mettilo sotto systemd o launchd, così si riavvia e si registra di nuovo dopo un crash o un riavvio.

Non esiste una finestra di compatibilità del protocollo

Un worker la cui versione del protocollo di flotta differisce da quella del server viene registrato come Incompatibile, non riceve mai un lease e cc_worker stesso si interrompe con Incompatible fleet protocol: worker speaks v… server speaks v… Upgrade cc_worker to match the server release. Compila il worker dalla stessa release del server.

Passaggio 4: verificalo nel pannello della flotta

Apri Osservabilità nell’app desktop o web, passa alla scheda Dal vivo e scorri fino in fondo. Worker elenca ogni worker registrato con la sua piattaforma, i core, le chiavi di capacità e l’ultimo heartbeat; Lavori elenca i lavori distribuiti tra loro.

Il fatto che il tuo worker compaia lì con un heartbeat recente è la conferma che l’abbinamento e la registrazione hanno funzionato.

Dal riquadro di un worker puoi svuotarlo (finire i lavori in corso, senza accettare nuovi lease), riprendere un worker in svuotamento, revocare la sua credenziale o rimuovere la riga.

Le righe dei worker e dei lavori risiedono nel global.db del server — il worker stesso non scrive nulla su disco oltre alla cache di materializzazione.

Che cosa dichiara il worker

Alla registrazione il worker rileva automaticamente le proprie capacità e lo scheduler abbina i lavori a esse. Non le configuri a mano:

• Sistema operativo e architettura (macos/linux/windows, arm64/x64) — sonde esatte, con fallback su uname -m / PROCESSOR_ARCHITECTURE
• Core e RAM — numero esatto di core; la RAM scende a 0 quando non è possibile rilevarla
• flutter — impostato quando un SDK Flutter è raggiungibile (flutter semplice, poi fvm flutter); i lavori di golden render lo richiedono
• sandbox — native-macos su macOS, native-linux su Linux. È un suggerimento di posizionamento, non una promessa: il worker dichiara il backend che la sua piattaforma ha, ma non avvolge in esso i lavori che esegue. A differenza di cc_server, cc_worker avvia direttamente un lavoro in lease
• always-on e parallel — un cc_worker dedicato dichiara sempre entrambe, quindi è idoneo ai batch di eval e ad altra capacità parallela usa e getta

Il rilevamento è di tipo best-effort: tutto ciò che non riesce a sondare degrada a un valore predefinito sicuro invece di far fallire l’avvio.

Che cosa eseguirebbe il worker

Il protocollo di lease trasporta sei tipi di lavoro:

Tipo	Che cos’è
agentRun	Una singola esecuzione di agente (invio)
pipelineStep	L’esecuzione di un passaggio di pipeline
codeIndex	La creazione di un indice del codice di un repo
goldenRender	Un rendering golden visivo dell’interfaccia (richiede flutter)
benchmark	Un’esecuzione di benchmark delle prestazioni
evalBatch	Un batch di eval (preferisce capacità parallel)

L’esecuzione è una vera implementazione che trasmette sottoprocessi, non un runtime completo di agenti incorporato. Quando un lease porta repoRemote, il worker esegue git clone --depth 1 in una directory di cache con chiave remote-e-SHA, poi git fetch e git checkout. Per agentRun esegue il comando in CC_JOB_COMMAND dell’ambiente del lease nella directory di lavoro, trasmettendo stdout e stderr come eventi; senza CC_JOB_COMMAND restituisce il prompt, così il trasporto viene comunque esercitato per intero. Gli altri tipi eseguono piccoli comandi reali (git rev-parse HEAD, git --version) come sonde oneste. Le credenziali con ambito limitato al lavoro presenti nell’ambiente del lease vengono iniettate in ogni sottoprocesso e non finiscono mai in un log.

Gli eventi vengono raggruppati e inviati ogni 250ms o ogni 32 eventi; ogni lavoro termina con un evento done e un report di completamento. Il modello è heartbeat più lease con TTL breve: se un worker perde il contatto, il suo lease scade e il server recupera il lavoro per un nuovo tentativo. Sul worker non c’è alcuno stato durevole e tra i worker non ci sono consenso né work-stealing.

Guide correlate

• Esegui un server headless
• Connettiti a un server remoto
• Associa un dispositivo

Concetti correlati

• Deployment e client