Ejecutar un worker de flota

Ejecuta cc_worker en una máquina de repuesto para añadir capacidad de ejecución a tu flota. Es un binario de Dart puro —sin motor de Flutter— que se empareja con un cc_server, declara las capacidades del host, envía latidos, recoge trabajos con lease, los ejecuta y devuelve por streaming los eventos de proceso. No guarda ningún estado duradero: un supervisor lo reinicia y vuelve a registrarse.

Necesitas antes un cc_server en ejecución; consulta Ejecutar un servidor headless.

Un worker emparejado se registra, envía latidos y espera trabajos con lease. Envía trabajo con fleet.submitJob. El despacho de agentes en este servidor no pasa por la flota; la señal de éxito de esta guía es que el worker aparezca en el panel de flota con un latido reciente. El worker en proceso registrado al arrancar tiene un mapa de runners vacío, así que un trabajo colocado en él devuelve No local runner for job kind ….

Requisitos previos

El SDK de Dart. Este repositorio fija su SDK con fvm, así que antepone fvm a los comandos.
Este repositorio clonado en la máquina del worker.
Un cc_server accesible (loopback para desarrollo, LAN o remoto para producción).
git en el PATH: el worker materializa repos y ejecuta sondas de git.

Paso 1: Compila el binario

cd apps/cc_worker
fvm dart build cli

Esto genera un paquete autocontenido en ./build/cli/<os_arch>/bundle/bin/cc_worker.

Paso 2: Crea la credencial del worker

Un cc_server solo acepta un worker que presente un id de dispositivo emparejado y una clave precompartida, incluido un servidor de loopback. Créalos en la máquina del servidor (pair puede ejecutarse con el servidor en marcha; el nuevo dispositivo se detecta sin reiniciar):

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

Imprime un Device id y un Pairing key: son los valores que toman --device-id y --psk / --psk-file / CC_WORKER_PSK.

Paso 3: Arranca el worker

Contra un servidor emparejado:

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

Contra un servidor de loopback (también emparejado: cc_server siempre ejecuta el handshake de PSK):

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

Opción	Descripción	Predeterminado
`--server <url>`	URL de cc_server (`ws://`/`wss://`; `http(s)` y una ruta `/rpc` ausente se convierten). Obligatorio.	—
`--name <name>`	Nombre del worker orientado al operador.	nombre del host
`--device-id <id>`	Id estable del dispositivo emparejado, que también se usa como id del worker.	`cc-worker`
`--psk-file <path>`	Archivo cuya primera línea no vacía es la clave de emparejamiento. Se prefiere a `--psk`.	—
`--psk <key>`	Clave de emparejamiento en la línea de comandos. Visible en `ps` y en el historial del shell: el binario avisa.	—
`--max-jobs <n>`	Límite máximo de trabajos que este proceso ejecuta de forma concurrente (entero positivo).	`4`

El orden de resolución de la clave es --psk-file → CC_WORKER_PSK → --psk. Omitir todas las fuentes se salta el handshake de autenticación del worker; un cc_server real entonces deniega la sesión (auth_denied) en lugar de aceptar un worker sin autenticar. Las opciones desconocidas son un error de uso (exit 64); a diferencia de cc_server, este binario usa package:args y no ignora las erratas.

CC_WORKER_CACHE sobrescribe el directorio de caché de materialización de worktrees (valor predeterminado: un directorio cc_worker_cache bajo el directorio temporal del sistema).

El worker se registra con fleet.registerWorker, luego envía un latido cada 20s y consulta leases cada 2s. Se ejecuta hasta recibir SIGINT/SIGTERM; ponlo bajo systemd o launchd para que se reinicie y vuelva a registrarse tras un fallo o un reinicio.

Paso 4: Verifícalo en el panel de flota

Abre Observabilidad en la aplicación de escritorio o web, cambia a la pestaña En vivo y desplázate hasta el final. Trabajadores enumera cada worker registrado con su plataforma, núcleos, claves de capacidad y último latido; Trabajos enumera los trabajos distribuidos entre ellos.

Que tu worker aparezca ahí con un latido reciente es la confirmación de que el emparejamiento y el registro han funcionado.

Desde la tarjeta de un worker puedes drenarlo (terminar los trabajos actuales, no aceptar nuevos leases), reanudar un worker que se está drenando, revocar su credencial o eliminar la fila.

Las filas de workers y trabajos viven en el global.db del servidor; el worker en sí no escribe nada en disco más allá de la caché de materialización.

Qué anuncia el worker

Al registrarse, el worker detecta automáticamente sus capacidades y el planificador empareja los trabajos con ellas. No las configuras a mano:

Sistema operativo y arquitectura (macos/linux/windows, arm64/x64): sondas exactas, con alternativas a uname -m / PROCESSOR_ARCHITECTURE
Núcleos y RAM: recuento exacto de núcleos; la RAM se degrada a 0 cuando no se puede sondear
flutter: se define cuando hay un SDK de Flutter accesible (flutter sin más y luego fvm flutter); los trabajos de render golden lo requieren
sandbox: native-macos en macOS y native-linux en Linux. Es una indicación de colocación, no una promesa: el worker anuncia el backend que su plataforma tiene, pero no envuelve en él los trabajos que ejecuta. A diferencia de cc_server, cc_worker lanza un trabajo con lease directamente
always-on y parallel: un cc_worker dedicado anuncia siempre ambas, por lo que es elegible para lotes de evaluación y otra capacidad paralela desechable

La detección es de mejor esfuerzo: todo lo que no puede sondear se degrada a un valor predeterminado seguro en lugar de hacer fallar el arranque.

Qué ejecutaría el worker

El protocolo de lease transporta seis tipos de trabajo:

Tipo	Qué es
`agentRun`	Una única ejecución de agente (despacho)
`pipelineStep`	La ejecución de un paso de pipeline
`codeIndex`	Una compilación del índice de código de un repo
`goldenRender`	Un render golden visual de la interfaz (requiere `flutter`)
`benchmark`	Una ejecución de benchmark de rendimiento
`evalBatch`	Un lote de evaluación (prefiere capacidad `parallel`)

La ejecución es una implementación real que transmite subprocesos, no un tiempo de ejecución de agente totalmente embebido. Cuando un lease lleva repoRemote, el worker hace git clone --depth 1 en un directorio de caché con clave de remoto y SHA, y después git fetch y git checkout. Para agentRun, ejecuta el comando de CC_JOB_COMMAND del entorno del lease en el directorio de trabajo, y transmite stdout y stderr de vuelta como eventos; si no hay CC_JOB_COMMAND, hace eco del prompt para que el transporte se siga ejercitando de extremo a extremo. Los demás tipos ejecutan pequeños comandos reales (git rev-parse HEAD, git --version) como sondas honestas. Las credenciales con ámbito de trabajo del entorno del lease se inyectan en cada subproceso y nunca se escriben en un log.

Los eventos se agrupan por lotes y se vuelcan cada 250ms o cada 32 eventos; cada trabajo termina con un evento done y un informe de finalización. El modelo son latidos más leases de TTL corto: si un worker pierde el contacto, su lease caduca y el servidor recupera el trabajo para reintentarlo. No hay estado duradero en el worker ni consenso ni robo de trabajo entre workers.

Guías relacionadas

Conceptos relacionados

Despliegue y clientes