راهاندازی محیطها
محیط پشتهٔ در حال اجرای یک فضاست: سرویسهایی که یک شاخه نیاز دارد، جدا از همهٔ فضاهای دیگر، نمایان در نوار کناری و در دسترس عاملها. درخواستهای کشش هم محیط دارند، چون هر PR از قبل فضای خودش را دارد.
مدیر فضای کاری یک بار تعریف را مینویسد. سپس اعضا در بخش محیط نوار کناری فضا یا PR روی شروع میزنند. تعریفها در پایگاهدادهٔ فضای کاری هستند، بنابراین یک شاخهٔ قابلیت هرگز آنچه را Control Center اجرا میکند تغییر نمیدهد، هرچند ابزارها همچنان کد آن شاخه را اجرا میکنند.
ساختن تعریف
بخش با عنوان “ساختن تعریف”- تنظیمات → فضای کاری → محیطها را باز کنید. فقط مدیران فضای کاری میتوانند تعریفها را تغییر دهند، و فقط مالک سرور میتواند تعریفی را که روی میزبان سرور اجرا میشود ذخیره کند (ببینید چه کسی چه چیزی را ذخیره میکند).
- روی تعریف جدید و سپس تعریف خالی یا پیشنویس از مخزن کلیک کنید. پیشنویس مخزن را برای فایلهای compose، یک
Procfileو اسکریپتهایpackage.jsonمیگردد و نتیجه را شما بازبینی میکنید. - فرم را پر کنید یا از زبانهٔ JSON استفاده کنید. نمونههای این صفحه همان JSON هستند.
- روی اجرای آزمایش کلیک کنید. این کار یک محیط یکبارمصرف را آغاز میکند، تا آماده شدنش صبر میکند و آن را نابود میکند.
هنگام ذخیره، تعریف بهدقت بررسی میشود. هر فیلد ناشناخته، مقدار با نوع نادرست یا گزینهٔ غلطنوشتهشده رد میشود، همراه با مسیر آن و نزدیکترین نام معتبر، مانند repos.app.requird: Unknown field. Did you mean "required"?. یک $schema در سطح بالا مجاز است.
برای نگه داشتن تعریف در مخزن، از پیوند فایل مخزن استفاده کنید. Control Center فایل را فقط از شاخهٔ پیشفرض میخواند و فقط نسخهای را اجرا میکند که تأیید شده باشد: توسط مدیر فضای کاری، یا توسط مالک سرور وقتی تعریف روی میزبان اجرا میشود. نسخهٔ جدیدتر بهروزرسانی موجود است را نشان میدهد و تا تأیید نشود چیزی را تغییر نمیدهد.
چه کسی چه چیزی را ذخیره میکند
بخش با عنوان “چه کسی چه چیزی را ذخیره میکند”یک تعریف محیط میتواند فرمانهایی را روی میزبان سرور بهعنوان کاربر خود سرور اجرا کند. این تصمیم مالک سرور است، نه نقش فضای کاری:
- تعریفی روی میزبان اجرا میشود که جایگذاری میزبان، بررسیای که فرمانی را اجرا میکند، یا وظیفهٔ
provisionیاarchiveداشته باشد. این وظایف، هرچه جایگذاری باشد، در worktree فضا روی میزبان اجرا میشوند. - فقط مالک سرور میتواند تعریفی را که روی میزبان اجرا میشود ذخیره یا تأیید کند. این شامل تأیید نسخهٔ جدید یک فایل مخزن پیوندی هم میشود. مدیر فضای کاری که تلاش کند این پیام را میبیند: «فقط مالک سرور میتواند محیطی را که روی میزبان سرور اجرا میشود ذخیره یا تأیید کند. مدیر فضای کاری میتواند از محیطی استفاده کند که داخل Rig اجرا میشود.»
- مدیر فضای کاری میتواند تعریفی را که کاملاً داخل یک rig اجرا میشود ذخیره و تأیید کند:
"placement": "rig"، بدون فرمان بررسی و بدون وظیفهٔprovisionیاarchive. - اعضا در هر حال محیطها را شروع، متوقف و استفاده میکنند.
- تعریفی که روی میزبان اجرا میشود فقط بعد از آنکه مالک فعلیِ سرور آن را ذخیره یا تأیید کرده اجرا میشود. سرور این تأیید را خودش ثبت میکند و پیش از هر شروع، بررسی، وظیفه و همگامسازی سر PR آن را بررسی میکند. تعریفی که مالک فعلی تأیید نکرده، مثلاً تعریفی که مالک پیشین ذخیره کرده، زیر ردیفش در فهرست محیطها و در ویرایشگر منتظر میماند. مالک سرور پیام «روی این سرور اجرا میشود. برای اینکه شروع شود آن را تأیید کنید.» را همراه با تأیید میبیند که آن را بدون تغییر ذخیره میکند؛ بقیه پیام «روی این سرور اجرا میشود. پیش از شروع، مالک سرور باید آن را تأیید کند.» را میبینند.
- محیطی که برای این تأیید نگه داشته شده میگوید: «مالک سرور هنوز این محیط را تأیید نکرده است، پس نمیتواند روی این سرور اجرا شود.» مالک سرور بهجای آن این را میبیند: «هنوز این محیط را تأیید نکردهاید. روی این سرور اجرا میشود، پس وقتی تعریفش را تأیید کنید شروع میشود.» همراه با بازبینی و تأیید که تعریف را باز میکند.
- ترمینالهای فرایندهای محیط، و ترمینالی که شروع وقتی به شما نیاز دارد باز میکند، روی میزبان سرور اجرا میشوند. تایپ در آنها، تغییر اندازه یا بستنشان به دسترسی نوشتن روی هر مخزنی که فضا در اختیار میگذارد نیاز دارد، که با ورود خودتان به forge خوانده میشود: همان چیزی که برای شروع محیط لازم است. هر کس دیگری اصلاً به آن ترمینالها نمیرسد.
کوچکترین تعریف
بخش با عنوان “کوچکترین تعریف”یک مخزن 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، در نشست پایانهٔ تحت نظارت | سرورهای توسعه و workerها |
task |
Control Center، یک بار برای هر محرک | نصب، مهاجرت، آزمون |
app |
Control Center، وقتی کسی روی راهاندازی برنامه کلیک کند | برنامهٔ دسکتاپ |
مؤلفههای task یک فهرست when میگیرند:
| محرک | زمان اجرا |
|---|---|
provision |
هنگام ساخته شدن worktree (وظایف worktree را در ادامه ببینید) |
create |
یک بار برای هر محیط و دوباره پس از بازنشانی |
start |
در هر آغاز |
change |
پس از همگامسازی، وقتی مسیر تغییریافته با onChange مطابقت داشته باشد |
manual |
در صورت درخواست: اجرا، cc-env run <id> یا environment_run_task |
archive |
درست پیش از نابودی worktree |
وظیفهای که در شروع کاری برایش نیست، وضعیت بیکار را دارد و در فهرست گامهایی که هنگام شروع محیط نشان داده میشود نمیآید: وظیفهٔ 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 پیش از آغاز هر چیز، درگاههای میزبان را از بازهای مشترک برای کل میزبان تخصیص میدهد (پیشفرض ۴۲۰۰۰ تا ۴۹۹۹۹، در بلوکهای ۳۲تایی). درگاه در تمام عمر محیط ثابت میماند و درگاههای 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 روی مسیریاب سرور میگیرند که روی یک درگاه loopback گوش میدهد:
http://<endpoint>--<name>--<project>.localhost:<router port>http://web--fix-login--shop.localhost:7355<name>شاخه بهصورت slug است، یا در فضای PR مقدارpr-<n>.<project>همانnaming.projectاست، وگرنه نام تعریف.- نامهای
*.localhostبه loopback اشاره میکنند، پس به ورودی hosts یا DNS نیاز ندارند و نام میزبان کوکیها را میان محیطها جدا نگه میدارد. - درگاههای compose که به HTTP پاسخ میدهند شناسایی میشوند و
httpروی مؤلفه این حدس را جایگزین میکند. فرایند به"endpoint": { "role": "web", "primary": true }نیاز دارد که{url.web}را هم در دسترس میگذارد. - در مرورگر (VM)، از باز کردن در Browser (VM) استفاده کنید. آنجا
https://web--fix-login--shop.localhost/به همان مسیر میرسد. - کل برچسب در ۶۳ نویسه میماند، پس نامهای بلند با یک هش کوتاه میشوند.
- دو نقطهٔ پایانی دامنهٔ والد مشترک ندارند. برنامهای که یک کوکی برای هر دو میخواهد باید آنها را از یک نقطهٔ پایانی ارائه کند.
برای URLهایی که باید از پیش ثبت شوند، مانند تغییرمسیرهای OAuth، "naming": { "pool": { "names": "cc{n}", "size": 8 }, "project": "shop" } مجموعهای ثابت از نامها میدهد.
policy تعیین میکند محیطها چه زمانی اجرا شوند. autoCreate مقدار off، prSpaces یا allSpaces دارد، پیشفرض idleStopMinutes عدد ۲۴۰ است، followPrHead با جابهجایی head محیط PR را همگام میکند و با maxRunning (پیشفرض ۶) دکمهٔ شروع پیشنهاد میکند محیطی که از همه دیرتر استفاده شده متوقف شود.
نمونه: برنامهٔ compose
بخش با عنوان “نمونه: برنامهٔ compose”یک برنامهٔ وب و Postgres از یک فایل compose، با .env نادیدهگرفتهشده در git، مهاجرتها و یک وظیفهٔ آزمون. seedFiles فایلهای نامبرده را از چکاوت ثبتشدهٔ شما به هر worktree تازه کپی میکند.
{ "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را انتخاب میکند. هر فعل میتواند بهجای argv مقدار{ "shell": "…" }باشد.interactiveفعلهایی را نام میبرد، از میانcreate،startوreset، که میتوانند آنچه لازم دارند را در یک ترمینال بخواهند. وقتی چنین فعلی با کد ۳ خارج شود، برای کسی که شروع را زده، Control Center همان فعل را دوباره روی یک زبانهٔ ترمینال اجرا میکند و شروع پس از خروج با کد ۰ ادامه مییابد. آنجا شرطinteractiveدرست است وCC_ENV_INTERACTIVE=1تنظیم میشود، بنابراین{ "if": "!interactive", "args": ["--json"] }خروجی ماشینی را برای لولهٔ پردازش نگه میدارد. شروعی که عامل یا خودکار انجام دهد هرگز ترمینالی باز نمیکند: محیط نیاز به اقدام را نشان میدهد و منتظر میماند.- اگر
destroyشکست بخورد، باز هم محیط حذف میشود، وقتیstatusپس از آنmissingرا گزارش کند؛ به این ترتیب محیطی که ابزار دیگر ندارد همیشه قابل حذف است. listبه Control Center امکان میدهد محیطی را که ابزار آن را از دست داده تشخیص دهد. محیط فقط وقتی گمشده علامت میخورد که نامش درlistنباشد وstatusپس از آنmissingبگوید. خروجیای که نتوان آن را بهصورت فهرست خواند چیزی را تغییر نمیدهد.{service}درlogsوexecباید یک واژه باشد که با-شروع نشود، و یکی از سرویسهایی باشد که ابزار آخرین بار گزارش کرده، وقتی گزارشی داده است.statusMapJSON خود ابزار را با اشارهگرهای 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 در سطح پنجرههای سیستمعامل کار میکند و به هیچ hook یا 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 آن اعمال میشود، و تا وقتی هرکدام خاموش باشد راهاندازی برنامه رد میشود. برنامه تا وقتی هر فرایندی در گروه فرایندش اجرا شود در حال اجراست، پس اگر راهانداز برنامه را شروع کند و خارج شود، اشکالی ندارد. اگر همهٔ آنها ظرف حدود ۵ ثانیه پس از راهاندازی برنامه از بین بروند، برنامه با آخرین خطوط گزارشش خطادار نشان داده میشود. پس از آن، خروج تمیز بهصورت بسته و خرابی با آخرین خطوط گزارش نشان داده میشود و هیچکدام دوباره اجرایش نمیکنند. بازراهاندازی سرور برنامه را میبندد و هرگز دوباره اجرایش نمیکند، و توقف هنگام بیکاری به برنامهٔ در حال اجرا کاری ندارد.
مجوزها و محدودیتهای برنامهٔ دسکتاپ
بخش با عنوان “مجوزها و محدودیتهای برنامهٔ دسکتاپ”- در 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"پنجره را فعال میکند و نشانگر را در اختیار میگیرد.
وظایف worktree
بخش با عنوان “وظایف worktree”وظایف provision و archive اسکریپت راهاندازی و بایگانی هر مخزن را همراه با worktree آن اجرا میکنند. نماد روی ردیف مخزن در تنظیمات → فضای کاری → مخزنها تعریف آن مخزن را باز میکند.
این وظایف از worktree پیروی میکنند، نه از محیط، پس در فضاهایی هم که کسی روی شروع نمیزند اجرا میشوند:
provision |
archive |
|
|---|---|---|
| اجرا | هنگام ساخته شدن worktree نقش، در هر فضایی | درست پیش از نابودی آن worktree |
| هنگام شکست | آمادهسازی شکست میخورد و worktree نابود میشود | ثبت میشود و هرگز جلوی حذف را نمیگیرد |
| مهلت پیشفرض | ۵ دقیقه | ۲ دقیقه |
| میبیند | 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"]هنگام تغییر فایل قفل هم دوباره نصب میکند.- وظیفه برای worktree نقش
cwdخود اجرا میشود، پس تعریف چندمخزنی میتواند هر مخزن را جداگانه راهاندازی کند. - اجرای آزمایشی
CC_SCRIPT_TEST=1را تنظیم میکند. تلاش دوباره از worktree تمیز آغاز میشود، پس وظایفی بنویسید که اجرای دوباره را تاب بیاورند.
عاملها
بخش با عنوان “عاملها”عاملها هرگز سوکت 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، یک shim برای docker همچنین docker compose را با ps، logs، exec، port، restart و top مجاز میکند، و فقط علیه پروژهٔ compose خود این محیط. پیش از فعل هیچ پرچمی نمیآید و هر فعل فهرست کوتاهی از گزینهها دارد: logs نمیتواند خروجی را دنبال کند و exec فقط -T (یا --no-tty) را میپذیرد. گزینههایی که compose را به فایل یا پروژهٔ دیگری میفرستند (-f، -p، --project-directory، --env-file، --profile) در هر جایی که بیایند رد میشوند. هر چیز دیگری با کد ۵ و پیام «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 باید به درون worktreeهای اجرا برسد. فرمانی که با هیچ قاعدهای مطابقت نداشته باشد با کد ۵ پایان مییابد.
همین عملیات بهصورت ابزار هم هستند: 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 را حدس نزنند.
درخواستهای کشش از fork
بخش با عنوان “درخواستهای کشش از fork”کد یک PR از fork قابل اعتماد نیست و در جایگیری روی میزبان با کاربر سیستمعامل سرور اجرا میشود. policy.forkPrs تعیین میکند چه رخ دهد:
| مقدار | اثر | پیشفرض برای |
|---|---|---|
rig |
فایل compose بدون پرسش در VM اجرا میشود | تعریفهایی که فقط مؤلفههای compose و task دارند |
approval |
هر آغاز به مدیر نیاز دارد | همهٔ تعریفهای دیگر |
deny |
رد میشود | هیچکدام |
seedFilesهرگز برای fork کپی نمیشوند، چون معمولاً رازند. فایل compose که یکی از آنها را مقید کند فایل گمشده را با نام گزارش میدهد.- وظایف
provisionوarchiveنادیده گرفته میشوند، مگر آنکه سیاستrigباشد که در این صورت در VM اجرا میشوند. - در جایگیری روی میزبان،
privileged، فضای نام میزبان، مقیدسازی سوکت Docker،devicesو مقیدسازیهای بیرون از worktreeهای فضا روی fork رد میشوند. در فضاهای مورد اعتماد فقط هشدار میدهند.
جایگیری در rig
بخش با عنوان “جایگیری در rig”"placement": "rig" مؤلفههای compose و task را در یک microVM اختصاصی اجرا میکند. تعریفهایی با مؤلفههای process، cli یا app واجد شرایط نیستند. فایل compose بدون تغییر اجرا میشود، بدون سوکت Docker میزبان و بدون اعتبارنامهٔ گرداننده، و دسترسی شبکه به رجیستریهای موردنیاز ایمیجهایش محدود است. worktree بهصورت زنده سوار میشود.
- میهمانهای arm64. میهمانها روی Apple Silicon از نوع arm64 هستند، پس ایمیجهای فقط amd64 اجرا نمیشوند.
- رجیستریهای خصوصی رد میشوند. میهمانها اعتبارنامهٔ رجیستری ندارند، پس ایمیجی روی رجیستری بیرون از رجیستریهای عمومی شناختهشده پیش از بوت VM رد میشود. مخزن خصوصی روی رجیستری عمومی هنگام دریافت میهمان شکست میخورد.
- ۱۶ GiB فضا. همهٔ ایمیجها و ولومهای پشته یک دیسک ۱۶ GiB را شریکاند و قابل افزایش نیست.
- بوت نخست کند است. لایههای ایمیج برای هر VM جداست، پس بوت نخست همهچیز را دریافت میکند. rig متوقفشده دیسکش را نگه میدارد.
- ایمیج پایه باید خواندنی باشد. Dockerfile که ایمیج پایه را با یک متغیر نام میبرد قابل برنامهریزی نیست، چون دسترسی شبکه هنگام بوت ثابت میشود.
- طول عمر.
policy.rigTtlHoursبه VM پایان میدهد، بهطور پیشفرض پس از ۲۴ ساعت.
قرارداد وضعیت برای سازندگان ابزار
بخش با عنوان “قرارداد وضعیت برای سازندگان ابزار”مؤلفهٔ 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را با کد خروج ۰ گزارش کنید:statusناموفقfailedحساب میشود.- فقط
stateلازم است. فیلدهای ناشناخته نادیده گرفته میشوند و خروجی غیرقابل تجزیه بهصورت تنزلیافته نمایش داده میشود و متن خام جزئیات آن است. - URL باید loopback،
*.localhostیا زیرrouting.domainباشد، وگرنه کنار گذاشته میشود. needsRecreate: trueگزینهٔ ساخت دوباره را نشان میدهد که داده را دور میریزد. Control Center هرگز خودسرانه بر اساس آن عمل نمیکند.- فعل
listیک آرایهٔ JSON از نامها، یا اشیایی باnameچاپ میکند.
کدهای خروج برای همهٔ فعلها معتبرند:
| کد | معنا |
|---|---|
| 0 | موفق |
| 3 | پاسخی در ترمینال لازم است، مانند رمز عبور sudo. فعلی که در interactive آمده دوباره روی یک زبانهٔ ترمینال برای کسی که شروع را زده اجرا میشود. وگرنه اجرا در ترمینال پایانهٔ فضایی را باز میکند که فرمان command ابزار در آن تایپشده اما اجرا نشده، سپس تلاش مجدد دوباره تلاش میکند. Control Center هرگز sudo را اجرا نمیکند و به هیچ درخواستی پاسخ نمیدهد. |
| 4 | ورود به حساب لازم است. فرمان command ابزار نشان میدهد چگونه |
| 5 | چیزی که به آن وابسته است در دسترس نیست، مانند یک زماناجرای کانتینر که در حال اجرا نیست |
| دیگر | شکست |
کدهای ۳، ۴ و ۵ شکست نیستند. محیط نیاز به اقدام را نشان میدهد و منتظر میماند، و شروع بعدی از همان جایی ادامه میدهد که آن شروع متوقف شد. وظیفهای که با یکی از آنها خارج شود همین معنا را دارد.
پیشرفت بهصورت JSON خطبهخط به stderr میرود:
{"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 برای کپی پیشنهاد میشود، و ۱۲ خط آخر خروجی زیر message آن نشان داده میشود. بدون آن، Control Center آخرین ۲۰ خط stderr را نشان میدهد. هر چیزی که JSON نباشد خروجی گزارش عادی است.