Környezetek beállítása
A környezet egy tér futó stackje: az ág által igényelt szolgáltatások, minden más tértől elszigetelve, az oldalsávon láthatóan és az ügynökök számára elérhetően. A pull requestek is kapnak egyet, mert egy PR-nek már van saját tere.
A munkaterület egyik rendszergazdája egyszer megír egy definíciót. A tagok ezután a Indítás gombra kattintanak egy tér vagy PR oldalsávjának Környezet szakaszában. A definíciók a munkaterület adatbázisában vannak, így egy funkcióág soha nem változtatja meg, mit futtat a Control Center, bár az eszközök továbbra is az ág kódját futtatják.
Definíció létrehozása
Szekció neve “Definíció létrehozása”- Nyissa meg ezt: Beállítások → Munkaterület → Környezetek. Definíciókat csak a munkaterület rendszergazdái módosíthatnak, és csak a szerver tulajdonosa menthet olyan definíciót, amely a szerver gazdagépén fut (lásd: Ki menthet mit).
- Kattintson a Új definíció, majd a Üres definíció vagy a Vázlat a tárolóból elemre. A vázlat compose-fájlokat,
Procfilefájlt éspackage.jsonszkripteket keres a repóban, az eredményt pedig Ön ellenőrzi. - Töltse ki az űrlapot, vagy használja a JSON lapot. Az oldal példái ezt a JSON-t mutatják.
- Kattintson a Teszt futtatása gombra. Ez elindít egy eldobható környezetet, megvárja, amíg kész, majd megsemmisíti.
A mentés szigorúan ellenőrzi a definíciót. Az ismeretlen mező, a rossz típusú érték vagy az elírt választás elutasításra kerül, az elérési útjával és a legközelebbi érvényes névvel együtt, például repos.app.requird: Unknown field. Did you mean "required"?. A legfelső szintű $schema megengedett.
Ha a definíciót repóban szeretné tartani, használja a Tárolófájl összekapcsolása lehetőséget. A Control Center csak az alapértelmezett ágról olvassa a fájlt, és csak az a verzió fut, amelyet jóváhagytak: egy munkaterület-rendszergazda, vagy a szerver tulajdonosa, ha a definíció a gazdagépen fut. Egy újabb verzió a Frissítés érhető el jelzést mutatja, és jóváhagyásig semmit sem változtat.
Ki menthet mit
Szekció neve “Ki menthet mit”Egy környezeti definíció parancsokat futtathat a szerver gazdagépén, a szerver saját felhasználójaként. Ez a szerver tulajdonosának döntése, nem valamelyik munkaterületi szerepkörnek:
- Egy definíció a gazdagépen fut, ha gazdagép-elhelyezése van, ha van parancsot futtató ellenőrzése, vagy ha van
provisionvagyarchivefeladata. Ezek a feladatok az elhelyezéstől függetlenül a tér worktree-jében futnak a gazdagépen. - Csak a szerver tulajdonosa menthet vagy hagyhat jóvá olyan definíciót, amely a gazdagépen fut. Ez magában foglalja egy repóhoz kapcsolt fájl új verziójának jóváhagyását is. Ha egy munkaterület-rendszergazda megpróbálja, ezt látja: „Csak a szerver tulajdonosa menthet vagy hagyhat jóvá olyan környezetet, amely a szerver gépén fut. A munkaterület-adminisztrátor egy állomáson futót is használhat.”
- Egy munkaterület-rendszergazda menthet és hagyhat jóvá olyan definíciót, amely teljesen állomáson fut:
"placement": "rig", nincs ellenőrző parancs, és nincsprovisionvagyarchivefeladat. - A tagok mindkét esetben indítják, leállítják és használják a környezeteket.
- A gazdagépen futó definíció csak azután fut, hogy a jelenlegi szerver tulajdonosa elmentette vagy jóváhagyta. A szerver maga rögzíti ezt a jóváhagyást, és minden indítás, ellenőrzés, feladat és pull request fejének szinkronizálása előtt ellenőrzi. Az a definíció, amelyet a jelenlegi tulajdonos nem hagyott jóvá, például amelyet egy korábbi tulajdonos mentett, a környezetlistában és a szerkesztőben a sora alatt várakozik. A szerver tulajdonosa ezt látja: „A szerver gépén fut. Hagyja jóvá, hogy elindulhasson.” a Jóváhagyás gombbal, amely változtatás nélkül menti; mindenki más ezt látja: „A szerver gépén fut. A szerver tulajdonosának jóvá kell hagynia, mielőtt elindulhat.”
- A jóváhagyásra váró környezet ezt írja: „A szerver tulajdonosa még nem hagyta jóvá ezt a környezetet, ezért nem futhat ezen a szerveren.” A szerver tulajdonosa ezt látja helyette: „Ön még nem hagyta jóvá ezt a környezetet. A szerver gépén fut, ezért a definíció jóváhagyása után indul el.” az Átnézés és jóváhagyás gombbal, amely megnyitja a definíciót.
- Egy környezet folyamatterminálja, valamint az a terminál, amelyet egy indítás nyit meg, amikor Önre van szüksége, a szerver gazdagépén fut. Ezekbe gépelni, átméretezni vagy bezárni a térben megjelenített minden repóhoz írási jogosultság kell, amelyet a saját forge-bejelentkezésével olvas: ugyanaz, mint a környezet indításához. Más ezekhez a terminálokhoz egyáltalán nem fér hozzá.
A legkisebb definíció
Szekció neve “A legkisebb definíció”Egy egyszerű compose-repónak csak ennyi kell:
{ "contract": 1, "name": "Shop", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "components": [ { "kind": "compose", "id": "stack" } ]}Minden másnak van alapértéke: a compose-fájlt megtalálja, minden szolgáltatás fut, a portok kiosztásra kerülnek, a HTTP-végpontok felismerésre kerülnek, a környezet pedig az ágról kapja a nevét.
Összetevőtípusok
Szekció neve “Összetevőtípusok”A környezet összetevők rendezett listája. Mindegyik megvárja, amíg az előző kész, hacsak az after másokat nem nevez meg, a leállítás pedig fordított sorrendben történik. Az enabledWhen egy beállításhoz vagy szerepkörhöz köti az összetevőt, például opt.seed, !opt.seed vagy repo.web. Az az összetevő, amelynek szerepköre nem kötelező, és hiányzik a térből, ugyanígy kimarad, enabledWhen nélkül is: nem indul el, és nincs {port.*} vagy {url.*} értéke, így a másik összetevő, amely ezeket olvassa, meghiúsítja az indítást.
| Típus | Ki futtatja | Mire való |
|---|---|---|
compose |
A Control Center compose-illesztője | Bármely compose-fájl, környezetenként egy |
cli |
Az Ön eszköze. A Control Center leképezett igéket hív és JSON-t olvas | Olyan eszköz, amely maga kezeli az életciklusát, tartományait és adatait |
process |
A Control Center, felügyelt terminálmunkamenetben | Fejlesztői szerverek és workerek |
task |
A Control Center, triggerenként egyszer | Telepítések, migrációk, tesztek |
app |
A Control Center, amikor valaki a Megnyitás gombra kattint | Asztali alkalmazás |
A task összetevők when listát fogadnak:
| Trigger | Mikor fut |
|---|---|
provision |
A worktree létrehozásakor (lásd lentebb a worktree-feladatokat) |
create |
Környezetenként egyszer, és visszaállítás után újra |
start |
Minden indításkor |
change |
Szinkronizálás után, ha egy módosult útvonal illeszkedik az onChange mintára |
manual |
Kérésre: Futtatás, cc-env run <id> vagy environment_run_task |
archive |
Közvetlenül a worktree megsemmisítése előtt |
A környezet indításakor nincs dolga, a feladat Tétlen állapotot mutat, és nem szerepel a környezet indításakor megjelenő lépéslistában: ez a manual vagy change feladat, illetve a már lefutott create feladat.
A tömbként megadott parancs argv, így a beállítások értékei soha nem mennek át shellen. Egy karakterlánc, vagy a sorok tömbjét tartalmazó script a bash -lc alatt fut. Az olyan helyőrzők, mint a {name}, {branch}, {stateDir}, {repo.<role>}, {port.<key>}, {opt.<key>} és {url.<role>}, csak argv-ben helyettesítődnek be. A shell-parancsok ugyanezeket az értékeket CC_ENV_* változókként olvassák, például $CC_ENV_PORT_WEB. A részt vevő összetevőben egy ismeretlen helyőrző megállítja az indítást, mielőtt bármi futna.
Minden parancs és térterminál megkapja a CC_ENV_NAME, CC_ENV_STATE_DIR, CC_ENV_URL, CC_SPACE_ID, CC_ENV_REPO_<ROLE> változókat, PR-terekben pedig a CC_PR_NUMBER és CC_PR_IS_FORK változókat is. Compose-összetevővel a COMPOSE_PROJECT_NAME és COMPOSE_FILE is rendelkezésre áll, így egy feladatban a docker compose exec a megfelelő projektet éri el.
Szerepkörök és munkakönyvtár
Szekció neve “Szerepkörök és munkakönyvtár”A definíció szerepköröket köt a munkaterület repóihoz, így egy stack több repót is átfoghat:
"repos": { "api": { "repoId": "<api>", "anchor": true, "required": true }, "web": { "repoId": "<web>", "anchor": true }, "e2e": { "repoId": "<e2e>", "whenMissing": "useSource" }}anchor: egy tér akkor indíthatja a környezetet, ha legalább egy horgony szerepkört tartalmaz. Ha két definíció is illeszkedik, az indító választ.required: a stack nem fut e nélkül a repó nélkül.whenMissing: mi történik, ha a térből hiányzik a szerepkör. AzaddToSpacehozzáadja a repót az alapértelmezett ágon, és arequiredszerepkörök alapértéke. AuseSourceaz Ön regisztrált checkoutját adja át, amelyet csak olvashatóként kezeljen. Askipbeállítatlanul hagyja a változót, és egyébként ez az alapérték.- Az indításhoz
writejogosultság kell a tér egy horgonyrepójára, és olvasási hozzáférés minden más kötött repóhoz.
A parancs a repos-ban deklarált első szerepkörben fut, soha nem a tér egy másik szerepkörében, amely véletlenül megvan, így az egyrepós definíciónak ezt nem kell említenie. Bármely összetevő felülírhatja ezt ezzel: "cwd": { "role": "e2e", "path": "packages/ui" }. Mindkét mező elhagyható. Ha az első szerepkör hiányozhat egy térből, mert sem required, sem az egyetlen horgony nem, minden összetevőnek meg kell neveznie a szerepkörét.
Portok és URL-ek
Szekció neve “Portok és URL-ek”A Control Center még minden indítás előtt kiosztja a gazdaportokat egy az egész gazdára érvényes tartományból (alapértelmezés szerint 42000 és 49999 között, 32-es blokkokban). Egy port a környezet teljes élettartama alatt ugyanaz marad, a compose-portok pedig csak a 127.0.0.1 címhez kötődnek.
- A compose-portokat nem kell deklarálni. Olvassa őket így:
{port.postgres.5432}vagyCC_ENV_PORT_POSTGRES_5432. - A többi portot ott kell deklarálni, ahol használják,
"port": "web"vagy"ports": ["web", "hmr"]formában, olvasni pedig{port.web}alakban lehet. A porttal rendelkező folyamat megkapja aPORTés aHOST=127.0.0.1változót is.
A HTTP-végpontok URL-t kapnak a szerver útválasztóján, amely egyetlen loopback porton figyel:
http://<endpoint>--<name>--<project>.localhost:<router port>http://web--fix-login--shop.localhost:7355- A
<name>az ág slugként, vagy PR-térbenpr-<n>. A<project>anaming.project, ennek hiányában a definíció neve. - A
*.localhostnevek a loopbackre mutatnak, így nincs szükség hosts-bejegyzésre vagy DNS-re, a gazdanév pedig elkülöníti a sütiket a környezetek között. - A HTTP-re válaszoló compose-portokat felismeri, az összetevő
httpmezője pedig felülírja ezt a találgatást. Egy folyamatnak"endpoint": { "role": "web", "primary": true }kell, ami a{url.web}értéket is elérhetővé teszi. - A böngészőben (VM) használja a Megnyitás a Browser (VM) nézetben lehetőséget. A
https://web--fix-login--shop.localhost/ott ugyanazt az útvonalat éri el. - A teljes címke 63 karakteren belül marad, így a hosszú nevek hash segítségével rövidülnek.
- Két végpontnak nincs közös szülőtartománya. Az az alkalmazás, amelynek mindkettőn egy süti kell, egyetlen végpontról szolgálja ki őket.
Az előre regisztrálandó URL-ekhez, például OAuth-átirányításokhoz a "naming": { "pool": { "names": "cc{n}", "size": 8 }, "project": "shop" } rögzített névkészletet ad.
A policy dönti el, mikor futnak a környezetek. Az autoCreate értéke off, prSpaces vagy allSpaces, az idleStopMinutes alapértéke 240, a followPrHead szinkronizálja a PR-környezetet, ha elmozdul a headje, a maxRunning (alapérték 6) esetén pedig a Indítás felajánlja a legrégebben használt környezet leállítását.
Példa: compose-alkalmazás
Szekció neve “Példa: compose-alkalmazás”Egy webalkalmazás és Postgres egy compose-fájlból, git által figyelmen kívül hagyott .env fájllal, migrációkkal és tesztfeladattal. A seedFiles megnevezett fájlokat másol a regisztrált checkoutból minden új worktree-be.
{ "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" } ]}A healthchecks lehetővé teszi, hogy egy saját állapotellenőrzés nélküli szolgáltatás visszatartsa a következő összetevőt. Enélkül egy futó konténer késznek számít, és a migrációk megelőzhetik a még induló adatbázist.
Minden indítás és frissítés up parancsot futtat a --remove-orphans kapcsolóval, így a compose-fájlból eltávolított szolgáltatás leáll, és felszabadítja a portját. Az image-ek indításkor és frissítéskor épülnek, hacsak az összetevő nem állítja be a "build": false értéket.
Példa: saját CLI
Szekció neve “Példa: saját CLI”Egy kitalált acme eszköz, amely maga kezeli a konténereit, tartományait és TLS-ét. A Control Center a {name} értéket adja meg, minden mást a status kimenetéből tud meg. Soha nem vezeti le egy eszköz gazdaneveit, és soha nem szerkeszti az /etc/hosts fájlt.
{ "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"] } } ]}- A
create,statusésdestroykötelező. A Control Center a beolvasott állapot alapján választcreateésstartközött. Bármely ige lehet argv helyett{ "shell": "…" }. - Az
interactivenevezi meg azokat az igéket (create,startésresetközül), amelyek terminálban kérhetik a szükséges adatokat. Ha egy ilyen ige 3-as kóddal lép ki egy olyan személy számára, aki az Indítás gombra kattintott, a Control Center ugyanazt az igét újra lefuttatja egy terminálfülön, és az indítás folytatódik, amint 0-val lép ki. Ott azinteractivefeltétel igaz, és aCC_ENV_INTERACTIVE=1be van állítva, így a{ "if": "!interactive", "args": ["--json"] }a gépi kimenetet megtartja a nem interaktív futtatásnak. Ügynök által indított vagy automatikus indítás soha nem nyit terminált: a környezet Teendő van állapotban marad és vár. - Ha a
destroysikertelen, a környezetet attól még eltávolítja, ha astatusezutánmissingállapotot jelez, így az olyan környezet, amelyet az eszköz már nem ismer, mindig eltávolítható. - A
listlehetővé teszi, hogy a Control Center észrevegyen egy környezetet, amelyet az eszköz elvesztett. Csak akkor jelölődik eltűntként, ha a neve hiányzik alistkimenetéből, és astatusekkormissingértéket ad. Az a kimenet, amely nem olvasható listaként, nem változtat semmit. - A
logsésexecparancsban az{service}egyetlen szó legyen, amely nem kezdődik-karakterrel, és az eszköz utoljára jelentett szolgáltatásai közül egy, ha jelentett bármit. - A
statusMapJSON-mutatókkal olvassa az eszköz saját JSON-ját, ahol a*minden elemre illeszkedik. Az állapotszabályok rendezettek, és az első találat nyer. A feltételpathésequals, vagyanyilletvenoneéswhere. - A
keepsDataOnStop: falsekikapcsolja a tétlenségi leállítást, és adatvesztési figyelmeztetést tesz a Leállítás elé. Akkor állítsa be, ha a leállítás adatvesztéssel jár. - A
routing.mode: "tool"az eszköz gazdaneveit a böngészőhöz (VM) és az ügynökökhöz kapcsolja. A tartománynak.test,.localhostvagy.internalvégződésűnek kell lennie, a rajta kívül jelentett URL-t pedig eldobja.
Egy saját eszköz elhagyhatja a statusMap mezőt, és kiírhatja az oldal végén leírt állapotszerződést.
Példa: pnpm monorepo
Szekció neve “Példa: pnpm monorepo”Csak folyamatok és feladatok, konténerek nélkül. A webalkalmazás a {url.api} révén találja meg az API-t.
{ "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"] } ]}- Minden folyamat egy terminállap, amelyet megnyithat, olvashat, és amelybe gépelhet, ha minden repóban írási joga van a térben (lásd: Ki menthet mit). A lap bezárása nem állítja le.
- A
readylehethttp(teljes URL),tcp(host:port) vagylogMatch(reguláris kifejezés). Arestartleheton-failure(alapérték),alwaysvagynever. ArestartOnújraindítja a folyamatot, ha egy módosult útvonal illeszkedik. - Az
optionsűrlappá válik a Indítás gombnál, azagentDefaultpedig az ügynök által indított futásokra vonatkozik.
Példa: asztali alkalmazás
Szekció neve “Példa: asztali alkalmazás”Asztali alkalmazás build-lépéssel. Egy alkalmazás ugyanúgy működik, bármivel készült is, mert a Control Center az operációs rendszer ablakszintjén dolgozik, és nem kell hook vagy SDK az alkalmazásba.
{ "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" } ]}Az alkalmazás nem indul el a környezettel. Valaki a Megnyitás gombra kattint, és először a prepare fut le. A Újraépítés és újranyitás újra lefuttatja ezt a párost. Az enabledWhen az alkalmazásra és annak prepare feladatára vonatkozik, és a Megnyitás elutasításra kerül, amíg bármelyik ki van kapcsolva. Az alkalmazás futónak számít, amíg a folyamatcsoportjában bármelyik folyamat fut, így az is rendben van, ha az indító elindítja az alkalmazást, majd kilép. Ha a Megnyitás után nagyjából 5 másodpercen belül minden eltűnik, az alkalmazás hibásként jelenik meg az utolsó naplósorokkal. Ezt követően a tiszta kilépés bezártként, az összeomlás pedig az utolsó naplósorokat mutatja, és egyik sem indítja újra. A szerver újraindítása bezárja az alkalmazást, és soha nem indítja újra, a tétlenségi leállítás pedig békén hagyja a futó alkalmazást.
Asztali alkalmazások engedélyei és korlátai
Szekció neve “Asztali alkalmazások engedélyei és korlátai”- macOS rendszeren egyszer adja meg a Control Centernek a Képernyőfelvétel és a Kisegítő lehetőségek engedélyt a Rendszerbeállításokban. A szerver gazdagépének grafikus munkamenet kell: a headless szerver megtagadja az alkalmazás indítását.
- A binárist közvetlenül indítsa. Az
open -aátadja az alkalmazást a LaunchServicesnek, és az kikerül a Control Center által követett folyamatfából, ezért az alkalmazás az indítás után azonnal hibásként jelenik meg. - Az ablakok kijelzőn maradnak. A macOS nem rögzít olyan ablakot, amely minden kijelzőn kívül áll, így az ügynök által használt alkalmazás látható a szerver képernyőjén. Fókusz nem kell hozzá.
- Az
"isolate": "home"privát saját mappát ad az alkalmazásnak aHOME,XDG_*ésCFFIXED_USER_HOMErévén, így két tér példányai futhatnak egymás mellett. ANSUserDefaultsnincs elszigetelve, ezért a Cocoa-beállítások és a Fluttershared_preferencestárolója közös marad a példányok között. - Az
isolatecsak az indított folyamatra vonatkozik. Egy eszközlánc-indítónak, mint aflutter run, a valódi saját mappa kell, ezért azisolatebeállítást lefordított binárissal párosítsa. Ha az alkalmazásnak van saját beállítása, például--user-data-dir, inkább azt használja. - Az ügynökök az
app_useeszközzel vezérlik az ablakot, amely csak ennek a környezetnek a folyamatfáját éri el. Az ügynök az ablakot látja, nem az asztalt. Az ügynöki indítások a műveleti szabályzaton mennek át, és alapértelmezés szerint rákérdeznek, az ügynök bevitele pedig leáll, amíg ember vezérel. - Az
"input": "background"(alapérték) eseményeket küld a folyamatnak. A"foreground"aktiválja az ablakot, és átveszi a kurzort.
Worktree-feladatok
Szekció neve “Worktree-feladatok”A provision és archive feladatok futtatják a repó telepítését és lebontását a worktree-jével. A repó sorában lévő ikon a Beállítások → Munkaterület → Tárolók oldalon megnyitja a repó definícióját.
Ezek a feladatok a worktree-t követik, nem a környezetet, így olyan terekben is futnak, ahol senki sem kattint a Indítás gombra:
provision |
archive |
|
|---|---|---|
| Fut | A szerepkör worktree-jének létrehozásakor, bármely térben | Közvetlenül a worktree megsemmisítése előtt |
| Hiba esetén | A kiépítés meghiúsul, és a worktree megsemmisül | Rögzítésre kerül, soha nem blokkolja a törlést |
| Alapértelmezett időkorlát | 5 perc | 2 perc |
| Látja | CC_WORKSPACE_PATH, CC_ROOT_PATH, CC_SPACE_*, CC_REPO_NAME |
Ugyanazt |
Egy stack nélküli repónak csak egy definíció kell a feladataival. Mivel nincs mit indítani, nem kell horgony szerepkör:
{ "contract": 1, "name": "Web", "repos": { "app": { "repoId": "<id>" } }, "components": [ { "kind": "task", "id": "setup", "when": ["provision"], "script": ["pnpm install", "cp \"$CC_ROOT_PATH/.env\" .env"] } ]}- Még nincs környezet, így ezek a feladatok nem használhatják a
{name},{port.*},{url.*},{opt.*}vagyenabledWhenelemeket, és nem kapják meg a definícióenvmezőjét. - Egy repóhoz csak egy definíció tartalmazhat
provisionésarchivefeladatokat. A többi minden máshoz kötheti. - A
"when": ["provision", "change"]akkor is újratelepít, ha egy zárolási fájl változik. - A feladat a
cwdszerepkörének worktree-jére fut, így egy több repós definíció minden repót külön beállíthat. - A tesztfutás beállítja a
CC_SCRIPT_TEST=1változót. Az újrapróbálás tiszta worktree-ből indul, ezért olyan feladatokat írjon, amelyek elviselik az újrafuttatást.
Ügynökök
Szekció neve “Ügynökök”Az ügynökök soha nem kapják meg a Docker-socketet. Megfelelő definícióval rendelkező térben a futás megkapja a cc-env parancsot a saját PATH útvonalán. A tér a futásból adódik, így az ügynök csak a saját környezetén tud műveletet végezni, és minden parancs átmegy a műveleti szabályzaton.
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-összetevővel egy docker shim is engedélyezi a docker compose használatát a ps, logs, exec, port, restart és top alparancsokkal, és csak ennek a környezetnek a saját compose-projektjére. Az ige előtt nem állhat kapcsoló, és minden igéhez egy rövid kapcsolólista tartozik: a logs nem követhet, az exec pedig csak -T (vagy --no-tty) kapcsolót fogad. A kapcsolók, amelyek a compose-t másik fájlra vagy projektre irányítanák (-f, -p, --project-directory, --env-file, --profile), bárhol is szerepelnek, visszautasításra kerülnek. Minden más 5-ös kóddal és a „not available in Control Center agent runs” üzenettel lép ki.
Az a repó, amelynek képességei a saját eszközét hívják, ezt továbbra is megteheti. Egy cli összetevő agentPassthrough blokkja megadja, mely parancsokat futtathatják az ügynökök. Csak azok a parancsok haladnak át, amelyeket a jóváhagyott definíció deklarál, és mindegyik a gazdagépen fut, így rájuk a Parancsok futtatása a gazdagépen szabály vonatkozik, amely alapértelmezés szerint kérdez:
"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"] } ]}A maps azt a műveletet nevezi meg, amelynek szabályzata érvényes. A positionalName erre a tér környezetére kényszeríti az argumentumot, a nameFilter erre szűri a JSON-kimenetet, és minden pathFlags értéknek a futás worktree-jein belülre kell mutatnia. A szabályra nem illeszkedő parancs 5-ös kóddal lép ki.
Ugyanezek a műveletek eszközként is elérhetők: environment_status, environment_up, environment_down, environment_reset, environment_destroy, environment_restart, environment_exec, environment_logs, environment_run_task, environment_launch_app és environment_stop_app. A homokozóban futó ügynökök közvetlenül érik el a portjaikat, a környezetük gazdaneveit pedig a futás proxyján át, ezért kérje meg őket, hogy a végpontokat az environment_status kimenetéből olvassák, és ne találgassanak URL-t.
Forkból érkező pull requestek
Szekció neve “Forkból érkező pull requestek”Egy fork-PR kódja nem megbízható, és gazdaelhelyezés esetén a szerver operációsrendszer-felhasználójaként fut. A policy.forkPrs dönti el, mi történik:
| Érték | Hatás | Alapérték ehhez |
|---|---|---|
rig |
A compose-fájl kérdés nélkül VM-ben fut | Csak compose és task összetevőket tartalmazó definíciók |
approval |
Minden indításhoz rendszergazda kell | Minden más definíció |
deny |
Elutasítva | Egyik sem |
- A
seedFilesfájlok forkhoz soha nem másolódnak, mert általában titkok. Az ilyet csatoló compose-fájl név szerint jelenti a hiányzó fájlt. - A
provisionésarchivefeladatok kimaradnak, hacsak a szabályzat nemrig, ekkor a VM-ben futnak. - Gazdaelhelyezésnél egy forkon a
privileged, a gazda névterei, a Docker-socket csatolása, adevicesés a tér worktree-jein kívüli csatolások elutasításra kerülnek. Megbízható terekben csak figyelmeztetést adnak.
Rig-elhelyezés
Szekció neve “Rig-elhelyezés”A "placement": "rig" a compose és task összetevőket dedikált microVM-ben futtatja. A process, cli vagy app összetevőket tartalmazó definíciók nem alkalmasak. A compose-fájl változtatás nélkül fut, a gazda Docker-socketje és az üzemeltető hitelesítő adatai nélkül, a hálózati hozzáférés pedig a képei által igényelt regisztrációs adatbázisokra korlátozódik. A worktree élőben van csatolva.
- arm64 vendégek. Apple Siliconon a vendégek arm64-esek, így a csak amd64-es képek nem futnak.
- A privát regisztrációs adatbázisok tiltottak. A vendégeknek nincsenek regisztrációs hitelesítő adataik, így az ismert nyilvánosokon kívüli regisztrációs adatbázisból származó kép már a VM indítása előtt elutasításra kerül. A nyilvános regisztrációs adatbázisban lévő privát tároló akkor hiúsul meg, amikor a vendég letölti.
- 16 GiB tárhely. A stack összes képe és kötete egy 16 GiB-os lemezen osztozik, és ez nem növelhető.
- Az első indítás lassú. A képrétegek VM-enként külön vannak, így az első indítás mindent letölt. A leállított rig megtartja a lemezét.
- Az alapképeknek olvashatónak kell lenniük. Az a Dockerfile, amely változóval nevezi meg az alapképét, nem tervezhető, mert a hálózati hozzáférés indításkor rögzül.
- Élettartam. A
policy.rigTtlHoursleállítja a VM-et, alapértelmezés szerint 24 óra után.
Állapotszerződés eszközkészítőknek
Szekció neve “Állapotszerződés eszközkészítőknek”A statusMap nélküli cli összetevő a natív szerződést, a cc-env/1 formátumot várja. A status ige ezt az objektumot írja a stdout kimenetre:
{ "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": "…" }}- A
stateértékeready,starting,stopped,failedvagymissing. Amissingacreateigéhez vezet, astoppedés afailedpedig astartigéhez. Amissingállapotot 0-s kilépési kóddal jelentse: a sikertelenstatusfailedállapotnak számít. - Csak a
statekötelező. Az ismeretlen mezőket figyelmen kívül hagyja, az értelmezhetetlen kimenet pedig leromlottként jelenik meg, a nyers szöveggel részletként. - Az URL-nek loopbacknek,
*.localhostnévnek vagy arouting.domainalattinak kell lennie, különben eldobásra kerül. - A
needsRecreate: truemegjeleníti a Újralétrehozás műveletet, amely eldobja az adatokat. A Control Center erre soha nem lép magától. - A
listige neveket vagynamemezős objektumokat tartalmazó JSON-tömböt ír ki.
A kilépési kódok minden igére érvényesek:
| Kód | Jelentés |
|---|---|
| 0 | OK |
| 3 | Választ kell adni egy terminálban, például egy sudo jelszóra. Az interactive listában szereplő igét a rendszer újra lefuttatja egy terminálfülön annak a személynek, aki az Indítás gombra kattintott. Egyébként a Futtatás terminálban térterminált nyit, amelybe az eszköz command parancsa be van gépelve, de nincs lefuttatva, majd az Újrapróbálás újra próbálja. A Control Center soha nem futtat sudo parancsot, és soha nem válaszol kérdésre |
| 4 | Bejelentkezés szükséges. Az eszköz command parancsa megmondja, hogyan |
| 5 | Olyan dolog nem érhető el, amitől függ, például egy nem futó konténer-futtatókörnyezet |
| Egyéb | Hiba |
A 3-as, 4-es és 5-ös kódok nem hibák. A környezet Teendő van állapotban marad és vár, a következő indítás pedig ott folytatódik, ahol az előző megállt. Az a feladat, amely ezek valamelyikével lép ki, ugyanezt jelenti.
A folyamat állapota soronként tagolt JSON-ként megy a stderr kimenetre:
{"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"}Miközben a környezet indul, a panel felsorolja azokat a részeket, amelyeken az indítás keresztülmegy, mindegyiket forgó jelzéssel, pipával vagy kereszttel. A step sor azt mutatja, mit csinál éppen az eszköz, a label-je pedig az eszköz saját sora alatt jelenik meg; a lépések soha nem adnak hozzá sorokat. A lépés state értéke pending, running, done vagy failed, a state nélküli lépés pedig fut. Az a lépés, amely ugyanazzal az id-val (szöveggel vagy számmal, vagy azonosító nélkül ugyanazzal a label-lel) jelentkezik újra, felülírja az előző üzenetét, így egy egyetlen jelzővel dolgozó eszköz megtarthatja ugyanazt az id-t, és változtathatja a label-t. Azonosítók nélkül a lépések egymás után következnek: az új lezárja az előzőt. Amikor a parancs kilép, a még futó lépés úgy ér véget, ahogy a parancs.
A log sor egy kimeneti sort tartalmaz, amelyet az eszköz JSON-ba csomagolt, és sima kimenetként olvasható. A note sor a futtatás kimenetébe kerül, a "level": "warn" értékű sor pedig figyelmeztetésként a környezeten is megmarad. Egy utolsó error típusú sor strukturált hibává válik, és a command másolásra kínálkozik, valamint a kimenet utolsó 12 sora a message alatt jelenik meg. Enélkül a Control Center az utolsó 20 stderr sort mutatja. Minden, ami nem JSON, egyszerű naplókimenet.