รันวอร์กเกอร์ของฟลีต

รัน cc_worker บนเครื่องสำรองเพื่อเพิ่มความจุในการประมวลผลให้ฟลีตของคุณ มันเป็น ไบนารี Dart ล้วน — ไม่มีเอนจิน Flutter — ที่จับคู่กับ cc_server ประกาศ ความสามารถของโฮสต์ ส่งฮาร์ตบีต ดึงงานที่เช่าไปรัน ประมวลผลงานเหล่านั้น และ สตรีมเหตุการณ์ของโปรเซสกลับมา มันไม่มีสถานะถาวร: ตัวควบคุมดูแลจะเริ่มมันใหม่ แล้วมันจะลงทะเบียนอีกครั้ง

คุณต้องมี cc_server ที่รันอยู่ก่อน — ดูรันเซิร์ฟเวอร์แบบไม่มีส่วนติดต่อ

วอร์กเกอร์ที่จับคู่แล้วจะลงทะเบียน ส่งฮาร์ตบีต และรอรับงานที่เช่า ส่งงานด้วย fleet.submitJob การสั่งงานเอเจนต์บนเซิร์ฟเวอร์นี้ไม่ผ่านฟลีต สัญญาณความสำเร็จ ของคู่มือนี้คือวอร์กเกอร์ที่ปรากฏในแผงฟลีตพร้อมฮาร์ตบีตใหม่ วอร์กเกอร์ในโปรเซส ที่ลงทะเบียนตอนบูตมีแมปตัวรันว่างเปล่า งานที่ถูกวางบนมันจึงคืนค่า No local runner for job kind …

ก่อนเริ่ม

• Dart SDK รีโปนี้ปักหมุดเวอร์ชัน SDK ด้วย fvm จึงต้องเติม fvm นำหน้าคำสั่ง
• รีโปนี้ที่เช็กเอาต์ไว้บนเครื่องวอร์กเกอร์
• cc_server ที่เข้าถึงได้ (ลูปแบ็กสำหรับการพัฒนา หรือ LAN/ระยะไกลสำหรับโปรดักชัน)
• git บน PATH — วอร์กเกอร์จัดเตรียมรีโปและรันการตรวจสอบด้วย git

ขั้นตอนที่ 1: บิลด์ไบนารี

cd apps/cc_worker
fvm dart build cli

คำสั่งนี้สร้างบันเดิลที่ครบในตัวเองที่ ./build/cli/<os_arch>/bundle/bin/cc_worker

ขั้นตอนที่ 2: สร้างข้อมูลรับรองของวอร์กเกอร์

cc_server ยอมรับเฉพาะวอร์กเกอร์ที่แสดง id ของอุปกรณ์ที่จับคู่ไว้กับคีย์ที่แชร์ ล่วงหน้า — รวมถึงเซิร์ฟเวอร์ลูปแบ็กด้วย ให้สร้างสิ่งเหล่านี้บนเครื่อง เซิร์ฟเวอร์ (pair รันได้ขณะเซิร์ฟเวอร์ทำงานอยู่ อุปกรณ์ใหม่จะถูกนำมาใช้ โดยไม่ต้องรีสตาร์ต):

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

มันพิมพ์ Device id และ Pairing key ออกมา — สิ่งเหล่านี้คือค่าที่ --device-id และ --psk / --psk-file / CC_WORKER_PSK รับไป

ขั้นตอนที่ 3: เริ่มวอร์กเกอร์

กับเซิร์ฟเวอร์ที่จับคู่แล้ว:

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

กับเซิร์ฟเวอร์ลูปแบ็ก (ยังต้องจับคู่ — cc_server รันแฮนด์เชก PSK เสมอ):

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

