إعداد البيئات
البيئة هي المكدس العامل لمساحة واحدة: الخدمات التي يحتاجها فرع ما، معزولة عن كل المساحات الأخرى، ظاهرة في الشريط الجانبي ويمكن للوكلاء الوصول إليها. لطلبات السحب بيئة أيضًا، لأن لكل PR مساحته الخاصة أصلًا.
يكتب مسؤول مساحة العمل تعريفًا مرة واحدة. ثم يضغط الأعضاء بدء في قسم البيئة من الشريط الجانبي للمساحة أو PR. تُحفظ التعريفات في قاعدة بيانات مساحة العمل، لذا لا يغيّر فرع الميزة أبدًا ما يشغّله Control Center، مع أن الأدوات تظل تشغّل كود ذلك الفرع.
إنشاء تعريف
قسم بعنوان “إنشاء تعريف”- افتح الإعدادات ← مساحة العمل ← البيئات. يمكن لمسؤولي مساحة العمل فقط تغيير التعريفات، ولا يستطيع حفظ تعريف يعمل على مضيف الخادم إلا مالك الخادم (انظر من يستطيع حفظ ماذا).
- انقر تعريف جديد، ثم تعريف فارغ أو مسودة من المستودع. تبحث المسودة في المستودع عن ملفات compose وملف
Procfileوسكربتاتpackage.json، وتراجع أنت النتيجة. - املأ النموذج، أو استخدم علامة التبويب JSON. الأمثلة في هذه الصفحة هي ذلك JSON.
- انقر تشغيل الاختبار. يبدأ ذلك بيئة مؤقتة، وينتظر حتى تصبح جاهزة، ثم يدمرها.
يتحقق الحفظ من التعريف بصرامة. يُرفض أي حقل غير معروف، أو قيمة من نوع خاطئ، أو اختيار مكتوب بشكل خاطئ، مع ذكر مساره واسم أقرب قيمة صالحة، مثل repos.app.requird: Unknown field. Did you mean "required"?. يُسمح بـ $schema على المستوى الأعلى.
للاحتفاظ بتعريف في مستودع، استخدم ربط ملف من المستودع. يقرأ Control Center الملف من الفرع الافتراضي فقط ويشغّل فقط النسخة التي وافق عليها مسؤول مساحة العمل، أو مالك الخادم حين يعمل التعريف على المضيف. تعرض النسخة الأحدث يتوفر تحديث ولا تغيّر شيئًا حتى تتم الموافقة عليها.
من يستطيع حفظ ماذا
قسم بعنوان “من يستطيع حفظ ماذا”قد يشغّل تعريف البيئة أوامر على مضيف الخادم بصفة مستخدم الخادم نفسه. هذا قرار مالك الخادم، لا دور في مساحة العمل:
- يعمل التعريف على المضيف حين يكون له موضع على المضيف، أو فحص يشغّل أمرًا، أو مهمة
provisionأوarchive. تعمل هذه المهام في شجرة عمل المساحة على المضيف أيًّا كان موضعه. - لا يستطيع حفظ تعريف يعمل على المضيف أو اعتماده إلا مالك الخادم. ويشمل ذلك اعتماد نسخة جديدة من ملف مستودع مربوط. يقول مسؤول مساحة العمل الذي يحاول ذلك: «يمكن لمالك الخادم وحده حفظ بيئة تعمل على مضيف الخادم أو اعتمادها. يمكن لمسؤول مساحة العمل استخدام بيئة تعمل داخل Rig.»
- يستطيع مسؤول مساحة العمل حفظ تعريف يعمل بالكامل داخل منصة rig واعتماده:
"placement": "rig"، من غير أمر فحص ومن غير مهمةprovisionأوarchive. - يبدأ الأعضاء البيئات ويوقفونها ويستخدمونها في الحالتين.
- لا يعمل تعريف يعمل على المضيف إلا بعد أن يحفظه مالك الخادم الحالي أو يعتمده. يسجّل الخادم هذا الاعتماد بنفسه، ويتحقق منه قبل كل بدء وفحص ومهمة ومزامنة لرأس طلب السحب. التعريف الذي لم يعتمده المالك الحالي، مثل تعريف حفظه مالك سابق، ينتظر تحت صفّه في قائمة البيئات وفي المحرّر. يرى مالك الخادم عبارة «تعمل على هذا الخادم. اعتمدها للسماح ببدء تشغيلها.» مع زر موافقة، وهو يحفظها دون تغيير؛ ويرى الآخرون «تعمل على هذا الخادم. يجب أن يعتمدها مالك الخادم قبل أن تبدأ.»
- البيئة المعلّقة بانتظار هذا الاعتماد تقول «لم يعتمد مالك الخادم هذه البيئة بعد، لذلك لا يمكنها العمل على هذا الخادم.» أما مالك الخادم فيرى «لم تعتمد هذه البيئة بعد. تعمل على هذا الخادم، لذلك ستبدأ بعد أن تعتمد تعريفها.» مع زر المراجعة والاعتماد، الذي يفتح التعريف.
- تعمل طرفيات العمليات في البيئة، والطرفية التي يفتحها البدء حين يحتاج إليك، على مضيف الخادم. الكتابة فيها أو تغيير حجمها أو إغلاقها تحتاج إلى صلاحية كتابة على كل مستودع تعرضه المساحة، تُقرأ بتسجيل دخول منصتك الخاص، وهذا هو الشرط نفسه لبدء البيئة. لا يصل أي شخص آخر إلى هذه الطرفيات أصلًا.
أصغر تعريف
قسم بعنوان “أصغر تعريف”يحتاج مستودع compose بسيط إلى هذا فقط:
{ "contract": 1, "name": "Shop", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "components": [ { "kind": "compose", "id": "stack" } ]}كل ما عدا ذلك له قيمة افتراضية: يُكتشف ملف compose، وتعمل كل الخدمات، وتُخصص المنافذ، وتُكتشف نقاط نهاية HTTP، وتأخذ البيئة اسم الفرع.
أنواع المكونات
قسم بعنوان “أنواع المكونات”البيئة قائمة مرتبة من المكونات. ينتظر كل مكون أن يصبح السابق جاهزًا، ما لم يحدد after غيره، ويجري الإيقاف بالترتيب العكسي. يجعل enabledWhen المكون مشروطًا بخيار أو دور، مثل opt.seed أو !opt.seed أو repo.web. يُستبعد المكون الذي يكون دوره اختياريًا وغير موجود في المساحة بالطريقة نفسها، دون حاجة إلى enabledWhen: لا يبدأ ولا يملك {port.*} أو {url.*}، فيفشل بدء أي مكون آخر يقرأ هذه القيم.
| النوع | من يشغّله | الاستخدام |
|---|---|---|
compose |
مشغّل compose في Control Center | أي ملف compose، واحد لكل بيئة |
cli |
أداتك. يستدعي Control Center الأفعال المعيّنة ويقرأ JSON | أداة تملك دورة حياتها ونطاقاتها وبياناتها |
process |
Control Center، في جلسة طرفية خاضعة للإشراف | خوادم التطوير والعمال |
task |
Control Center، مرة لكل مشغّل | التثبيت والترحيل والاختبارات |
app |
Control Center، عندما ينقر أحدهم تشغيل التطبيق | تطبيق سطح مكتب |
تأخذ مكونات task قائمة when:
| المشغّل | وقت التشغيل |
|---|---|
provision |
عند إنشاء شجرة العمل (راجع مهام شجرة العمل أدناه) |
create |
مرة لكل بيئة، ومرة أخرى بعد إعادة الضبط |
start |
عند كل بدء |
change |
بعد المزامنة، عندما يطابق مسار متغيّر onChange |
manual |
عند الطلب: تشغيل أو cc-env run <id> أو environment_run_task |
archive |
قبل تدمير شجرة العمل مباشرة |
تعرض المهمة التي لا شيء لها لتفعله عند البدء الحالة خامل، ولا تظهر في قائمة الخطوات المعروضة أثناء بدء البيئة: وهي مهمة manual أو change، أو مهمة create سبق أن نُفذت.
الأمر المعطى كمصفوفة هو argv، لذا لا تمر قيم الخيارات عبر صدفة أبدًا. تعمل السلسلة النصية، أو script مع مصفوفة أسطر، تحت bash -lc. لا تُوسَّع العناصر النائبة مثل {name} و{branch} و{stateDir} و{repo.<role>} و{port.<key>} و{opt.<key>} و{url.<role>} إلا في argv. تقرأ أوامر الصدفة القيم نفسها كمتغيرات CC_ENV_*، مثل $CC_ENV_PORT_WEB. يوقف أي عنصر نائب غير معروف في مكون مشارك البدء قبل تشغيل أي شيء.
يحصل كل أمر وطرفية مساحة أيضًا على CC_ENV_NAME وCC_ENV_STATE_DIR وCC_ENV_URL وCC_SPACE_ID وCC_ENV_REPO_<ROLE>، وفي مساحات PR على CC_PR_NUMBER وCC_PR_IS_FORK. ومع مكون compose يحصلان أيضًا على COMPOSE_PROJECT_NAME وCOMPOSE_FILE، فيصل docker compose exec داخل مهمة إلى المشروع الصحيح.
الأدوار ودليل العمل
قسم بعنوان “الأدوار ودليل العمل”يربط التعريف أدوارًا بمستودعات مساحة العمل، فيمكن لمكدس واحد أن يمتد عبر عدة مستودعات:
"repos": { "api": { "repoId": "<api>", "anchor": true, "required": true }, "web": { "repoId": "<web>", "anchor": true }, "e2e": { "repoId": "<e2e>", "whenMissing": "useSource" }}anchor: يمكن لمساحة بدء البيئة إذا احتوت على دور مرساة واحد على الأقل. إذا تطابق تعريفان، يختار من يبدأ.required: لا يعمل المكدس من دون هذا المستودع.whenMissing: ما يحدث عندما تفتقد المساحة الدور. يضيفaddToSpaceالمستودع على فرعه الافتراضي وهو الافتراضي لأدوارrequired. يمررuseSourceنسختك المسجلة، وعليك معاملتها كقراءة فقط. يتركskipالمتغير بلا قيمة وهو الافتراضي في غير ذلك.- يتطلب البدء منحة
writeعلى مستودع مرساة في المساحة ووصول قراءة إلى كل مستودع مرتبط آخر.
يعمل الأمر في أول دور معلن في repos، لا في دور آخر قد تملكه المساحة بالمصادفة، لذا لا يذكره التعريف ذو المستودع الواحد أبدًا. يمكن لأي مكون تجاوز ذلك عبر "cwd": { "role": "e2e", "path": "packages/ui" }. كلا الحقلين اختياري. وعندما يمكن ألا يوجد الدور الأول في مساحة، لأنه ليس required ولا المرساة الوحيدة، يجب على كل مكون أن يسمّي دوره.
المنافذ وعناوين URL
قسم بعنوان “المنافذ وعناوين URL”يخصص Control Center منافذ المضيف قبل بدء أي شيء، من نطاق مشترك على مستوى المضيف (من 42000 إلى 49999 افتراضيًا، في كتل من 32). يبقى المنفذ نفسه طوال عمر البيئة، وترتبط منافذ compose بـ 127.0.0.1 فقط.
- لا تحتاج منافذ compose إلى تصريح. اقرأها بصيغة
{port.postgres.5432}أوCC_ENV_PORT_POSTGRES_5432. - يُصرَّح عن المنافذ الأخرى حيث تُستخدم، عبر
"port": "web"أو"ports": ["web", "hmr"]، وتُقرأ بصيغة{port.web}. تحصل العملية ذات المنفذ أيضًا علىPORTوHOST=127.0.0.1.
تحصل نقاط نهاية HTTP على عنوان URL على موجّه الخادم، الذي يستمع على منفذ استرجاع واحد:
http://<endpoint>--<name>--<project>.localhost:<router port>http://web--fix-login--shop.localhost:7355<name>هو الفرع بصيغة slug، أوpr-<n>في مساحة PR. و<project>هوnaming.project، وإلا فاسم التعريف.- تشير أسماء
*.localhostإلى الاسترجاع، فلا تحتاج إلى إدخالات hosts أو DNS، ويفصل اسم المضيف ملفات تعريف الارتباط بين البيئات. - تُكتشف منافذ compose التي تستجيب لـ HTTP، ويتجاوز
httpعلى المكون هذا التخمين. تحتاج العملية إلى"endpoint": { "role": "web", "primary": true }، الذي يتيح أيضًا{url.web}. - في المتصفح (VM)، استخدم فتح في Browser (VM). يصل
https://web--fix-login--shop.localhost/هناك إلى المسار نفسه. - تبقى التسمية كاملة ضمن 63 حرفًا، لذا تُختصر الأسماء الطويلة بتجزئة.
- لا تشترك نقطتا نهاية في نطاق أب. على التطبيق الذي يحتاج إلى ملف تعريف ارتباط واحد عبرهما أن يقدمهما من نقطة نهاية واحدة.
لعناوين URL التي يجب تسجيلها مسبقًا، مثل عمليات إعادة توجيه OAuth، يعطي "naming": { "pool": { "names": "cc{n}", "size": 8 }, "project": "shop" } مجموعة ثابتة من الأسماء.
يقرر policy متى تعمل البيئات. قيمة autoCreate هي off أو prSpaces أو allSpaces، وقيمة idleStopMinutes الافتراضية 240، ويزامن followPrHead بيئة PR عند تحرك رأسها، ومع maxRunning (الافتراضي 6) يعرض بدء إيقاف أقدم بيئة استخدامًا.
مثال: تطبيق compose
قسم بعنوان “مثال: تطبيق compose”تطبيق ويب وPostgres من ملف compose واحد، مع .env يتجاهله git وعمليات ترحيل ومهمة اختبار. ينسخ seedFiles ملفات مسماة من نسختك المسجلة إلى كل شجرة عمل جديدة.
{ "contract": 1, "name": "Shop", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "naming": { "project": "shop" }, "seedFiles": [".env"], "components": [ { "kind": "compose", "id": "stack", "services": ["postgres", "web"], "healthchecks": { "postgres": ["pg_isready", "-U", "postgres"] } }, { "kind": "task", "id": "migrate", "when": ["create", "change"], "onChange": ["db/migrations/**"], "command": "docker compose exec -T web bin/migrate" }, { "kind": "task", "id": "test", "when": ["manual"], "command": "docker compose exec -T web bin/test" } ]}يتيح healthchecks لخدمة بلا فحص صحة خاص بها أن تؤخر المكون التالي. من دونه تُعد الحاوية العاملة جاهزة، وقد تسبق عمليات الترحيل قاعدة بيانات ما زالت تبدأ.
تُنفَّذ كل عملية بدء وتحديث بالأمر up مع --remove-orphans، فتتوقف الخدمة التي أُزيلت من ملف compose وتحرر منفذها. تُبنى الصور عند البدء وعند التحديث، ما لم يضبط المكون "build": false.
مثال: CLI مخصصة
قسم بعنوان “مثال: CLI مخصصة”أداة خيالية acme تملك حاوياتها ونطاقاتها وTLS الخاص بها. يوفر Control Center القيمة {name} ويعرف الباقي من status. لا يستنتج أبدًا أسماء مضيفي الأداة ولا يحرر /etc/hosts أبدًا.
{ "contract": 1, "name": "Acme", "repos": { "server": { "repoId": "<server>", "anchor": true, "required": true }, "web": { "repoId": "<web>", "anchor": true } }, "routing": { "mode": "tool", "domain": "acme.test", "upstream": "127.0.0.1:443", "tls": true, "caFile": "~/.acme/tls/ca.crt" }, "components": [ { "kind": "cli", "id": "acme", "verbs": { "create": ["acme", "env", "create", "{name}", { "if": "!interactive", "args": ["--json"] }, { "if": "repo.web", "args": ["--web-dir", "{repo.web}"] }], "start": ["acme", "env", "start", "{name}"], "stop": ["acme", "env", "stop", "{name}"], "destroy": ["acme", "env", "destroy", "{name}", "--yes"], "reset": ["acme", "env", "reset-db", "{name}"], "status": ["acme", "env", "status", "{name}", "--json"], "list": ["acme", "env", "ls", "--json"], "logs": ["acme", "env", "logs", "{name}", { "if": "service", "args": ["{service}"] }, "--tail", "{tail}", { "if": "follow", "args": ["--follow"] }], "exec": ["acme", "env", "exec", "{name}", "{service}", "{command}"] }, "interactive": ["create"], "keepsDataOnStop": false, "statusMap": { "state": [ { "when": { "path": "/status/ready", "equals": true }, "state": "ready" }, { "when": { "none": "/status/containers", "where": { "state": "running" } }, "state": "stopped" }, { "when": { "path": "/status/phase", "equals": "failed" }, "state": "failed" }, { "state": "starting" } ], "detail": "phase: {/status/phase}", "warnings": [ { "when": { "path": "/status/dnsWorking", "equals": false }, "message": "Not resolvable on this host" } ], "endpoints": [ { "role": "app", "label": "App", "url": "/urls/app", "primary": true }, { "role": "db", "hostPort": "/ports/db" } ], "services": "/status/containers/*/service", "list": "/*/slug", "missingErrorCodes": ["env.not-found"] } } ]}createوstatusوdestroyمطلوبة. يختار Control Center بينcreateوstartمن الحالة التي يقرؤها. يمكن أن يكون أي فعل{ "shell": "…" }بدل argv.- يحدد
interactiveالأفعال، من بينcreateوstartوreset، التي يمكنها أن تطلب ما تحتاجه في طرفية. وعندما يخرج فعل من هذه الأفعال بالرمز 3 لشخص ضغط بدء، يشغّل Control Center الفعل نفسه مرة أخرى في لسان طرفية، ويستمر البدء بعد خروجه بالرمز 0. هناك يكون الشرطinteractiveصحيحًا ويُضبطCC_ENV_INTERACTIVE=1، لذا يُبقي{ "if": "!interactive", "args": ["--json"] }المخرجات الآلية للأنبوب. لا يفتح البدء الذي يبدأه وكيل، أو البدء التلقائي، طرفية أبدًا: تقرأ البيئة يلزم إجراء وتنتظر. - عندما يفشل
destroyتُزال البيئة مع ذلك إذا أبلغstatusبعدها أنهاmissing، فيمكن دائمًا إزالة بيئة لم تعد الأداة تملكها. - يتيح
listلـ Control Center أن يلاحظ بيئة فقدتها الأداة. لا تُعلَّم البيئة كمفقودة إلا عندما يغيب اسمها منlistويقولstatusبعد ذلكmissing. المخرجات التي لا يمكن قراءتها كقائمة لا تغيّر شيئًا. - يجب أن يكون
{service}فيlogsوexecكلمة واحدة لا تبدأ بـ-، وأن تكون إحدى الخدمات التي أبلغت عنها الأداة آخر مرة، عندما أبلغت عن أي خدمة. - يقرأ
statusMapملف JSON الخاص بالأداة بمؤشرات JSON، حيث يطابق*كل عنصر. قواعد الحالة مرتبة وتفوز أول مطابقة. الشرط هوpathمعequals، أوanyأوnoneمعwhere. - يوقف
keepsDataOnStop: falseالإيقاف عند الخمول ويضيف تحذير فقدان بيانات إلى إيقاف. اضبطه عندما يفقد الإيقاف البيانات. - يوصل
routing.mode: "tool"أسماء مضيفي الأداة بالمتصفح (VM) والوكلاء. يجب أن ينتهي النطاق بـ.testأو.localhostأو.internal، ويُسقط أي عنوان URL مُبلَّغ عنه خارجه.
يمكن لأداة تملكها الاستغناء عن statusMap وطباعة عقد الحالة الموضح في نهاية هذه الصفحة.
مثال: مستودع pnpm أحادي
قسم بعنوان “مثال: مستودع pnpm أحادي”عمليات ومهام فقط، بلا حاويات. يجد تطبيق الويب واجهة API عبر {url.api}.
{ "contract": 1, "name": "Monorepo", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "naming": { "project": "mono" }, "options": [ { "key": "seed", "type": "bool", "default": true, "agentDefault": false } ], "components": [ { "kind": "task", "id": "install", "when": ["provision", "change"], "onChange": ["pnpm-lock.yaml"], "command": ["pnpm", "install", "--frozen-lockfile"] }, { "kind": "process", "id": "api", "label": "API", "port": "api", "cwd": { "path": "apps/api" }, "command": ["pnpm", "dev"], "endpoint": { "role": "api" }, "ready": { "http": "http://127.0.0.1:{port.api}/health", "timeout": 120 }, "restartOn": ["pnpm-lock.yaml"] }, { "kind": "task", "id": "seed", "when": ["create"], "enabledWhen": "opt.seed", "cwd": { "path": "apps/api" }, "command": ["pnpm", "db:seed"] }, { "kind": "process", "id": "web", "label": "Dev server", "port": "web", "cwd": { "path": "apps/web" }, "env": { "API_URL": "{url.api}" }, "command": ["pnpm", "dev", "--port", "{port.web}", "--host", "127.0.0.1"], "endpoint": { "role": "web", "primary": true }, "ready": { "http": "http://127.0.0.1:{port.web}/" } }, { "kind": "task", "id": "lint", "when": ["manual"], "command": ["pnpm", "lint"] } ]}- كل عملية علامة تبويب طرفية يمكنك فتحها وقراءتها، والكتابة فيها إن كانت لديك صلاحية كتابة على كل مستودع في المساحة (انظر من يستطيع حفظ ماذا). إغلاق علامة التبويب لا يوقفها.
- يأخذ
readyالقيمhttp(عنوان URL كامل) أوtcp(host:port) أوlogMatch(تعبير منتظم). قيمةrestartهيon-failure(الافتراضية) أوalwaysأوnever. يعيدrestartOnتشغيل العملية عند مطابقة مسار متغيّر. - تصبح
optionsنموذجًا عند بدء، وينطبقagentDefaultعلى التشغيلات التي يبدأها وكيل.
مثال: تطبيق سطح مكتب
قسم بعنوان “مثال: تطبيق سطح مكتب”تطبيق سطح مكتب مع خطوة بناء. يعمل التطبيق بالطريقة نفسها أيًا كانت تقنيته، لأن Control Center يعمل على مستوى نوافذ نظام التشغيل ولا يحتاج إلى خطاف أو SDK في التطبيق.
{ "contract": 1, "name": "Studio", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "components": [ { "kind": "task", "id": "build", "when": ["manual"], "command": ["pnpm", "build"] }, { "kind": "app", "id": "desktop", "label": "Studio", "prepare": "build", "command": ["dist/mac-arm64/Studio.app/Contents/MacOS/Studio"], "isolate": "home" } ]}لا يبدأ التطبيق مع البيئة. ينقر أحدهم تشغيل التطبيق، ويعمل prepare أولًا. يعيد إعادة البناء والتشغيل تشغيل هذا الزوج. ينطبق enabledWhen على التطبيق وعلى مهمة prepare الخاصة به، ويُرفض تشغيل التطبيق ما دام أيٌّ منهما معطَّلًا. يُعد التطبيق عاملًا ما دامت أي عملية في مجموعة عملياته تعمل، فيكفي أن يبدأ المشغّل التطبيق ثم يخرج. إذا اختفت كل العمليات خلال نحو 5 ثوانٍ من تشغيل التطبيق، يظهر التطبيق فاشلًا مع آخر أسطر سجله. بعد ذلك يظهر الخروج السليم كمغلق والتعطل بعرض آخر أسطر السجل، ولا يعيد أيٌّ منهما تشغيله. يغلق إعادة تشغيل الخادم التطبيق ولا يعيد تشغيله أبدًا، ويترك الإيقاف عند الخمول التطبيق العامل وشأنه.
أذونات تطبيقات سطح المكتب وحدودها
قسم بعنوان “أذونات تطبيقات سطح المكتب وحدودها”- على macOS، امنح Control Center تسجيل الشاشة وتسهيلات الاستخدام مرة واحدة في إعدادات النظام. يحتاج مضيف الخادم إلى جلسة رسومية: يرفض الخادم عديم الواجهة تشغيل تطبيق.
- شغّل الملف التنفيذي مباشرة. يسلّم
open -aالتطبيق إلى LaunchServices فيغادر شجرة العمليات التي يتتبعها Control Center، فيظهر التطبيق فاشلًا مباشرةً بعد التشغيل. - تبقى النوافذ على شاشة. لا يلتقط macOS نافذة خارج كل الشاشات، لذا يظهر التطبيق الذي يستخدمه وكيل على شاشة الخادم. لا يحتاج إلى التركيز.
- يمنح
"isolate": "home"التطبيق دليلًا منزليًا خاصًا عبرHOMEوXDG_*وCFFIXED_USER_HOME، لتعمل نسخ من مساحتين جنبًا إلى جنب. لا يُعزلNSUserDefaults، لذا تبقى تفضيلات Cocoa وshared_preferencesفي Flutter مشتركة بين النسخ. - ينطبق
isolateعلى العملية المشغّلة فقط. يحتاج مشغّل سلسلة أدوات مثلflutter runإلى الدليل المنزلي الحقيقي، لذا استخدمisolateمع ملف تنفيذي مبني. إذا كان للتطبيق إعداد خاص، مثل--user-data-dir، ففضّله. - يتحكم الوكلاء في النافذة عبر
app_use، الذي لا يصل إلا إلى شجرة عمليات هذه البيئة. يرى الوكيل النافذة، لا سطح المكتب. تمر عمليات التشغيل من الوكلاء عبر سياسة الإجراءات وتسأل افتراضيًا، ويتوقف إدخال الوكيل ما دام شخص يملك التحكم. - يرسل
"input": "background"(الافتراضي) الأحداث إلى العملية. ينشّط"foreground"النافذة ويستحوذ على المؤشر.
مهام شجرة العمل
قسم بعنوان “مهام شجرة العمل”تُشغّل مهام provision وarchive إعداد المستودع وتفكيكه مع شجرة عمله. تفتح الأيقونة في صف المستودع ضمن الإعدادات ← مساحة العمل ← المستودعات تعريف المستودع.
تتبع هذه المهام شجرة العمل لا البيئة، لذا تعمل في مساحات لا يضغط فيها أحد بدء:
provision |
archive |
|
|---|---|---|
| تعمل | عند إنشاء شجرة عمل الدور، في أي مساحة | قبل تدمير شجرة العمل تلك مباشرة |
| عند الفشل | يفشل التجهيز وتُدمَّر شجرة العمل | يُسجَّل ولا يمنع الحذف أبدًا |
| المهلة الافتراضية | 5 دقائق | دقيقتان |
| ترى | CC_WORKSPACE_PATH وCC_ROOT_PATH وCC_SPACE_* وCC_REPO_NAME |
الشيء نفسه |
يحتاج المستودع بلا مكدس إلى تعريف يحمل مهامه فقط. ولأنه لا يوجد ما يُبدأ، لا يلزم دور مرساة:
{ "contract": 1, "name": "Web", "repos": { "app": { "repoId": "<id>" } }, "components": [ { "kind": "task", "id": "setup", "when": ["provision"], "script": ["pnpm install", "cp \"$CC_ROOT_PATH/.env\" .env"] } ]}- لا توجد بيئة بعد، لذا لا يمكن لهذه المهام استخدام
{name}أو{port.*}أو{url.*}أو{opt.*}أوenabledWhen، ولا تحصل علىenvالخاص بالتعريف. - يمكن لتعريف واحد فقط أن يحمل مهام
provisionوarchiveلمستودع. يمكن للتعريفات الأخرى ربطه لكل ما عدا ذلك. - يعيد
"when": ["provision", "change"]التثبيت أيضًا عند تغيّر ملف القفل. - تعمل المهمة لشجرة عمل دور
cwdالخاص بها، لذا يمكن لتعريف متعدد المستودعات إعداد كل مستودع على حدة. - يضبط التشغيل التجريبي
CC_SCRIPT_TEST=1. تبدأ إعادة المحاولة من شجرة عمل نظيفة، فاكتب مهامًا تتحمل إعادة التشغيل.
الوكلاء
قسم بعنوان “الوكلاء”لا يحصل الوكلاء أبدًا على مقبس Docker. في مساحة ذات تعريف مؤهل، يحصل التشغيل على cc-env في PATH الخاص به. تأتي المساحة من التشغيل، لذا لا يمكن للوكيل التصرف إلا في بيئته، ويمر كل أمر عبر سياسة الإجراءات.
cc-env statuscc-env upcc-env downcc-env resetcc-env destroycc-env restart <process>cc-env logs <name>cc-env exec <service> -- <cmd>cc-env run <task> -- <args>مع مكون compose، يسمح رقاقة docker أيضًا بـ docker compose مع ps وlogs وexec وport وrestart وtop، ولا يعمل إلا على مشروع compose الخاص بهذه البيئة. لا يجوز وضع رايات قبل الفعل، ولكل فعل قائمة قصيرة من الخيارات: لا يمكن لـ logs المتابعة، ولا يقبل exec إلا -T (أو --no-tty). تُرفض الخيارات التي توجّه compose إلى ملف أو مشروع آخر (-f و-p و--project-directory و--env-file و--profile) أينما وردت. أي شيء آخر ينتهي بالرمز 5 والرسالة «not available in Control Center agent runs».
يمكن لمستودع تستدعي مهاراته أداته الخاصة الاستمرار في ذلك. تصرّح كتلة agentPassthrough على مكون cli بالأوامر التي يمكن للوكلاء تشغيلها. لا يمر إلا الأوامر التي يصرّح بها التعريف المعتمد، وينفَّذ كل منها على المضيف، لذلك تسري عليه قاعدة تشغيل الأوامر على المضيف، التي تسأل أولًا افتراضيًا:
"agentPassthrough": { "binary": "acme", "allow": [ { "argv": ["env", "ls"], "maps": "status", "nameFilter": true }, { "argv": ["env", "status|url"], "maps": "status", "positionalName": 2 }, { "argv": ["env", "create"], "maps": "up", "positionalName": 2, "pathFlags": ["--web-dir"], "denyFlags": ["--force"] }, { "argv": ["env", "logs"], "maps": "logs", "positionalName": 2, "denyFlags": ["--follow"] } ]}يسمّي maps العملية التي تنطبق سياستها. يفرض positionalName ذلك الوسيط على بيئة هذه المساحة، ويرشّح nameFilter مخرجات JSON إليها، ويجب أن تُحل كل قيمة pathFlags داخل أشجار عمل التشغيل. الأمر الذي لا يطابق أي قاعدة ينتهي بالرمز 5.
العمليات نفسها متاحة كأدوات: environment_status وenvironment_up وenvironment_down وenvironment_reset وenvironment_destroy وenvironment_restart وenvironment_exec وenvironment_logs وenvironment_run_task وenvironment_launch_app وenvironment_stop_app. يصل الوكلاء في صندوق الحماية إلى منافذهم مباشرة وإلى أسماء مضيفي بيئتهم عبر وكيل الشبكة الخاص بالتشغيل، لذا اطلب منهم قراءة نقاط النهاية من environment_status بدل تخمين عنوان URL.
طلبات السحب من التفرعات
قسم بعنوان “طلبات السحب من التفرعات”كود PR من تفرع غير موثوق، وفي الوضع على المضيف يعمل بصفته مستخدم نظام تشغيل الخادم. يقرر policy.forkPrs ما يحدث:
| القيمة | الأثر | الافتراضي لـ |
|---|---|---|
rig |
يعمل ملف compose في VM بلا مطالبة | التعريفات ذات مكونات compose وtask فقط |
approval |
يحتاج كل بدء إلى مسؤول | كل التعريفات الأخرى |
deny |
مرفوض | لا شيء |
- لا تُنسخ
seedFilesأبدًا إلى تفرع، لأنها عادة أسرار. يُبلغ ملف compose الذي يربط أحدها عن الملف المفقود باسمه. - تُتخطى مهام
provisionوarchiveما لم تكن السياسةrig، وعندها تعمل في VM. - في الوضع على المضيف، تُرفض على التفرع
privilegedومساحات أسماء المضيف وربط مقبس Docker وdevicesوالروابط خارج أشجار عمل المساحة. في المساحات الموثوقة تكتفي بالتحذير.
الوضع في منصة rig
قسم بعنوان “الوضع في منصة rig”يشغّل "placement": "rig" مكونات compose وtask في microVM مخصص. التعريفات ذات مكونات process أو cli أو app غير مؤهلة. يعمل ملف compose بلا تعديل، من دون مقبس Docker للمضيف ومن دون بيانات اعتماد المشغّل، ويقتصر الوصول إلى الشبكة على السجلات التي تحتاجها صوره. تُركَّب شجرة العمل مباشرة.
- ضيوف arm64. الضيوف arm64 على Apple Silicon، لذا لا تعمل الصور المخصصة لـ amd64 فقط.
- تُرفض السجلات الخاصة. لا يملك الضيوف بيانات اعتماد السجلات، لذا تُرفض الصورة الموجودة في سجل خارج السجلات العامة المعروفة قبل إقلاع VM. يفشل المستودع الخاص في سجل عام عندما يسحبه الضيف.
- تخزين 16 جيبيبايت. تتشارك كل صور المكدس وأحجامه قرصًا واحدًا بسعة 16 GiB، ولا يمكن زيادته.
- الإقلاع الأول بطيء. طبقات الصور خاصة بكل VM، لذا يسحب الإقلاع الأول كل شيء. تحتفظ منصة rig المتوقفة بقرصها.
- يجب أن تكون الصور الأساسية مقروءة. لا يمكن التخطيط لملف Dockerfile يسمي صورته الأساسية عبر متغير، لأن الوصول إلى الشبكة يُثبَّت عند الإقلاع.
- العمر. ينهي
policy.rigTtlHoursالجهاز الافتراضي، بعد 24 ساعة افتراضيًا.
عقد الحالة لمؤلفي الأدوات
قسم بعنوان “عقد الحالة لمؤلفي الأدوات”يتوقع مكون cli بلا statusMap العقد الأصلي cc-env/1. يطبع الفعل status هذا الكائن على stdout:
{ "state": "ready", "detail": "migrations applied, HTTP 200", "endpoints": [ { "role": "app", "label": "App", "url": "https://fix-login.acme.test", "primary": true }, { "role": "postgres", "label": "Postgres", "hostPort": 49213 } ], "services": ["server", "postgres"], "needsRecreate": false, "error": { "code": "post-start-failed", "message": "…", "hint": "…", "command": "…" }}- قيمة
stateهيreadyأوstartingأوstoppedأوfailedأوmissing. يقودmissingإلىcreate، ويقودstoppedوfailedإلىstart. أبلغ عنmissingبرمز الخروج 0: يُحتسبstatusالفاشلfailed. stateوحده مطلوب. تُتجاهل الحقول غير المعروفة، وتظهر المخرجات غير القابلة للتحليل كمتدهورة، مع النص الخام كتفصيل.- يجب أن يكون عنوان URL استرجاعًا أو
*.localhostأو تحتrouting.domain، وإلا يُسقط. - يعرض
needsRecreate: trueالإجراء إعادة الإنشاء الذي يتخلص من البيانات. لا يتصرف Control Center بناءً عليه من تلقاء نفسه. - يطبع الفعل
listمصفوفة JSON من الأسماء، أو من كائنات تحويname.
تنطبق رموز الخروج على كل فعل:
| الرمز | المعنى |
|---|---|
| 0 | موافق |
| 3 | تلزم إجابة في طرفية، مثل كلمة مرور sudo. يعمل الفعل المدرج في interactive مجددًا في لسان طرفية لمن ضغط بدء. وإلا يفتح تشغيل في الطرفية طرفية مساحة يُكتب فيها الأمر command الخاص بالأداة دون تشغيله، ثم يحاول إعادة المحاولة مجددًا. لا يشغّل Control Center الأمر sudo أبدًا ولا يجيب عن أي طلب. |
| 4 | تسجيل الدخول مطلوب. يوضح command الخاص بالأداة الطريقة |
| 5 | شيء تعتمد عليه غير متاح، مثل بيئة تشغيل الحاويات التي لا تعمل |
| غير ذلك | فشل |
الرموز 3 و4 و5 ليست فشلًا. تقرأ البيئة يلزم إجراء وتنتظر، ويكمل البدء التالي من حيث توقف ذلك البدء. وتعني المهمة التي تخرج برمز منها الشيء نفسه.
يذهب التقدم إلى stderr بصيغة JSON مفصول بأسطر:
{"type":"step","id":"images","label":"Pull images","state":"running"}{"type":"log","stream":"stdout","line":"postgres Pulled"}{"type":"step","id":"images","label":"Pulled 4 images","state":"done"}{"type":"note","level":"warn","message":"Hosts entries stayed behind after destroy"}{"type":"error","code":"hosts-missing","message":"Add the hosts entry","hint":"Needs sudo","command":"sudo acme hosts add fix-login"}عند بدء تشغيل البيئة، تعرض اللوحة المكونات التي تمر بها عملية البدء، ولكل منها مؤشر دوران أو علامة صح أو علامة خطأ. يوضح سطر step ما تفعله الأداة الآن، ويظهر label الخاص به أسفل صف الأداة نفسها، ولا تضيف الخطوات صفوفًا خاصة بها أبدًا. تكون حالة الخطوة state إما pending أو running أو done أو failed، والخطوة التي لا تحمل state تُعد قيد التشغيل. والخطوة التي تُبلغ من جديد بالمعرّف id نفسه (نصًا كان أو رقمًا، أو بالتسمية label نفسها إن لم يكن هناك معرّف) تحل محل ما قالته من قبل، لذلك يمكن لأداة لها مؤشر دوران واحد أن تحتفظ بالمعرّف id نفسه وتغيّر label فقط. ومن دون معرّفات، تتعاقب الخطوات: الخطوة الجديدة تُنهي التي قبلها. وعند خروج الأمر، تنتهي الخطوة التي لا تزال قيد التشغيل بالطريقة نفسها التي انتهى بها الأمر.
يحمل سطر log سطرًا واحدًا من مخرجات الأداة ملفوفًا في JSON، ويُقرأ كمخرجات نصية عادية. يذهب السطر note إلى مخرجات التشغيل، والذي يحمل "level": "warn" يبقى أيضًا على البيئة كتحذير. يصبح السطر الأخير من نوع error خطأً منظمًا، مع عرض command للنسخ، وتظهر آخر 12 سطرًا من المخرجات أسفل message الخاصة به. ومن دونه يعرض Control Center آخر 20 سطرًا من stderr. أي شيء ليس JSON هو مخرجات سجل عادية.