تشغيل عامل أسطول

شغّل cc_worker على جهاز متفرّغ لتضيف سعة تنفيذ إلى أسطولك. هو ثنائي Dart خالص — بلا محرّك Flutter — يقترن بـ cc_server، ويصرّح بقدرات المضيف، وينبض، ويسحب المهام المؤجَّرة، وينفّذها، ويبث أحداث العملية عائدة. لا يحتفظ بحالة دائمة: يعيد مشرف تشغيله فيسجّل نفسه من جديد.

تحتاج أولًا إلى cc_server يعمل — انظر تشغيل خادم بلا واجهة.

يسجّل العامل المقترن نفسه، وينبض، وينتظر المهام المؤجَّرة. تُرسل العمل بـ fleet.submitJob. إرسال الوكيل على هذا الخادم لا يمر بالأسطول؛ وعلامة النجاح في هذا الدليل أن يظهر العامل في لوحة الأسطول بنبضة حديثة. يُسجَّل عند الإقلاع عامل داخل العملية وخريطة منفّذاته فارغة، فتعيد المهمة الموضوعة عليه No local runner for job kind ….

المتطلبات

• Dart SDK. يحصر هذا المستودع إصدار الحزمة بـ fvm، فابدأ الأوامر بـ fvm.
• نسخة من هذا المستودع على جهاز العامل.
• cc_server يمكن بلوغه (loopback للتطوير، وLAN أو بعيد للإنتاج).
• git على PATH — يُجسّد العامل المستودعات ويشغّل سبر git.

الخطوة 1: بناء الثنائي

cd apps/cc_worker
fvm dart build cli

ينتج هذا حزمة مكتفية بذاتها في ./build/cli/<os_arch>/bundle/bin/cc_worker.

الخطوة 2: صك بيانات اعتماد العامل

لا يقبل cc_server إلا عاملًا يقدّم معرّف جهاز مقترن ومفتاحًا مشتركًا مسبقًا — بما في ذلك خادم loopback. صُكّهما على جهاز الخادم (يمكن تشغيل 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

إلى خادم loopback (مقترن هو أيضًا — cc_server يجري مصافحة PSK دائمًا):

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

العلم	الوصف	الافتراضي
--server <url>	عنوان cc_server (ws:///wss://؛ ويُحوَّل http(s) ومسار /rpc إن غاب). مطلوب.	—
--name <name>	اسم العامل كما يراه المشغّل.	اسم المضيف
--device-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 دليل الذاكرة المؤقتة لتجسيد شجرة العمل (الافتراضي: دليل cc_worker_cache تحت دليل النظام المؤقت).

يسجّل العامل نفسه بـ fleet.registerWorker، ثم ينبض كل 20 ثانية ويستطلع الإيجارات كل ثانيتين. يبقى يعمل حتى 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
• الأنوية والذاكرة — عدد الأنوية دقيق؛ وتتدهور الذاكرة إلى 0 حين يتعذّر سبرها
• flutter — تُضبط حين يُبلَغ Flutter SDK (flutter المجرّد، ثم fvm flutter)؛ ومهام التصيير الذهبي تشترطها
• sandbox — native-macos على macOS، وnative-linux على Linux. هذه إشارة توزيع لا وعد: يعلن العامل الخلفية التي تملكها منصته، لكنه لا يغلّف المهام التي يشغّلها بها. وبخلاف cc_server، يطلق cc_worker المهمة المؤجَّرة مباشرة
• always-on وparallel — يعلن cc_worker المخصّص الاثنتين دائمًا، فيصير مؤهّلًا لدفعات التقييم ولسائر السعة المتوازية العابرة

الكشف بأفضل جهد: ما يتعذّر سبره يتدهور إلى افتراض آمن بدل أن يفشل الإقلاع.

ما ينفّذه العامل

يحمل بروتوكول الإيجار ستة أنواع من المهام:

النوع	ما هو
agentRun	تشغيل وكيل واحد (إرسال)
pipelineStep	تنفيذ خطوة خط أنابيب
codeIndex	بناء فهرس الشفرة لمستودع
goldenRender	تصيير ذهبي مرئي للواجهة (يتطلب flutter)
benchmark	تشغيل معيار أداء
evalBatch	دفعة تقييم (تفضّل سعة parallel)

التنفيذ تنفيذ حقيقي يبث مخرجات العمليات الفرعية، لا بيئة تشغيل وكيل مضمّنة كاملة. حين يحمل الإيجار repoRemote، ينفّذ العامل git clone --depth 1 في دليل ذاكرة مؤقتة مفتاحه المستودع البعيد وSHA، ثم git fetch وgit checkout. وفي agentRun يشغّل الأمر الذي في CC_JOB_COMMAND ضمن بيئة الإيجار، داخل دليل العمل، ويبث stdout وstderr عائدة في صورة أحداث؛ وإن غاب CC_JOB_COMMAND أعاد المطالبة بالصدى حتى يُمارَس النقل من الطرف إلى الطرف. وتشغّل الأنواع الأخرى أوامر حقيقية صغيرة (git rev-parse HEAD، git --version) سبرًا صادقًا. بيانات الاعتماد المحصورة بالمهمة، داخل بيئة الإيجار، تُحقن في كل عملية فرعية ولا تُكتب في سجل.

تُجمَّع الأحداث وتُفرَّغ كل 250 مللي ثانية أو كل 32 حدثًا، وتنتهي كل مهمة بحدث انتهاء وتقرير إتمام. النموذج نبضات مع إيجارات قصيرة الأجل: إن انقطع اتصال عامل انتهت صلاحية إيجاره واسترد الخادم المهمة لإعادة المحاولة. لا حالة دائمة على العامل، ولا إجماع ولا انتزاع عمل بين العمال.

أدلة ذات صلة

• تشغيل خادم بلا واجهة
• الاتصال بخادم بعيد
• اقتران جهاز

مفاهيم ذات صلة

• النشر والعملاء