Exécuter un worker de flotte

Exécutez cc_worker sur une machine de réserve pour ajouter de la capacité d’exécution à votre flotte. C’est un binaire en pur Dart — sans moteur Flutter — qui s’associe à un cc_server, déclare les capacités de l’hôte, émet un signal, tire les tâches louées, les exécute et renvoie en continu les événements de processus. Il ne détient aucun état durable : un superviseur le redémarre et il se réenregistre.

Vous avez d’abord besoin d’un cc_server en cours d’exécution — voir Exécuter un serveur sans interface.

Un worker associé s’enregistre, émet un signal et attend des tâches louées. Soumettez du travail avec fleet.submitJob. Le lancement d’agents sur ce serveur ne passe pas par la flotte ; le critère de réussite de ce guide est l’apparition du worker dans le panneau de la flotte avec un signal récent. Le worker intra-processus enregistré au démarrage a une table d’exécuteurs vide, si bien qu’une tâche qui lui est attribuée renvoie No local runner for job kind ….

Prérequis

Le SDK Dart. Ce dépôt épingle son SDK avec fvm, donc préfixez les commandes par fvm.
Ce dépôt cloné sur la machine du worker.
Un cc_server joignable (boucle locale pour le développement, réseau local ou distant pour la production).
git dans le PATH — le worker matérialise les dépôts et exécute des sondes git.

Étape 1 : Compiler le binaire

cd apps/cc_worker
fvm dart build cli

Cela produit un paquet autonome à l’emplacement ./build/cli/<os_arch>/bundle/bin/cc_worker.

Étape 2 : Émettre les identifiants du worker

Un cc_server n’accepte qu’un worker qui présente un identifiant d’appareil associé et une clé pré-partagée — y compris un serveur en boucle locale. Émettez-les sur la machine serveur (pair peut s’exécuter pendant que le serveur tourne ; le nouvel appareil est pris en compte sans redémarrage) :

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

Il affiche un Device id et un Pairing key — ce sont les valeurs que prennent --device-id et --psk / --psk-file / CC_WORKER_PSK.

Étape 3 : Démarrer le worker

Avec un serveur associé :

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

Avec un serveur en boucle locale (toujours associé — cc_server exécute toujours la poignée de main PSK) :

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

Option	Description	Valeur par défaut
`--server <url>`	URL du cc_server (`ws://`/`wss://` ; `http(s)` et un chemin `/rpc` manquant sont convertis). Obligatoire.	—
`--name <name>`	Nom du worker tel qu’affiché à l’opérateur.	nom de l’hôte
`--device-id <id>`	Identifiant stable de l’appareil associé, également utilisé comme identifiant du worker.	`cc-worker`
`--psk-file <path>`	Fichier dont la première ligne non vide est la clé d’appairage. Préféré à `--psk`.	—
`--psk <key>`	Clé d’appairage passée sur la ligne de commande. Visible dans `ps` et l’historique du shell — le binaire avertit.	—
`--max-jobs <n>`	Plafond strict du nombre de tâches que ce processus exécute en parallèle (entier positif).	`4`

L’ordre de résolution de la clé est --psk-file → CC_WORKER_PSK → --psk. Omettre toutes les sources ignore la poignée de main d’authentification du worker ; un vrai cc_server refuse alors la session (auth_denied) au lieu d’accepter un worker non authentifié. Les options inconnues constituent une erreur d’usage (exit 64) — contrairement à cc_server, ce binaire utilise package:args et n’ignore pas les fautes de frappe.

CC_WORKER_CACHE remplace le répertoire de cache de matérialisation des arbres de travail (par défaut : un répertoire cc_worker_cache sous le répertoire temporaire du système).

Le worker s’enregistre avec fleet.registerWorker, puis émet un signal toutes les 20 s et interroge les locations toutes les 2 s. Il s’exécute jusqu’à SIGINT/SIGTERM ; placez-le sous systemd ou launchd pour qu’il redémarre et se réenregistre après un plantage ou un redémarrage.