แฟล็ก	คำอธิบาย	ค่าเริ่มต้น
--server <url>	URL ของ cc_server (ws:///wss://; http(s) และพาธ /rpc ที่หายไปจะถูกปรับให้) จำเป็น	—
--name <name>	ชื่อวอร์กเกอร์ที่ผู้ปฏิบัติงานเห็น	ชื่อโฮสต์
--device-id <id>	id ของอุปกรณ์ที่จับคู่แบบถาวร ใช้เป็น id ของวอร์กเกอร์ด้วย	cc-worker
--psk-file <path>	ไฟล์ที่บรรทัดแรกที่ไม่ว่างคือคีย์จับคู่ แนะนำให้ใช้แทน --psk	—
--psk <key>	คีย์จับคู่บนบรรทัดคำสั่ง มองเห็นได้ใน ps และประวัติเชลล์ — ไบนารีจะเตือน	—
--max-jobs <n>	เพดานสูงสุดของงานที่โปรเซสนี้ประมวลผลพร้อมกัน (จำนวนเต็มบวก)	4

ลำดับการหาคีย์คือ --psk-file → CC_WORKER_PSK → --psk การละทุกแหล่งจะข้าม แฮนด์เชกการยืนยันตัวตนของวอร์กเกอร์ แล้ว cc_server จริงจะปฏิเสธเซสชัน (auth_denied) แทนที่จะยอมรับวอร์กเกอร์ที่ไม่ได้ยืนยันตัวตน แฟล็กที่ไม่รู้จัก ถือเป็นข้อผิดพลาดการใช้งาน (exit 64) — ต่างจาก cc_server ไบนารีนี้ใช้ package:args และไม่เพิกเฉยต่อการพิมพ์ผิด

CC_WORKER_CACHE เขียนทับไดเรกทอรีแคชการจัดเตรียม worktree (ค่าเริ่มต้น: ไดเรกทอรี cc_worker_cache ใต้ไดเรกทอรีชั่วคราวของระบบ)

วอร์กเกอร์ลงทะเบียนด้วย fleet.registerWorker จากนั้นส่งฮาร์ตบีตทุก 20 วินาที และโพลล์หาการเช่าทุก 2 วินาที มันรันจนกว่าจะได้รับ SIGINT/SIGTERM ให้วางไว้ ใต้ systemd หรือ launchd เพื่อให้มันรีสตาร์ตและลงทะเบียนใหม่หลังแครชหรือรีบูต

ไม่มีช่วงเวลาที่โปรโตคอลเข้ากันได้

วอร์กเกอร์ที่มีเวอร์ชันโปรโตคอลฟลีตต่างจากของเซิร์ฟเวอร์จะถูกลงทะเบียนว่า เข้ากันไม่ได้ และจะไม่ถูกเสนอการเช่าเลย และตัว cc_worker เองจะยกเลิกด้วย Incompatible fleet protocol: worker speaks v… server speaks v… Upgrade cc_worker to match the server release ให้บิลด์วอร์กเกอร์จากรีลีสเดียวกับเซิร์ฟเวอร์

ขั้นตอนที่ 4: ตรวจสอบในแผงฟลีต

เปิด การสังเกตการณ์ ในแอปเดสก์ท็อปหรือเว็บ สลับไปแท็บ สด แล้วเลื่อนลงไป ล่างสุด เวิร์กเกอร์ แสดงรายการวอร์กเกอร์ที่ลงทะเบียนทุกตัวพร้อมแพลตฟอร์ม จำนวนคอร์ คีย์ความสามารถ และฮาร์ตบีตครั้งล่าสุด งาน แสดงรายการงานที่กระจาย อยู่ตามวอร์กเกอร์เหล่านั้น

การที่วอร์กเกอร์ของคุณปรากฏที่นั่นพร้อมฮาร์ตบีตล่าสุดคือหลักยืนยันว่าการจับคู่ และการลงทะเบียนสำเร็จ

จากไทล์ของวอร์กเกอร์ คุณสามารถ ระบาย มัน (ทำงานปัจจุบันให้จบ ไม่รับการเช่า ใหม่) ทำต่อ วอร์กเกอร์ที่กำลังระบาย เพิกถอน ข้อมูลรับรองของมัน หรือ นำออก แถวนั้น

แถวของวอร์กเกอร์และงานอยู่ใน global.db ของเซิร์ฟเวอร์ — ตัววอร์กเกอร์เขียน อะไรลงดิสก์นอกเหนือจากแคชการจัดเตรียม

สิ่งที่วอร์กเกอร์ประกาศ

ตอนลงทะเบียน วอร์กเกอร์จะตรวจจับความสามารถของตัวเองโดยอัตโนมัติ และตัวจัดตาราง จะจับคู่งานกับความสามารถเหล่านั้น คุณไม่ได้กำหนดค่าเหล่านี้ด้วยมือ:

• ระบบปฏิบัติการและสถาปัตยกรรม (macos/linux/windows, arm64/x64) — ตรวจสอบแบบแม่นยำ พร้อมตัวสำรองเป็น uname -m / PROCESSOR_ARCHITECTURE
• จำนวนคอร์และ RAM — จำนวนคอร์แบบแม่นยำ; RAM จะลดลงเหลือ 0 เมื่อตรวจสอบไม่ได้
• flutter — ตั้งค่าเมื่อเข้าถึง Flutter SDK ได้ (flutter เปล่า ๆ แล้วจึง fvm flutter); งานเรนเดอร์โกลเดนต้องใช้ค่านี้
• sandbox — native-macos บน macOS, native-linux บน Linux นี่เป็นเพียงคำใบ้สำหรับการวางงาน ไม่ใช่คำสัญญา: วอร์กเกอร์ประกาศแบ็กเอนด์ที่แพลตฟอร์มของมัน มี แต่ไม่ได้ห่องานที่มันรันไว้ในแบ็กเอนด์นั้น ต่างจาก cc_server ตัว cc_worker สปอว์นงานที่เช่าขึ้นมาตรง ๆ
• always-on และ parallel — cc_worker เฉพาะทางจะประกาศทั้งสองอย่างเสมอ จึงมีสิทธิ์รับชุด eval และความจุแบบขนานที่ใช้แล้วทิ้งอื่น ๆ

การตรวจจับเป็นแบบพยายามเต็มที่: สิ่งใดที่ตรวจสอบไม่ได้จะลดลงเป็นค่าเริ่มต้น ที่ปลอดภัย แทนที่จะทำให้การเริ่มระบบล้มเหลว

สิ่งที่วอร์กเกอร์จะประมวลผล

โปรโตคอลการเช่าพกชนิดงานหกชนิด:

ชนิด	สิ่งที่มันเป็น
agentRun	การรันเอเจนต์หนึ่งครั้ง (การสั่งงาน)
pipelineStep	การประมวลผลขั้นตอนไปป์ไลน์หนึ่งขั้น
codeIndex	การบิลด์ดัชนีโค้ดของรีโป
goldenRender	การเรนเดอร์โกลเดนเชิงภาพของ UI (ต้องมี flutter)
benchmark	การรันเบนช์มาร์กประสิทธิภาพ
evalBatch	ชุด eval (ชอบความจุแบบ parallel)

การประมวลผลเป็นการนำไปใช้จริงที่สตรีมโปรเซสย่อย ไม่ใช่รันไทม์ของเอเจนต์แบบฝังตัว เต็มรูปแบบ เมื่อการเช่าพา repoRemote มา วอร์กเกอร์จะ git clone --depth 1 ลงไดเรกทอรีแคชที่ใช้ remote และ SHA เป็นคีย์ จากนั้น git fetch และ git checkout สำหรับ agentRun มันจะรันคำสั่งใน CC_JOB_COMMAND ของ env การเช่าในไดเรกทอรีทำงาน สตรีม stdout และ stderr กลับมาเป็นเหตุการณ์; เมื่อไม่มี CC_JOB_COMMAND มันจะสะท้อนพรอมต์กลับ เพื่อให้เส้นทางขนส่งถูกใช้งานตั้งแต่ ต้นจนจบ ชนิดอื่นรันคำสั่งจริงขนาดเล็ก (git rev-parse HEAD, git --version) เป็นการตรวจสอบอย่างซื่อตรง ข้อมูลรับรองที่จำกัดขอบเขตตามงานใน env การเช่า จะถูกฉีดเข้าไปในโปรเซสย่อยทุกตัวและไม่ถูกเขียนลงล็อกเลย

เหตุการณ์จะถูกจัดกลุ่มและฟลัชทุก 250ms หรือทุก 32 เหตุการณ์; งานแต่ละงานจบด้วย เหตุการณ์ done และรายงานการเสร็จสิ้น โมเดลคือฮาร์ตบีตบวกการเช่าที่มี TTL สั้น: หากวอร์กเกอร์ขาดการติดต่อ การเช่าของมันจะหมดอายุ และเซิร์ฟเวอร์จะเก็บงานนั้น กลับไปลองใหม่ ไม่มีสถานะถาวรบนวอร์กเกอร์ และไม่มีความเห็นพ้องหรือการขโมยงาน ระหว่างวอร์กเกอร์

คู่มือที่เกี่ยวข้อง

• รันเซิร์ฟเวอร์แบบไม่มีส่วนติดต่อ
• เชื่อมต่อเซิร์ฟเวอร์ระยะไกล
• จับคู่อุปกรณ์

แนวคิดที่เกี่ยวข้อง

• การปรับใช้และไคลเอนต์