Executar um worker da frota

Execute o cc_worker numa máquina disponível para acrescentar capacidade de execução à sua frota. É um binário em Dart puro — sem motor Flutter — que emparelha com um cc_server, declara as capacidades do anfitrião, envia heartbeats, recolhe trabalhos em lease, executa-os e transmite de volta os eventos de processo. Não detém qualquer estado duradouro: um supervisor reinicia-o e este volta a registar-se.

Precisa primeiro de um cc_server em execução — consulte Executar um servidor headless.

Um worker emparelhado regista-se, envia heartbeats e aguarda trabalhos em lease. Submeta trabalho com fleet.submitJob. O despacho de agentes neste servidor não passa pela frota; o sinal de sucesso deste guia é o worker aparecer no painel da frota com um heartbeat recente. O worker no próprio processo, registado no arranque, tem um mapa de runners vazio, pelo que um trabalho colocado nele devolve No local runner for job kind ….

Pré-requisitos

O Dart SDK. Este repositório fixa o SDK com o fvm, pelo que deve prefixar os comandos com fvm.
Este repositório clonado na máquina do worker.
Um cc_server alcançável (loopback para desenvolvimento, LAN ou remoto para produção).
git no PATH — o worker materializa repositórios e executa sondagens com git.

Passo 1: Compilar o binário

cd apps/cc_worker
fvm dart build cli

Isto produz um pacote autocontido em ./build/cli/<os_arch>/bundle/bin/cc_worker.

Passo 2: Emitir a credencial do worker

Um cc_server só aceita um worker que apresente um id de dispositivo emparelhado e uma chave pré-partilhada — incluindo um servidor em loopback. Emita-as na máquina do servidor (pair pode correr com o servidor em funcionamento; o novo dispositivo é reconhecido sem reinício):

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

Imprime um Device id e uma Pairing key — são esses os valores que --device-id e --psk / --psk-file / CC_WORKER_PSK aceitam.

Passo 3: Iniciar o worker

Ligado a um servidor emparelhado:

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

Ligado a um servidor em loopback (continua a ser preciso emparelhamento — o cc_server executa sempre o handshake PSK):

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

Opção	Descrição	Predefinição
`--server <url>`	URL do cc_server (`ws://`/`wss://`; `http(s)` e um caminho `/rpc` em falta são convertidos). Obrigatório.	—
`--name <name>`	Nome do worker visível ao operador.	nome do anfitrião
`--device-id <id>`	Id estável do dispositivo emparelhado, também usado como id do worker.	`cc-worker`
`--psk-file <path>`	Ficheiro cuja primeira linha não vazia é a chave de emparelhamento. Preferível a `--psk`.	—
`--psk <key>`	Chave de emparelhamento na linha de comandos. Visível em `ps` e no histórico da shell — o binário avisa.	—
`--max-jobs <n>`	Limite rígido de trabalhos que este processo executa em simultâneo (número inteiro positivo).	`4`

A ordem de resolução da chave é --psk-file → CC_WORKER_PSK → --psk. Omitir todas as fontes ignora o handshake de autenticação do worker; um cc_server real recusa então a sessão (auth_denied) em vez de aceitar um worker não autenticado. Opções desconhecidas são um erro de utilização (exit 64) — ao contrário do cc_server, este binário usa package:args e não ignora erros tipográficos.

CC_WORKER_CACHE substitui o diretório de cache de materialização da worktree (predefinição: um diretório cc_worker_cache sob o diretório temporário do sistema).

O worker regista-se com fleet.registerWorker, envia depois heartbeats a cada 20 s e procura leases a cada 2 s. Corre até receber SIGINT/SIGTERM; coloque-o sob o systemd ou o launchd para que reinicie e volte a registar-se após uma falha ou um reinício do sistema.

Passo 4: Verificar no painel da frota

Abra a Observabilidade na aplicação para computador ou web, mude para o separador Ao vivo e desça até ao fundo. Trabalhadores lista cada worker registado com a sua plataforma, núcleos, chaves de capacidade e último heartbeat; Trabalhos lista os trabalhos distribuídos por eles.

O aparecimento aí do seu worker com um heartbeat recente é a confirmação de que o emparelhamento e o registo funcionaram.

A partir do bloco de um worker pode Drenar um worker (concluir os trabalhos em curso, não aceitar novos leases), Retomar um worker em drenagem, Revogar a sua credencial ou Remover a linha.

As linhas de workers e de trabalhos vivem na global.db do servidor — o próprio worker não escreve nada no disco além da cache de materialização.

O que o worker anuncia

No registo, o worker deteta automaticamente as suas capacidades e o escalonador faz corresponder os trabalhos a essas capacidades. Não é preciso configurá-las à mão:

Sistema operativo e arquitetura (macos/linux/windows, arm64/x64) — sondagens exatas, com recurso a uname -m / PROCESSOR_ARCHITECTURE como alternativa
Núcleos e RAM — número exato de núcleos; a RAM degrada para 0 quando não é possível sondá-la
flutter — definida quando há um Flutter SDK acessível (flutter simples, depois fvm flutter); os trabalhos de renderização golden exigem-na
sandbox — native-macos no macOS, native-linux no Linux. Isto é uma indicação para a colocação, não uma promessa: o worker anuncia o backend que a sua plataforma tem, mas não envolve em nenhum deles os trabalhos que executa. Ao contrário do cc_server, o cc_worker lança um trabalho em lease diretamente
always-on e parallel — um cc_worker dedicado anuncia sempre ambas, pelo que é elegível para lotes de avaliação e outra capacidade paralela descartável

A deteção é feita na medida do possível: tudo o que não consiga sondar degrada para uma predefinição segura em vez de fazer falhar o arranque.

O que o worker executaria

O protocolo de lease transporta seis tipos de trabalho:

Tipo	O que é
`agentRun`	Uma única execução de agente (despacho)
`pipelineStep`	A execução de um passo de pipeline
`codeIndex`	Uma compilação do índice de código de um repositório
`goldenRender`	Uma renderização golden visual de interface (requer `flutter`)
`benchmark`	Uma execução de benchmark de desempenho
`evalBatch`	Um lote de avaliação (prefere capacidade `parallel`)

A execução é uma implementação real de streaming de subprocessos, não um runtime completo de agente incorporado. Quando um lease transporta repoRemote, o worker faz git clone --depth 1 para um diretório de cache com chave de remoto e SHA, seguido de git fetch e git checkout. Para agentRun, executa o comando em CC_JOB_COMMAND do ambiente do lease, no diretório de trabalho, transmitindo stdout e stderr de volta como eventos; sem CC_JOB_COMMAND, ecoa o prompt para que o transporte continue a ser exercitado de ponta a ponta. Os outros tipos executam pequenos comandos reais (git rev-parse HEAD, git --version) como sondagens honestas. As credenciais com âmbito de trabalho presentes no ambiente do lease são injetadas em todos os subprocessos e nunca são escritas num registo.

Os eventos são agrupados e descarregados a cada 250 ms ou a cada 32 eventos; cada trabalho termina com um evento de fim e um relatório de conclusão. O modelo é heartbeats mais leases de TTL curto: se um worker perde o contacto, o seu lease expira e o servidor recolhe o trabalho para nova tentativa. Não há estado duradouro no worker nem consenso ou roubo de trabalho entre workers.

Guias relacionados

Conceitos relacionados

Implementação e clientes