Étape 4 : Le vérifier dans le panneau de la flotte

Ouvrez Observabilité dans l’application de bureau ou web, passez à l’onglet En direct et faites défiler jusqu’en bas. Exécuteurs liste chaque worker enregistré avec sa plateforme, ses cœurs, ses clés de capacités et son dernier signal ; Travaux liste les tâches réparties entre eux.

L’apparition de votre worker à cet endroit avec un signal récent confirme que l’appairage et l’enregistrement ont fonctionné.

Depuis la tuile d’un worker, vous pouvez le Drainer (terminer les tâches en cours, ne prendre aucune nouvelle location), Reprendre un worker en cours de drainage, Révoquer ses identifiants, ou Supprimer la ligne.

Les lignes des workers et des tâches résident dans le global.db du serveur — le worker lui-même n’écrit rien sur le disque en dehors du cache de matérialisation.

Ce que le worker annonce

À l’enregistrement, le worker détecte automatiquement ses capacités et l’ordonnanceur fait correspondre les tâches à celles-ci. Vous ne les configurez pas à la main :

Système d’exploitation et architecture (macos/linux/windows, arm64/x64) — sondes exactes, avec repli sur uname -m / PROCESSOR_ARCHITECTURE
Cœurs et mémoire vive — nombre exact de cœurs ; la mémoire vive se réduit à 0 quand elle ne peut pas être sondée
flutter — défini lorsqu’un SDK Flutter est joignable (flutter seul, puis fvm flutter) ; les tâches de rendu golden l’exigent
sandbox — native-macos sous macOS, native-linux sous Linux. C’est une indication de placement, pas une promesse : le worker annonce le backend dont sa plateforme dispose, mais il n’enveloppe pas les tâches qu’il exécute dans un bac à sable. Contrairement à cc_server, cc_worker lance directement une tâche louée
always-on et parallel — un cc_worker dédié annonce toujours les deux, ce qui le rend éligible aux lots d’évaluation et aux autres capacités parallèles jetables

La détection se fait au mieux : tout ce qu’il ne peut pas sonder se réduit à une valeur par défaut sûre plutôt que de faire échouer le démarrage.

Ce que le worker exécuterait

Le protocole de location transporte six types de tâches :

Type	Description
`agentRun`	Une exécution d’agent unique (lancement)
`pipelineStep`	L’exécution d’une étape de pipeline
`codeIndex`	La construction de l’index de code d’un dépôt
`goldenRender`	Un rendu golden visuel d’interface (exige `flutter`)
`benchmark`	Une exécution de benchmark de performance
`evalBatch`	Un lot d’évaluation (préfère la capacité `parallel`)

L’exécution est une véritable implémentation de diffusion de sous-processus, et non un moteur d’agent embarqué complet. Lorsqu’une location porte repoRemote, le worker effectue git clone --depth 1 dans un répertoire de cache indexé par dépôt distant et SHA, puis git fetch et git checkout. Pour agentRun, il exécute dans le répertoire de travail la commande indiquée par CC_JOB_COMMAND dans l’environnement de la location, en renvoyant stdout et stderr sous forme d’événements ; sans CC_JOB_COMMAND, il renvoie l’invite en écho afin que le transport soit tout de même exercé de bout en bout. Les autres types exécutent de petites commandes réelles (git rev-parse HEAD, git --version) comme sondes honnêtes. Les identifiants propres à la tâche présents dans l’environnement de la location sont injectés dans chaque sous-processus et ne sont jamais écrits dans un journal.

Les événements sont regroupés et vidés toutes les 250 ms ou tous les 32 événements ; chaque tâche se termine par un événement de fin et un rapport d’achèvement. Le modèle repose sur des signaux et des locations à TTL court : si un worker perd le contact, sa location expire et le serveur récupère la tâche pour la réessayer. Il n’y a aucun état durable sur le worker, ni consensus ni vol de travail entre workers.

Guides connexes

Concepts connexes

Déploiement et clients