Exécuter un worker de flotte

Exécutez cc_worker sur une machine de rechange 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, envoie des battements de cœur, tire des tâches louées, les exécute et renvoie les événements de processus en continu. 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 — consultez Exécuter un serveur sans interface.

Un worker associé s’enregistre, envoie des battements de cœur et attend des tâches louées. Soumettez du travail avec fleet.submitJob. La répartition des agents sur ce serveur ne passe pas par la flotte ; le signal de réussite de ce guide est l’apparition du worker dans le panneau de flotte avec un battement de cœur récent. Le worker en cours de processus, enregistré au démarrage, a une table d’exécuteurs vide, donc une tâche placée sur lui renvoie No local runner for job kind ….

Prérequis

Le SDK Dart. Ce dépôt fixe 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 (la boucle locale pour le développement, le réseau local ou une adresse distante en 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 dans ./build/cli/<os_arch>/bundle/bin/cc_worker.

Étape 2 : Générer le justificatif 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. Générez-les sur la machine du 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 imprime un Device id et une 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

Indicateur	Description	Valeur par défaut
`--server <url>`	URL du cc_server (`ws://`/`wss://`; la forme `http(s)` et un chemin `/rpc` manquant sont normalisés). Obligatoire.	—
`--name <name>`	Nom du worker visible par l’opérateur.	nom de l’hôte
`--device-id <id>`	Identifiant stable d’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 sur la ligne de commande. Visible dans `ps` et l’historique du shell — le binaire émet un avertissement.	—
`--max-jobs <n>`	Plafond absolu du nombre de tâches que ce processus exécute simultanément (entier positif).	`4`

L’ordre de résolution de la clé est --psk-file → CC_WORKER_PSK → --psk. Si vous omettez toutes les sources, la poignée de main d’authentification du worker est sautée ; un vrai cc_server refuse alors la session (auth_denied) plutôt que d’accepter un worker non authentifié. Les indicateurs inconnus constituent une erreur d’utilisation (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 dans le répertoire temporaire du système).

Le worker s’enregistre avec fleet.registerWorker, puis envoie un battement de cœur toutes les 20 s et vérifie 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 : Vérifier le worker dans le panneau de flotte

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

L’apparition de votre worker à cet endroit avec un battement de cœur récent confirme que l’association et l’enregistrement ont fonctionné.

Depuis la vignette d’un worker, vous pouvez le drainer (terminer les tâches en cours, ne plus prendre de nouvelles locations), reprendre un worker en cours de drainage, révoquer son justificatif ou supprimer la ligne.

Les lignes des workers et des tâches se trouvent 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 met les tâches en correspondance avec elles. 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 est ramenée à 0 lorsqu’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 un indice de placement, pas une promesse : le worker annonce le backend que sa plateforme possède, mais il n’enveloppe pas dans un backend les tâches qu’il exécute. 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 admissible aux lots d’évaluation et à toute autre capacité parallèle jetable

La détection est effectuée au mieux : tout ce qu’il ne peut pas sonder est ramené à une valeur par défaut sûre au lieu de faire échouer le démarrage.

Ce que le worker exécuterait

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

Type	Ce que c’est
`agentRun`	Une seule exécution d’agent (répartition)
`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 de l’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 vraie implémentation de sous-processus avec diffusion en continu, et non un environnement d’exécution d’agent embarqué complet. Lorsqu’une location transporte repoRemote, le worker fait git clone --depth 1 dans un répertoire de cache indexé par dépôt distant et par 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 de 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 pour que le transport soit tout de même exercé de bout en bout. Les autres types exécutent de petites vraies commandes (git rev-parse HEAD, git --version) à titre de sondes honnêtes. Les justificatifs à portée de tâche de l’environnement de la location sont injectés dans chaque sous-processus et ne sont jamais écrits dans un journal.

Les événements sont mis en lots et vidés toutes les 250 ms ou tous les 32 événements ; chaque tâche se termine par un événement done et un rapport d’achèvement. Le modèle repose sur des battements de cœur et des locations à courte durée de vie : si un worker perd le contact, sa location expire et le serveur récupère la tâche pour une nouvelle tentative. 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