Chạy một worker đội máy

Chạy cc_worker trên một chiếc máy dự phòng để bổ sung năng lực thực thi cho đội máy của bạn. Đây là một tệp nhị phân Dart thuần — không có engine Flutter — ghép nối với một cc_server, khai báo các năng lực của máy chủ nhà, gửi heartbeat, kéo về những công việc được thuê, thực thi chúng rồi truyền sự kiện tiến trình về. Nó không giữ trạng thái bền vững nào: một trình giám sát khởi động lại nó và nó tự đăng ký lại.

Trước tiên bạn cần một cc_server đang chạy — xem Chạy máy chủ không giao diện.

Một worker đã ghép nối sẽ đăng ký, gửi heartbeat và chờ những công việc được thuê. Hãy gửi công việc bằng fleet.submitJob. Việc điều phối agent trên máy chủ này không đi qua đội máy; dấu hiệu thành công của hướng dẫn này là worker xuất hiện trong bảng đội máy với một heartbeat mới. Worker chạy trong cùng tiến trình, được đăng ký lúc khởi động, có một map runner rỗng, nên một công việc được đặt lên nó sẽ trả về No local runner for job kind ….

Điều kiện tiên quyết

Dart SDK. Kho mã này ghim phiên bản SDK của mình bằng fvm, nên hãy thêm tiền tố fvm vào các lệnh.
Kho mã này đã được checkout trên máy chạy worker.
Một cc_server với tới được (loopback khi phát triển, LAN hoặc từ xa khi chạy thật).
git trên PATH — worker hiện thực hóa các kho mã và chạy những phép dò git.

Bước 1: Dựng tệp nhị phân

cd apps/cc_worker
fvm dart build cli

Lệnh này tạo ra một gói khép kín tại ./build/cli/<os_arch>/bundle/bin/cc_worker.

Bước 2: Phát hành thông tin xác thực cho worker

Một cc_server chỉ chấp nhận worker xuất trình id thiết bị đã ghép nối và khóa chia sẻ trước — kể cả máy chủ loopback. Hãy phát hành chúng ngay trên máy chủ (pair có thể chạy trong khi máy chủ đang hoạt động; thiết bị mới được nhận mà không cần khởi động lại):

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

Nó in ra một Device id và một Pairing key — đó chính là những gì --device-id và --psk / --psk-file / CC_WORKER_PSK nhận.

Bước 3: Khởi động worker

Chạy với một máy chủ đã ghép nối:

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

Chạy với một máy chủ loopback (vẫn phải ghép nối — cc_server luôn chạy bắt tay PSK):

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

Cờ	Mô tả	Mặc định
`--server <url>`	URL của cc_server (`ws://`/`wss://`; `http(s)` và đường dẫn `/rpc` bị thiếu đều được tự động chuyển đổi). Bắt buộc.	—
`--name <name>`	Tên worker hiển thị cho người vận hành.	tên máy
`--device-id <id>`	Id thiết bị đã ghép nối, ổn định, cũng được dùng làm id worker.	`cc-worker`
`--psk-file <path>`	Tệp có dòng không trống đầu tiên là khóa ghép nối. Được ưu tiên hơn `--psk`.	—
`--psk <key>`	Khóa ghép nối ngay trên dòng lệnh. Hiện ra trong `ps` và lịch sử shell — tệp nhị phân sẽ cảnh báo.	—
`--max-jobs <n>`	Mức trần cứng cho số công việc mà tiến trình này thực thi đồng thời (số nguyên dương).	`4`

Thứ tự phân giải khóa là --psk-file → CC_WORKER_PSK → --psk. Bỏ qua mọi nguồn sẽ khiến worker không thực hiện bắt tay xác thực; một cc_server thật khi đó sẽ từ chối phiên (auth_denied) thay vì chấp nhận một worker chưa xác thực. Cờ không xác định là lỗi dùng sai (exit 64) — khác với cc_server, tệp nhị phân này dùng package:args và không bỏ qua lỗi gõ sai.

CC_WORKER_CACHE ghi đè thư mục đệm hiện thực hóa worktree (mặc định: một thư mục cc_worker_cache dưới thư mục tạm của hệ thống).

Worker đăng ký bằng fleet.registerWorker, sau đó gửi heartbeat 20 giây một lần và thăm dò hợp đồng thuê 2 giây một lần. Nó chạy cho tới khi nhận SIGINT/SIGTERM; hãy đặt nó dưới systemd hoặc launchd để nó khởi động lại và đăng ký lại sau khi gặp sự cố hoặc khởi động lại máy.

