Sediakan persekitaran
Persekitaran ialah stack berjalan bagi satu ruang: perkhidmatan yang diperlukan oleh sesuatu cawangan, diasingkan daripada semua ruang lain, kelihatan di bar sisi dan boleh dicapai oleh ejen. Pull request juga mendapat satu, kerana PR sudah mempunyai ruangnya sendiri.
Pentadbir ruang kerja menulis definisi sekali sahaja. Ahli kemudian menekan Mula dalam bahagian Persekitaran pada bar sisi ruang atau PR. Definisi disimpan dalam pangkalan data ruang kerja, jadi cawangan ciri tidak pernah mengubah apa yang dijalankan Control Center, walaupun alat masih menjalankan kod cawangan itu.
Cipta definisi
Bahagian bertajuk “Cipta definisi”- Buka Tetapan → Ruang kerja → Persekitaran. Hanya pentadbir ruang kerja boleh mengubah definisi, dan hanya pemilik pelayan boleh menyimpan yang berjalan pada hos pelayan (lihat Siapa boleh menyimpan apa).
- Klik Definisi baharu, kemudian Definisi kosong atau Draf daripada repo. Draf mengimbas repositori untuk fail compose,
Procfiledan skrippackage.json, dan anda menyemak hasilnya. - Isi borang, atau gunakan tab JSON. Contoh pada halaman ini ialah JSON tersebut.
- Klik Jalankan ujian. Ia memulakan persekitaran pakai buang, menunggu sehingga sedia dan memusnahkannya.
Simpan memeriksa definisi dengan ketat. Medan yang tidak diketahui, nilai jenis yang salah atau pilihan yang tersalah eja ditolak, dengan laluannya dan nama sah terdekat, contohnya repos.app.requird: Unknown field. Did you mean "required"?. $schema peringkat atas dibenarkan.
Untuk menyimpan definisi dalam repositori, gunakan Paut fail repo. Control Center membaca fail hanya daripada cawangan lalai dan menjalankan hanya versi yang telah diluluskan: oleh pentadbir ruang kerja, atau oleh pemilik pelayan apabila definisi berjalan pada hos. Versi lebih baharu memaparkan Kemas kini tersedia dan tidak mengubah apa-apa sehingga diluluskan.
Siapa boleh menyimpan apa
Bahagian bertajuk “Siapa boleh menyimpan apa”Definisi persekitaran boleh menjalankan arahan pada hos pelayan sebagai pengguna pelayan itu sendiri. Itu keputusan pemilik pelayan, bukan peranan ruang kerja:
- Definisi berjalan pada hos apabila ia mempunyai penempatan hos, semakan yang menjalankan arahan, atau tugasan
provisionatauarchive. Tugasan itu berjalan dalam worktree ruang pada hos tanpa mengira penempatan. - Hanya pemilik pelayan boleh menyimpan atau meluluskan definisi yang berjalan pada hos. Itu termasuk meluluskan versi baharu bagi fail repo yang dipautkan. Admin ruang kerja yang cuba melihat “Hanya pemilik pelayan boleh menyimpan atau meluluskan persekitaran yang berjalan pada hos pelayan. Admin ruang kerja boleh menggunakan yang berjalan dalam rig.”
- Admin ruang kerja boleh menyimpan dan meluluskan definisi yang berjalan sepenuhnya dalam rig:
"placement": "rig", tanpa arahan semakan dan tanpa tugasanprovisionatauarchive. - Ahli memulakan, menghentikan dan menggunakan persekitaran dengan kedua-dua cara.
- Definisi yang berjalan pada hos hanya berjalan selepas pemilik pelayan semasa menyimpan atau meluluskannya. Pelayan merekodkan kelulusan itu sendiri dan menyemaknya sebelum setiap mula, semakan, tugasan dan penyegerakan kepala pull request. Definisi yang tidak diluluskan oleh pemilik semasa, seperti yang disimpan oleh pemilik sebelumnya, menunggu di bawah barisnya dalam senarai persekitaran dan dalam editor. Pemilik pelayan melihat “Berjalan pada pelayan ini. Luluskannya untuk membenarkannya bermula.” dengan Luluskan, yang menyimpannya tanpa perubahan; orang lain melihat “Berjalan pada pelayan ini. Pemilik pelayan perlu meluluskannya sebelum ia boleh bermula.”
- Persekitaran yang ditahan untuk kelulusan itu berkata “Pemilik pelayan belum meluluskan persekitaran ini, jadi ia tidak boleh berjalan pada pelayan ini.” Pemilik pelayan pula melihat “Anda belum meluluskan persekitaran ini. Ia berjalan pada pelayan ini, jadi ia akan bermula sebaik sahaja anda meluluskan definisinya.” dengan Semak dan luluskan, yang membuka definisi itu.
- Terminal proses persekitaran dan terminal yang dibuka oleh permulaan apabila ia memerlukan anda berjalan pada hos pelayan. Menaip ke dalamnya, mengubah saiznya atau menutupnya memerlukan akses tulis kepada setiap repositori yang didedahkan oleh ruang, boleh dibaca melalui log masuk forge anda sendiri: sama seperti memulakan persekitaran. Orang lain tidak dapat mencapai terminal itu langsung.
Definisi terkecil
Bahagian bertajuk “Definisi terkecil”Repositori compose yang ringkas hanya memerlukan ini:
{ "contract": 1, "name": "Shop", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "components": [ { "kind": "compose", "id": "stack" } ]}Semua yang lain mempunyai nilai lalai: fail compose ditemui, setiap perkhidmatan berjalan, port diberikan, titik akhir HTTP dikesan dan persekitaran dinamakan mengikut cawangan.
Jenis komponen
Bahagian bertajuk “Jenis komponen”Persekitaran ialah senarai komponen tertib. Setiap satu menunggu komponen sebelumnya sedia, melainkan after menamakan yang lain, dan penghentian berjalan secara terbalik. enabledWhen menjadikan komponen bergantung pada pilihan atau peranan, contohnya opt.seed, !opt.seed atau repo.web. Komponen yang peranannya pilihan dan tiada dalam ruang ditinggalkan dengan cara yang sama, tanpa enabledWhen diperlukan: ia tidak bermula dan tidak mempunyai {port.*} atau {url.*}, jadi komponen lain yang membacanya gagal semasa permulaan.
| Jenis | Siapa menjalankannya | Kegunaan |
|---|---|---|
compose |
Pemacu compose Control Center | Mana-mana fail compose, satu bagi setiap persekitaran |
cli |
Alat anda. Control Center memanggil kata kerja yang dipetakan dan membaca JSON | Alat yang memiliki kitaran hayat, domain dan datanya sendiri |
process |
Control Center, dalam sesi terminal yang diselia | Pelayan pembangunan dan worker |
task |
Control Center, sekali bagi setiap pencetus | Pemasangan, migrasi, ujian |
app |
Control Center, apabila seseorang mengklik Lancarkan | Apl desktop |
Komponen task menerima senarai when:
| Pencetus | Berjalan |
|---|---|
provision |
Apabila worktree dicipta (lihat tugasan worktree di bawah) |
create |
Sekali bagi setiap persekitaran, dan sekali lagi selepas tetapan semula |
start |
Pada setiap permulaan |
change |
Selepas penyegerakan, apabila laluan yang berubah sepadan dengan onChange |
manual |
Atas permintaan: Jalankan, cc-env run <id> atau environment_run_task |
archive |
Sejurus sebelum worktree dimusnahkan |
Tugas yang tiada apa-apa untuk dilakukan semasa permulaan dipaparkan sebagai Terlengah dan tidak disenaraikan dalam senarai langkah yang dipaparkan semasa persekitaran bermula: tugas manual atau change, atau tugas create yang sudah dijalankan.
Arahan yang diberikan sebagai tatasusunan ialah argv, jadi nilai pilihan tidak pernah melalui shell. Rentetan, atau script dengan tatasusunan baris, berjalan di bawah bash -lc. Pemegang tempat seperti {name}, {branch}, {stateDir}, {repo.<role>}, {port.<key>}, {opt.<key>} dan {url.<role>} hanya dikembangkan dalam argv. Arahan shell membaca nilai yang sama sebagai pemboleh ubah CC_ENV_*, contohnya $CC_ENV_PORT_WEB. Pemegang tempat yang tidak diketahui dalam komponen yang mengambil bahagian menghentikan permulaan sebelum apa-apa dijalankan.
Setiap arahan dan terminal ruang juga mendapat CC_ENV_NAME, CC_ENV_STATE_DIR, CC_ENV_URL, CC_SPACE_ID, CC_ENV_REPO_<ROLE> dan, dalam ruang PR, CC_PR_NUMBER serta CC_PR_IS_FORK. Dengan komponen compose, ia juga mendapat COMPOSE_PROJECT_NAME dan COMPOSE_FILE, supaya docker compose exec dalam tugasan mencapai projek yang betul.
Peranan dan direktori kerja
Bahagian bertajuk “Peranan dan direktori kerja”Definisi mengikat peranan kepada repositori ruang kerja, supaya satu stack boleh merangkumi beberapa repositori:
"repos": { "api": { "repoId": "<api>", "anchor": true, "required": true }, "web": { "repoId": "<web>", "anchor": true }, "e2e": { "repoId": "<e2e>", "whenMissing": "useSource" }}anchor: ruang boleh memulakan persekitaran apabila ia mempunyai sekurang-kurangnya satu peranan sauh. Jika dua definisi sepadan, orang yang memulakan memilih.required: stack tidak boleh berjalan tanpa repositori ini.whenMissing: apa yang berlaku apabila ruang tiada peranan itu.addToSpacemenambah repositori pada cawangan lalainya dan merupakan lalai untuk perananrequired.useSourcemenghantar checkout berdaftar anda, yang patut dilayan sebagai baca sahaja.skipmembiarkan pemboleh ubah tidak ditetapkan dan merupakan lalai selainnya.- Memulakan memerlukan kebenaran
writepada repositori sauh dalam ruang dan akses baca kepada setiap repositori terikat yang lain.
Arahan berjalan dalam peranan pertama yang diisytiharkan dalam repos, bukan dalam peranan lain yang kebetulan dimiliki ruang, jadi definisi satu repositori tidak pernah menyebutnya. Mana-mana komponen boleh mengatasinya dengan "cwd": { "role": "e2e", "path": "packages/ui" }. Kedua-dua medan adalah pilihan. Jika peranan pertama mungkin tiada dalam ruang, kerana ia bukan required mahupun satu-satunya sauh, setiap komponen mesti menamakan peranannya.
Port dan URL
Bahagian bertajuk “Port dan URL”Control Center memberikan port hos sebelum apa-apa bermula, daripada julat untuk seluruh hos (42000 hingga 49999 secara lalai, dalam blok 32). Port kekal sama sepanjang hayat persekitaran, dan port compose hanya mengikat kepada 127.0.0.1.
- Port compose tidak perlu diisytiharkan. Bacanya sebagai
{port.postgres.5432}atauCC_ENV_PORT_POSTGRES_5432. - Port lain diisytiharkan di tempat ia digunakan, dengan
"port": "web"atau"ports": ["web", "hmr"], dan dibaca sebagai{port.web}. Proses dengan port juga mendapatPORTdanHOST=127.0.0.1.
Titik akhir HTTP mendapat URL pada penghala pelayan, yang mendengar pada satu port loopback:
http://<endpoint>--<name>--<project>.localhost:<router port>http://web--fix-login--shop.localhost:7355<name>ialah cawangan sebagai slug, ataupr-<n>dalam ruang PR.<project>ialahnaming.project, atau nama definisi jika tiada.- Nama
*.localhostmenghala ke loopback, jadi ia tidak memerlukan entri hosts atau DNS, dan nama hos memisahkan kuki antara persekitaran. - Port compose yang menjawab HTTP dikesan, dan
httppada komponen mengatasi tekaan itu. Proses memerlukan"endpoint": { "role": "web", "primary": true }, yang juga menyediakan{url.web}. - Dalam pelayar (VM), gunakan Buka dalam Browser (VM).
https://web--fix-login--shop.localhost/mencapai laluan yang sama di sana. - Keseluruhan label kekal dalam 63 aksara, jadi nama panjang dipendekkan dengan cincangan.
- Dua titik akhir tidak berkongsi domain induk. Apl yang memerlukan satu kuki merentas kedua-duanya mesti menyajikannya daripada satu titik akhir.
Untuk URL yang perlu didaftarkan lebih awal, seperti pengubah hala OAuth, "naming": { "pool": { "names": "cc{n}", "size": 8 }, "project": "shop" } memberikan set nama yang tetap.
policy menentukan bila persekitaran berjalan. autoCreate ialah off, prSpaces atau allSpaces, idleStopMinutes lalainya 240, followPrHead menyegerakkan persekitaran PR apabila head bergerak, dan dengan maxRunning (lalai 6) Mula menawarkan untuk menghentikan persekitaran yang paling lama tidak digunakan.
Contoh: apl compose
Bahagian bertajuk “Contoh: apl compose”Apl web dan Postgres daripada satu fail compose, dengan .env yang diabaikan git, migrasi dan tugasan ujian. seedFiles menyalin fail bernama daripada checkout berdaftar anda ke setiap worktree baharu.
{ "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 membolehkan perkhidmatan tanpa semakan kesihatan sendiri menahan komponen seterusnya. Tanpanya, bekas yang berjalan dikira sedia, dan migrasi boleh mendahului pangkalan data yang masih bermula.
Setiap mula dan muat semula menjalankan up dengan --remove-orphans, jadi perkhidmatan yang dibuang daripada fail compose berhenti dan membebaskan portnya. Imej dibina semasa mula dan muat semula melainkan komponen menetapkan "build": false.
Contoh: CLI tersuai
Bahagian bertajuk “Contoh: CLI tersuai”Alat rekaan acme yang memiliki bekas, domain dan TLS-nya sendiri. Control Center memberikan {name} dan mengetahui yang selebihnya daripada status. Ia tidak pernah menerbitkan nama hos alat dan tidak pernah menyunting /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,statusdandestroydiperlukan. Control Center memilihcreateataustartberdasarkan status yang dibacanya. Mana-mana kata kerja boleh menjadi{ "shell": "…" }dan bukannya argv.interactivemenamakan kata kerja, daripadacreate,startdanreset, yang boleh meminta apa yang diperlukan dalam terminal. Apabila kata kerja sedemikian keluar dengan kod 3 untuk orang yang menekan Mula, Control Center menjalankan kata kerja yang sama sekali lagi dalam tab terminal, dan permulaan diteruskan apabila ia keluar dengan kod 0. Di situ syaratinteractiveadalah benar danCC_ENV_INTERACTIVE=1ditetapkan, jadi{ "if": "!interactive", "args": ["--json"] }mengekalkan output mesin untuk mod bukan interaktif. Permulaan oleh ejen, atau permulaan automatik, tidak pernah membuka terminal: persekitaran memaparkan Tindakan diperlukan dan menunggu.destroyyang gagal masih mengeluarkan persekitaran apabilastatuskemudian melaporkanmissing, jadi persekitaran yang tidak lagi dimiliki alat sentiasa boleh dikeluarkan.listmembolehkan Control Center mengesan persekitaran yang telah hilang daripada alat itu. Ia ditandakan hilang hanya apabila namanya tiada dalamlistdanstatuskemudian memaparkanmissing. Output yang tidak boleh dibaca sebagai senarai tidak mengubah apa-apa.{service}dalamlogsdanexecmestilah satu perkataan yang tidak bermula dengan-, dan salah satu perkhidmatan yang dilaporkan alat itu kali terakhir, jika ia ada melaporkan apa-apa.statusMapmembaca JSON alat dengan penuding JSON, dengan*sepadan dengan setiap item. Peraturan keadaan adalah tertib dan padanan pertama menang. Syarat ialahpathdenganequals, atauanyataunonedenganwhere.keepsDataOnStop: falsemematikan penghentian semasa melahu dan menambah amaran kehilangan data pada Henti. Tetapkannya apabila penghentian menghilangkan data.routing.mode: "tool"menyambungkan nama hos alat kepada pelayar (VM) dan ejen. Domain mesti berakhir dengan.test,.localhostatau.internal, dan URL yang dilaporkan di luarnya dibuang.
Alat milik anda boleh melangkau statusMap dan mencetak kontrak status yang diterangkan di hujung halaman ini.
Contoh: monorepo pnpm
Bahagian bertajuk “Contoh: monorepo pnpm”Hanya proses dan tugasan, tanpa bekas. Apl web menemui API melalui {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"] } ]}- Setiap proses ialah tab terminal yang boleh anda buka, baca dan taip, jika anda mempunyai akses tulis kepada setiap repositori dalam ruang (lihat Siapa boleh menyimpan apa). Menutup tab tidak menghentikannya.
readymenerimahttp(URL penuh),tcp(host:port) ataulogMatch(ungkapan biasa).restartialahon-failure(lalai),alwaysataunever.restartOnmemulakan semula proses apabila laluan yang berubah sepadan.optionsmenjadi borang pada Mula, danagentDefaultterpakai pada larian yang dimulakan ejen.
Contoh: apl desktop
Bahagian bertajuk “Contoh: apl desktop”Apl desktop dengan langkah binaan. Apl berfungsi sama walau apa pun teknologinya, kerana Control Center bekerja pada tahap tetingkap OS dan tidak memerlukan hook atau SDK dalam apl.
{ "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" } ]}Apl tidak bermula bersama persekitaran. Seseorang mengklik Lancarkan, dan prepare berjalan dahulu. Bina semula & lancarkan semula menjalankan pasangan itu semula. enabledWhen terpakai kepada apl dan tugas prepare-nya, dan Lancarkan ditolak selagi mana-mana satu daripadanya dimatikan. Apl dikira berjalan selagi mana-mana proses dalam kumpulan prosesnya berjalan, jadi pelancar yang memulakan apl dan keluar adalah baik-baik sahaja. Jika semuanya hilang dalam masa lebih kurang 5 saat selepas Lancarkan, apl dipaparkan sebagai gagal dengan baris log terakhirnya. Selepas itu, keluar bersih dipaparkan sebagai ditutup dan ranap menunjukkan baris log terakhir, dan kedua-duanya tidak memulakannya semula. Mula semula pelayan menutup apl dan tidak pernah melancarkannya semula, dan penghentian semasa melahu membiarkan apl yang berjalan.
Kebenaran dan had apl desktop
Bahagian bertajuk “Kebenaran dan had apl desktop”- Pada macOS, berikan Control Center Rakaman Skrin dan Kebolehcapaian sekali dalam Tetapan Sistem. Hos pelayan memerlukan sesi GUI: pelayan headless enggan melancarkan apl.
- Lancarkan binari secara terus.
open -amenyerahkan apl kepada LaunchServices dan ia meninggalkan pepohon proses yang dijejak Control Center, jadi apl dipaparkan sebagai gagal sejurus selepas dilancarkan. - Tetingkap kekal pada paparan. macOS tidak menangkap tetingkap yang diletakkan di luar semua paparan, jadi apl yang digunakan ejen kelihatan pada skrin pelayan. Ia tidak memerlukan fokus.
"isolate": "home"memberi apl direktori rumah peribadi melaluiHOME,XDG_*danCFFIXED_USER_HOME, supaya salinan daripada dua ruang boleh berjalan seiring.NSUserDefaultstidak diasingkan, jadi keutamaan Cocoa danshared_preferencesFlutter kekal dikongsi antara salinan.isolatehanya terpakai pada proses yang dilancarkan. Pelancar rantai alat sepertiflutter runmemerlukan direktori rumah sebenar, jadi gandingkanisolatedengan binari terbina. Jika apl mempunyai tetapan sendiri, seperti--user-data-dir, utamakannya.- Ejen memandu tetingkap dengan
app_use, yang hanya boleh mencapai pepohon proses persekitaran ini. Ejen melihat tetingkap, bukan desktop. Pelancaran ejen melalui dasar tindakan dan secara lalai bertanya, dan input ejen berhenti ketika seseorang memegang kawalan. "input": "background"(lalai) menghantar peristiwa kepada proses."foreground"mengaktifkan tetingkap dan mengambil alih kursor.
Tugasan worktree
Bahagian bertajuk “Tugasan worktree”Tugasan provision dan archive menjalankan persediaan dan penamatan repositori bersama worktreenya. Ikon pada baris repositori dalam Tetapan → Ruang kerja → Repositori membuka definisi repositori itu.
Tugasan ini mengikut worktree, bukan persekitaran, jadi ia berjalan dalam ruang yang tiada sesiapa mengklik Mula:
provision |
archive |
|
|---|---|---|
| Berjalan | Apabila worktree peranan dicipta, dalam mana-mana ruang | Sejurus sebelum worktree itu dimusnahkan |
| Jika gagal | Peruntukan gagal dan worktree dimusnahkan | Direkodkan, tidak pernah menyekat pemadaman |
| Tamat masa lalai | 5 minit | 2 minit |
| Melihat | CC_WORKSPACE_PATH, CC_ROOT_PATH, CC_SPACE_*, CC_REPO_NAME |
Sama |
Repositori tanpa stack hanya memerlukan definisi yang memegang tugasannya. Oleh sebab tiada apa untuk dimulakan, peranan sauh tidak diperlukan:
{ "contract": 1, "name": "Web", "repos": { "app": { "repoId": "<id>" } }, "components": [ { "kind": "task", "id": "setup", "when": ["provision"], "script": ["pnpm install", "cp \"$CC_ROOT_PATH/.env\" .env"] } ]}- Persekitaran belum wujud, jadi tugasan ini tidak boleh menggunakan
{name},{port.*},{url.*},{opt.*}atauenabledWhen, dan tidak mendapatenvdefinisi. - Hanya satu definisi boleh memegang tugasan
provisiondanarchiveuntuk sesuatu repositori. Yang lain masih boleh mengikatnya untuk perkara lain. "when": ["provision", "change"]juga memasang semula apabila fail kunci berubah.- Tugasan berjalan untuk worktree peranan
cwd-nya, jadi definisi berbilang repositori boleh menyediakan setiap repositori secara berasingan. - Larian ujian menetapkan
CC_SCRIPT_TEST=1. Percubaan semula bermula daripada worktree bersih, jadi tulis tugasan yang tahan dijalankan semula.
Ejen tidak pernah mendapat soket Docker. Dalam ruang dengan definisi yang layak, larian mendapat cc-env pada PATH-nya. Ruang datang daripada larian, jadi ejen hanya boleh bertindak pada persekitarannya sendiri, dan setiap arahan melalui dasar tindakan.
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>Dengan komponen compose, shim docker juga membenarkan docker compose dengan ps, logs, exec, port, restart dan top, dan hanya terhadap projek compose persekitaran ini sendiri. Tiada bendera boleh datang sebelum kata kerja, dan setiap kata kerja menerima senarai pendek pilihan: logs tidak boleh mengikuti output, dan exec hanya menerima -T (atau --no-tty). Pilihan yang menunjuk compose kepada fail atau projek lain (-f, -p, --project-directory, --env-file, --profile) ditolak di mana sahaja ia muncul. Yang lain keluar dengan kod 5 dan “not available in Control Center agent runs”.
Repositori yang kemahirannya memanggil alatnya sendiri boleh terus berbuat demikian. Blok agentPassthrough pada komponen cli mengisytiharkan arahan yang boleh dijalankan ejen. Hanya arahan yang diisytiharkan oleh definisi yang diluluskan boleh melalui, dan setiap satunya berjalan pada hos, jadi ia membawa peraturan Jalankan arahan pada hos, yang bertanya dahulu secara lalai:
"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 menamakan operasi yang dasarnya terpakai. positionalName memaksa argumen itu kepada persekitaran ruang ini, nameFilter menapis output JSON kepadanya, dan setiap nilai pathFlags mesti menghala ke dalam worktree larian. Arahan yang tidak sepadan dengan mana-mana peraturan keluar dengan kod 5.
Operasi yang sama wujud sebagai alat: environment_status, environment_up, environment_down, environment_reset, environment_destroy, environment_restart, environment_exec, environment_logs, environment_run_task, environment_launch_app dan environment_stop_app. Ejen dalam kotak pasir mencapai port mereka secara terus dan nama hos persekitaran mereka melalui proksi larian, jadi minta mereka membaca titik akhir daripada environment_status dan bukannya meneka URL.
Pull request daripada fork
Bahagian bertajuk “Pull request daripada fork”Kod PR fork tidak dipercayai, dan pada peletakan hos ia berjalan sebagai pengguna OS pelayan. policy.forkPrs menentukan apa yang berlaku:
| Nilai | Kesan | Lalai untuk |
|---|---|---|
rig |
Fail compose berjalan dalam VM tanpa gesaan | Definisi yang hanya ada komponen compose dan task |
approval |
Setiap permulaan memerlukan pentadbir | Semua definisi lain |
deny |
Ditolak | Tiada |
seedFilestidak pernah disalin untuk fork, kerana biasanya ia rahsia. Fail compose yang mengikat salah satunya melaporkan fail yang hilang mengikut nama.- Tugasan
provisiondanarchivedilangkau melainkan dasar ialahrig, dan dalam keadaan itu ia berjalan dalam VM. - Pada peletakan hos,
privileged, ruang nama hos, ikatan soket Docker,devicesdan ikatan di luar worktree ruang ditolak pada fork. Dalam ruang yang dipercayai, ia hanya memberi amaran.
Peletakan rig
Bahagian bertajuk “Peletakan rig”"placement": "rig" menjalankan komponen compose dan task dalam microVM khusus. Definisi dengan komponen process, cli atau app tidak layak. Fail compose berjalan tanpa diubah, tanpa soket Docker hos dan tanpa kelayakan pengendali, dan akses rangkaian dihadkan kepada pendaftaran yang diperlukan imejnya. Worktree dilekapkan secara langsung.
- Tetamu arm64. Tetamu ialah arm64 pada Apple Silicon, jadi imej amd64 sahaja tidak akan berjalan.
- Pendaftaran peribadi ditolak. Tetamu tiada kelayakan pendaftaran, jadi imej pada pendaftaran di luar yang awam dan dikenali ditolak sebelum VM dihidupkan. Repositori peribadi pada pendaftaran awam gagal apabila tetamu menariknya.
- Storan 16 GiB. Semua imej dan volum stack berkongsi satu cakera 16 GiB, dan ia tidak boleh dinaikkan.
- But pertama perlahan. Lapisan imej adalah bagi setiap VM, jadi but pertama menarik semuanya. Rig yang dihentikan mengekalkan cakeranya.
- Imej asas mesti boleh dibaca. Dockerfile yang menamakan imej asasnya melalui pemboleh ubah tidak boleh dirancang, kerana akses rangkaian ditetapkan semasa but.
- Hayat.
policy.rigTtlHoursmenamatkan VM, secara lalai selepas 24 jam.
Kontrak status untuk pengarang alat
Bahagian bertajuk “Kontrak status untuk pengarang alat”Komponen cli tanpa statusMap menjangkakan kontrak asli, cc-env/1. Kata kerja status mencetak objek ini ke 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": "…" }}stateialahready,starting,stopped,failedataumissing.missingmembawa kepadacreate, manakalastoppeddanfailedmembawa kepadastart. Laporkanmissingdengan kod keluar 0:statusyang gagal dikira sebagaifailed.- Hanya
statediperlukan. Medan yang tidak diketahui diabaikan, dan output yang tidak boleh dihuraikan dipaparkan sebagai merosot, dengan teks mentah sebagai butiran. - URL mesti loopback,
*.localhostatau di bawahrouting.domain, jika tidak ia dibuang. needsRecreate: truememaparkan Cipta semula, yang membuang data. Control Center tidak pernah bertindak sendiri berdasarkannya.- Kata kerja
listmencetak tatasusunan JSON nama, atau objek denganname.
Kod keluar terpakai pada setiap kata kerja:
| Kod | Maksud |
|---|---|
| 0 | OK |
| 3 | Jawapan diperlukan di terminal, contohnya kata laluan sudo. Kata kerja yang disenaraikan dalam interactive dijalankan semula dalam tab terminal untuk orang yang menekan Mula. Jika tidak, Jalankan dalam terminal membuka terminal ruang dengan arahan command alat ditaip tetapi tidak dijalankan, kemudian Cuba semula mencuba lagi. Control Center tidak pernah menjalankan sudo dan tidak pernah menjawab gesaan |
| 4 | Log masuk diperlukan. Arahan command alat menunjukkan caranya |
| 5 | Sesuatu yang bergantung kepadanya tidak tersedia, contohnya masa jalan bekas yang tidak berjalan |
| Lain | Kegagalan |
Kod 3, 4 dan 5 bukan kegagalan. Persekitaran memaparkan Tindakan diperlukan dan menunggu, dan permulaan seterusnya meneruskan dari tempat yang terhenti itu. Tugasan yang keluar dengan salah satu daripadanya membawa maksud yang sama.
Kemajuan pergi ke stderr sebagai JSON dipisahkan baris:
{"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"}Semasa persekitaran bermula, panel menyenaraikan komponen yang dilalui proses mula, setiap satu dengan spinner, tanda semak atau tanda silang. Baris step menyatakan perkara yang sedang dilakukan alat itu sekarang, dan label-nya dipaparkan di bawah baris alat itu sendiri; langkah tidak pernah menambah baris. state langkah ialah pending, running, done atau failed, dan langkah tanpa state dianggap sedang berjalan. Langkah yang melaporkan semula di bawah id yang sama (rentetan atau nombor, atau label yang sama jika tiada) menggantikan apa yang dikatakannya sebelum ini, supaya alat dengan satu spinner boleh mengekalkan satu id dan menukar label. Tanpa id, langkah mengikut satu sama lain: langkah baharu menamatkan yang sebelumnya. Apabila arahan keluar, langkah yang masih berjalan tamat mengikut cara arahan itu tamat.
Baris log membawa satu baris output yang dibalut dalam JSON oleh alat, dan dibaca sebagai output biasa. Baris note pergi ke output larian, dan yang mempunyai "level": "warn" turut kekal pada persekitaran sebagai amaran. Baris terakhir jenis error menjadi ralat berstruktur, dengan command ditawarkan untuk disalin, dan 12 baris output terakhir dipaparkan di bawah message-nya. Tanpanya, Control Center menunjukkan 20 baris stderr terakhir. Apa-apa yang bukan JSON ialah output log biasa.