Bước 4: Xác minh trong bảng đội máy

Mở Quan sát trong ứng dụng máy tính hoặc web, chuyển sang tab Trực tiếp rồi cuộn xuống cuối. Worker liệt kê mọi worker đã đăng ký cùng nền tảng, số nhân, các khóa năng lực và heartbeat gần nhất; Công việc liệt kê những công việc được phân bổ cho chúng.

Việc worker của bạn xuất hiện ở đó với một heartbeat gần đây chính là xác nhận rằng ghép nối và đăng ký đã thành công.

Từ ô của một worker, bạn có thể ngừng nhận nó (hoàn thành các công việc hiện tại, không nhận hợp đồng thuê mới), tiếp tục một worker đang ngừng nhận, thu hồi thông tin xác thực của nó, hoặc xóa hàng đó.

Các hàng worker và công việc nằm trong global.db của máy chủ — bản thân worker không ghi gì xuống đĩa ngoài thư mục đệm hiện thực hóa.

Những gì worker quảng bá

Khi đăng ký, worker tự dò các năng lực của mình và bộ lập lịch đối chiếu công việc với chúng. Bạn không cấu hình những thứ này bằng tay:

Hệ điều hành và kiến trúc (macos/linux/windows, arm64/x64) — các phép dò chính xác, có phương án dự phòng là uname -m / PROCESSOR_ARCHITECTURE
Số nhân và RAM — số nhân chính xác; RAM giảm về 0 khi không dò được
flutter — được đặt khi với tới được một Flutter SDK (flutter trần, rồi fvm flutter); các công việc golden-render cần nó
sandbox — native-macos trên macOS, native-linux trên Linux. Đây là một gợi ý xếp chỗ, không phải một lời hứa: worker quảng bá backend mà nền tảng của nó có, nhưng nó không bọc những công việc mình chạy trong backend đó. Khác với cc_server, cc_worker sinh thẳng một công việc được thuê
always-on và parallel — một cc_worker chuyên dụng luôn quảng bá cả hai, nên nó đủ điều kiện cho các lô đánh giá và những năng lực song song dùng một lần khác

Việc dò là nỗ lực tối đa: bất cứ thứ gì nó không dò được đều lùi về một giá trị mặc định an toàn thay vì làm khởi động thất bại.

Những gì worker sẽ thực thi

Giao thức hợp đồng thuê mang sáu loại công việc:

Loại	Nội dung
`agentRun`	Một lượt chạy agent đơn lẻ (điều phối)
`pipelineStep`	Việc thực thi một bước quy trình
`codeIndex`	Việc dựng chỉ mục mã của một kho mã
`goldenRender`	Một lượt render golden trực quan giao diện (cần `flutter`)
`benchmark`	Một lượt chạy benchmark hiệu năng
`evalBatch`	Một lô đánh giá (ưu tiên năng lực `parallel`)

Việc thực thi là một triển khai truyền phát tiến trình con thật sự, không phải một runtime agent nhúng đầy đủ. Khi một hợp đồng thuê mang repoRemote, worker chạy git clone --depth 1 vào một thư mục đệm được đặt khóa theo remote và SHA, rồi git fetch và git checkout. Với agentRun, nó chạy lệnh trong CC_JOB_COMMAND của môi trường hợp đồng thuê, ngay tại thư mục làm việc, truyền phát stdout và stderr về dưới dạng sự kiện; nếu không có CC_JOB_COMMAND, nó lặp lại prompt để đường truyền vẫn được chạy thử từ đầu đến cuối. Các loại khác chạy những lệnh thật nhỏ (git rev-parse HEAD, git --version) như những phép dò trung thực. Thông tin xác thực theo phạm vi công việc trong môi trường hợp đồng thuê được tiêm vào mọi tiến trình con và không bao giờ được ghi vào log.

Các sự kiện được gom lô và xả mỗi 250ms hoặc mỗi 32 sự kiện; mỗi công việc kết thúc bằng một sự kiện done và một báo cáo hoàn thành. Mô hình là heartbeat cộng với những hợp đồng thuê có TTL ngắn: nếu một worker mất liên lạc, hợp đồng thuê của nó hết hạn và máy chủ thu hồi công việc để thử lại. Không có trạng thái bền vững trên worker và không có đồng thuận hay giành việc giữa các worker.

Các hướng dẫn liên quan

Các khái niệm liên quan

Triển khai và máy khách