Thiết lập môi trường
Môi trường là stack đang chạy của một space: các dịch vụ mà một nhánh cần, tách biệt với mọi space khác, hiển thị trong thanh bên và agent có thể truy cập. Pull request cũng có một môi trường, vì mỗi PR vốn đã có space riêng.
Quản trị viên không gian làm việc viết định nghĩa một lần. Sau đó thành viên nhấn Bắt đầu trong phần Môi trường của thanh bên space hoặc PR. Định nghĩa nằm trong cơ sở dữ liệu của không gian làm việc, nên một nhánh tính năng không bao giờ thay đổi thứ Control Center chạy, dù các công cụ vẫn chạy mã của nhánh đó.
Tạo định nghĩa
Phần tiêu đề “Tạo định nghĩa”- Mở Cài đặt → Không gian làm việc → Môi trường. Chỉ quản trị viên không gian làm việc mới có thể thay đổi định nghĩa, và chỉ chủ sở hữu máy chủ mới có thể lưu một định nghĩa chạy trên máy chủ (xem Ai có thể lưu gì).
- Nhấp Định nghĩa mới, rồi Định nghĩa trống hoặc Tạo bản nháp từ repo. Bản nháp quét kho mã để tìm tệp compose,
Procfilevà script trongpackage.json, còn bạn xem lại kết quả. - Điền biểu mẫu, hoặc dùng thẻ JSON. Các ví dụ trên trang này chính là JSON đó.
- Nhấp Chạy kiểm thử. Thao tác này khởi động một môi trường dùng một lần, chờ đến khi sẵn sàng rồi hủy nó.
Khi lưu, định nghĩa được kiểm tra nghiêm ngặt. Trường không xác định, giá trị sai kiểu hoặc lựa chọn viết sai chính tả đều bị từ chối, kèm theo đường dẫn và tên hợp lệ gần nhất, chẳng hạn repos.app.requird: Unknown field. Did you mean "required"?. Khóa $schema ở cấp cao nhất được phép.
Để lưu định nghĩa trong kho mã, dùng Liên kết tệp repo. Control Center chỉ đọc tệp từ nhánh mặc định và chỉ chạy phiên bản đã được phê duyệt: bởi quản trị viên không gian làm việc, hoặc bởi chủ sở hữu máy chủ khi định nghĩa chạy trên máy chủ. Phiên bản mới hơn hiện Có bản cập nhật và không thay đổi gì cho đến khi được phê duyệt.
Ai có thể lưu gì
Phần tiêu đề “Ai có thể lưu gì”Một định nghĩa môi trường có thể chạy lệnh trên máy chủ với tư cách người dùng của máy chủ. Đó là quyết định của chủ sở hữu máy chủ, không phải của một vai trò trong không gian làm việc:
- Một định nghĩa chạy trên máy chủ khi nó có vị trí đặt trên host, một kiểm tra chạy một lệnh, hoặc một tác vụ
provisionhoặcarchive. Những tác vụ đó chạy trong worktree của space trên máy chủ bất kể vị trí đặt là gì. - Chỉ chủ sở hữu máy chủ mới có thể lưu hoặc phê duyệt một định nghĩa chạy trên máy chủ. Điều đó bao gồm việc phê duyệt một phiên bản mới của tệp repo được liên kết. Quản trị viên không gian làm việc thử làm vậy sẽ thấy “Chỉ chủ sở hữu máy chủ mới có thể lưu hoặc phê duyệt môi trường chạy trên máy chủ. Quản trị viên không gian làm việc có thể dùng môi trường chạy trong rig.”
- Quản trị viên không gian làm việc có thể lưu và phê duyệt một định nghĩa chạy hoàn toàn trong rig:
"placement": "rig", không có lệnh kiểm tra và không có tác vụprovisionhoặcarchive. - Thành viên bắt đầu, dừng và dùng môi trường theo cả hai cách.
- Một định nghĩa chạy trên máy chủ chỉ chạy sau khi chủ sở hữu máy chủ hiện tại đã lưu hoặc phê duyệt nó. Máy chủ tự ghi nhận phê duyệt đó và kiểm tra trước mỗi lần khởi động, kiểm tra, tác vụ và đồng bộ head của pull request. Một định nghĩa mà chủ sở hữu hiện tại chưa phê duyệt, chẳng hạn một định nghĩa do chủ sở hữu trước đó lưu, sẽ chờ dưới dòng của nó trong danh sách môi trường và trong trình soạn thảo. Chủ sở hữu máy chủ thấy “Chạy trên máy chủ này. Hãy phê duyệt để cho phép nó khởi động.” cùng Phê duyệt, thao tác này lưu nó không đổi; những người khác thấy “Chạy trên máy chủ này. Chủ sở hữu máy chủ cần phê duyệt trước khi nó có thể khởi động.”
- Một môi trường đang chờ phê duyệt đó hiển thị “Chủ sở hữu máy chủ chưa phê duyệt môi trường này, nên nó không thể chạy trên máy chủ này.” Thay vào đó, chủ sở hữu máy chủ thấy “Bạn chưa phê duyệt môi trường này. Nó chạy trên máy chủ này, nên sẽ khởi động khi bạn phê duyệt định nghĩa của nó.” cùng Xem xét và phê duyệt, thao tác này mở định nghĩa.
- Các terminal tiến trình của môi trường và terminal mà lần khởi động mở khi cần đến bạn đều chạy trên máy chủ. Gõ vào một terminal, đổi kích thước hoặc đóng nó đều cần quyền ghi trên mọi kho mã mà space công bố, đọc được qua đăng nhập forge của chính bạn: giống như khi bắt đầu môi trường. Những người khác hoàn toàn không tiếp cận được các terminal đó.
Định nghĩa nhỏ nhất
Phần tiêu đề “Định nghĩa nhỏ nhất”Một kho mã compose đơn giản chỉ cần chừng này:
{ "contract": 1, "name": "Shop", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "components": [ { "kind": "compose", "id": "stack" } ]}Mọi thứ khác đều có giá trị mặc định: tệp compose được phát hiện, mọi dịch vụ đều chạy, cổng được gán, điểm cuối HTTP được phát hiện và môi trường được đặt tên theo nhánh.
Các loại thành phần
Phần tiêu đề “Các loại thành phần”Môi trường là một danh sách thành phần có thứ tự. Mỗi thành phần chờ thành phần trước sẵn sàng, trừ khi after chỉ định thành phần khác, và việc dừng diễn ra theo thứ tự ngược lại. enabledWhen ràng buộc một thành phần theo một tùy chọn hoặc vai trò, ví dụ opt.seed, !opt.seed hoặc repo.web. Thành phần có vai trò không bắt buộc và không có trong space cũng bị loại bỏ tương tự, không cần enabledWhen: nó không khởi động và không có {port.*} hay {url.*}, nên thành phần khác đọc các giá trị đó sẽ làm lần khởi động thất bại.
| Loại | Ai chạy | Dùng cho |
|---|---|---|
compose |
Trình điều khiển compose của Control Center | Mọi tệp compose, một tệp cho mỗi môi trường |
cli |
Công cụ của bạn. Control Center gọi các động từ đã ánh xạ và đọc JSON | Công cụ tự quản lý vòng đời, tên miền và dữ liệu |
process |
Control Center, trong phiên terminal được giám sát | Máy chủ phát triển và worker |
task |
Control Center, một lần cho mỗi trình kích hoạt | Cài đặt, di chuyển dữ liệu, kiểm thử |
app |
Control Center, khi ai đó nhấp Khởi chạy | Ứng dụng máy tính |
Thành phần task nhận một danh sách when:
| Trình kích hoạt | Chạy khi |
|---|---|
provision |
Worktree được tạo (xem tác vụ worktree bên dưới) |
create |
Một lần cho mỗi môi trường, và lại chạy sau khi đặt lại |
start |
Mỗi lần khởi động |
change |
Sau khi đồng bộ, khi đường dẫn đã đổi khớp với onChange |
manual |
Theo yêu cầu: Chạy, cc-env run <id> hoặc environment_run_task |
archive |
Ngay trước khi worktree bị hủy |
Một tác vụ không có việc gì phải làm khi khởi động sẽ hiển thị Nhàn rỗi và không xuất hiện trong danh sách bước hiển thị trong lúc môi trường khởi động: một tác vụ manual hoặc change, hoặc một tác vụ create đã chạy rồi.
Lệnh viết dưới dạng mảng là argv, nên giá trị tùy chọn không bao giờ đi qua shell. Một chuỗi, hoặc script với mảng các dòng, chạy dưới bash -lc. Các phần giữ chỗ như {name}, {branch}, {stateDir}, {repo.<role>}, {port.<key>}, {opt.<key>} và {url.<role>} chỉ được mở rộng trong argv. Lệnh shell đọc cùng các giá trị đó qua biến CC_ENV_*, ví dụ $CC_ENV_PORT_WEB. Một phần giữ chỗ không xác định trong thành phần thuộc space này sẽ dừng lần khởi động trước khi có gì được chạy.
Mỗi lệnh và terminal của space còn nhận CC_ENV_NAME, CC_ENV_STATE_DIR, CC_ENV_URL, CC_SPACE_ID, CC_ENV_REPO_<ROLE> và, trong space của PR, CC_PR_NUMBER cùng CC_PR_IS_FORK. Khi có thành phần compose, chúng còn nhận COMPOSE_PROJECT_NAME và COMPOSE_FILE, nên docker compose exec trong tác vụ đến đúng dự án.
Vai trò và thư mục làm việc
Phần tiêu đề “Vai trò và thư mục làm việc”Định nghĩa gắn vai trò với các kho mã của không gian làm việc, nên một stack có thể trải trên nhiều kho mã:
"repos": { "api": { "repoId": "<api>", "anchor": true, "required": true }, "web": { "repoId": "<web>", "anchor": true }, "e2e": { "repoId": "<e2e>", "whenMissing": "useSource" }}anchor: space có thể khởi động môi trường khi chứa ít nhất một vai trò neo. Nếu hai định nghĩa cùng khớp, người khởi động sẽ chọn.required: stack không chạy được nếu thiếu kho mã này.whenMissing: điều xảy ra khi space thiếu vai trò.addToSpacethêm kho mã ở nhánh mặc định và là mặc định cho vai tròrequired.useSourcetruyền bản checkout đã đăng ký của bạn, cần coi là chỉ đọc.skipđể biến không được đặt và là mặc định trong các trường hợp khác.- Khởi động cần quyền
writetrên một kho mã neo trong space và quyền đọc với mọi kho mã đã gắn khác.
Lệnh chạy trong vai trò đầu tiên được khai báo trong repos, không bao giờ chạy ở vai trò khác mà space tình cờ có, nên định nghĩa một kho mã không cần nhắc đến. Bất kỳ thành phần nào cũng có thể ghi đè bằng "cwd": { "role": "e2e", "path": "packages/ui" }. Cả hai trường đều không bắt buộc. Khi vai trò đầu tiên có thể thiếu trong một space, vì nó không phải required cũng không phải neo duy nhất, mọi thành phần đều phải nêu rõ vai trò của nó.
Cổng và URL
Phần tiêu đề “Cổng và URL”Control Center gán cổng máy chủ trước khi bất cứ thứ gì khởi động, từ một dải dùng chung cho cả máy chủ (mặc định 42000 đến 49999, theo khối 32). Một cổng giữ nguyên trong suốt vòng đời môi trường, và cổng compose chỉ gắn với 127.0.0.1.
- Cổng compose không cần khai báo. Đọc chúng dưới dạng
{port.postgres.5432}hoặcCC_ENV_PORT_POSTGRES_5432. - Các cổng khác được khai báo tại nơi dùng, bằng
"port": "web"hoặc"ports": ["web", "hmr"], và đọc dưới dạng{port.web}. Tiến trình có cổng cũng nhậnPORTvàHOST=127.0.0.1.
Điểm cuối HTTP nhận một URL trên bộ định tuyến của máy chủ, vốn lắng nghe trên một cổng loopback:
http://<endpoint>--<name>--<project>.localhost:<router port>http://web--fix-login--shop.localhost:7355<name>là nhánh ở dạng slug, hoặcpr-<n>trong space của PR.<project>lànaming.project, nếu không thì là tên định nghĩa.- Tên
*.localhosttrỏ về loopback nên không cần mục hosts hay DNS, và tên máy giữ cookie tách biệt giữa các môi trường. - Cổng compose trả lời HTTP được phát hiện, và
httptrên thành phần sẽ ghi đè phán đoán đó. Tiến trình cần"endpoint": { "role": "web", "primary": true }, điều này cũng cung cấp{url.web}. - Trong trình duyệt (VM), dùng Mở trong Browser (VM).
https://web--fix-login--shop.localhost/đến cùng tuyến ở đó. - Toàn bộ nhãn nằm trong 63 ký tự, nên tên dài được rút ngắn bằng hàm băm.
- Hai điểm cuối không có chung tên miền cha. Ứng dụng cần một cookie cho cả hai phải phục vụ chúng từ một điểm cuối.
Với URL phải đăng ký trước, như chuyển hướng OAuth, "naming": { "pool": { "names": "cc{n}", "size": 8 }, "project": "shop" } cho một tập tên cố định.
policy quyết định khi nào môi trường chạy. autoCreate là off, prSpaces hoặc allSpaces, idleStopMinutes mặc định là 240, followPrHead đồng bộ môi trường của PR khi head di chuyển, và với maxRunning (mặc định 6) Bắt đầu đề nghị dừng môi trường lâu chưa dùng nhất.
Ví dụ: ứng dụng compose
Phần tiêu đề “Ví dụ: ứng dụng compose”Một ứng dụng web và Postgres từ một tệp compose, với .env bị git bỏ qua, các lần di chuyển dữ liệu và một tác vụ kiểm thử. seedFiles sao chép các tệp được chỉ định từ bản checkout đã đăng ký vào mỗi worktree mới.
{ "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 cho phép một dịch vụ không có kiểm tra sức khỏe riêng giữ thành phần tiếp theo lại. Nếu không có, container đang chạy được tính là sẵn sàng, và di chuyển dữ liệu có thể chạy trước cơ sở dữ liệu còn đang khởi động.
Mỗi lần khởi động và làm mới đều chạy up với --remove-orphans, nên dịch vụ đã bị xóa khỏi tệp compose sẽ dừng và giải phóng cổng của nó. Image được build khi khởi động và khi làm mới, trừ khi thành phần đặt "build": false.
Ví dụ: CLI tùy chỉnh
Phần tiêu đề “Ví dụ: CLI tùy chỉnh”Một công cụ giả định acme tự quản lý container, tên miền và TLS. Control Center cung cấp {name} và biết mọi thứ khác từ status. Nó không bao giờ tự suy ra tên máy của công cụ và không bao giờ sửa /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,statusvàdestroylà bắt buộc. Control Center chọncreatehoặcstarttheo trạng thái đọc được. Bất kỳ động từ nào cũng có thể là{ "shell": "…" }thay cho argv.interactiveliệt kê các động từ, trong sốcreate,startvàreset, có thể yêu cầu thông tin cần thiết trên terminal. Khi động từ như vậy thoát với mã 3 đối với người đã nhấn Start, Control Center chạy lại đúng động từ đó trên một tab terminal, và lần khởi động tiếp tục khi nó thoát với mã 0. Ở đó, điều kiệninteractivelà đúng vàCC_ENV_INTERACTIVE=1được đặt, nên{ "if": "!interactive", "args": ["--json"] }giữ đầu ra dành cho máy cho đường ống. Lần khởi động bởi agent hoặc lần khởi động tự động không bao giờ mở terminal: môi trường hiển thị Cần thao tác và chờ.- Lệnh
destroybị lỗi vẫn xóa môi trường khistatussau đó báomissing, nên một môi trường mà công cụ không còn có thể luôn được xóa. listcho phép Control Center nhận ra một môi trường mà công cụ đã làm mất. Nó chỉ được đánh dấu là đã mất khi tên của nó không có tronglistvàstatussau đó báomissing. Đầu ra không thể đọc như một danh sách thì không thay đổi gì.{service}tronglogsvàexecphải là một từ không bắt đầu bằng-, và là một trong các dịch vụ mà công cụ báo cáo lần gần nhất khi nó có báo cáo.statusMapđọc JSON của công cụ bằng con trỏ JSON, trong đó*khớp mọi mục. Các quy tắc trạng thái có thứ tự và kết quả khớp đầu tiên thắng. Điều kiện làpathvớiequals, hoặcanyhaynonevớiwhere.keepsDataOnStop: falsetắt dừng khi nhàn rỗi và thêm cảnh báo mất dữ liệu vào Dừng. Đặt khi việc dừng làm mất dữ liệu.routing.mode: "tool"nối tên máy của công cụ với trình duyệt (VM) và agent. Tên miền phải kết thúc bằng.test,.localhosthoặc.internal, và URL được báo cáo ngoài đó bị loại bỏ.
Công cụ của riêng bạn có thể bỏ qua statusMap và in hợp đồng trạng thái được mô tả ở cuối trang này.
Ví dụ: monorepo pnpm
Phần tiêu đề “Ví dụ: monorepo pnpm”Chỉ có tiến trình và tác vụ, không có container. Ứng dụng web tìm API qua {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"] } ]}- Mỗi tiến trình là một thẻ terminal mà bạn có thể mở, đọc và gõ vào, nếu bạn có quyền ghi trên mọi kho mã trong space (xem Ai có thể lưu gì). Đóng thẻ không dừng tiến trình.
readynhậnhttp(URL đầy đủ),tcp(host:port) hoặclogMatch(biểu thức chính quy).restartlàon-failure(mặc định),alwayshoặcnever.restartOnkhởi động lại tiến trình khi đường dẫn đã đổi khớp.optionstrở thành biểu mẫu tại Bắt đầu, vàagentDefaultáp dụng cho lần chạy do agent khởi động.
Ví dụ: ứng dụng máy tính
Phần tiêu đề “Ví dụ: ứng dụng máy tính”Một ứng dụng máy tính có bước build. Ứng dụng hoạt động như nhau dù xây dựng bằng gì, vì Control Center làm việc ở mức cửa sổ của hệ điều hành và không cần hook hay SDK trong ứng dụng.
{ "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" } ]}Ứng dụng không khởi động cùng môi trường. Ai đó nhấp Khởi chạy, và prepare chạy trước. Dựng lại và khởi chạy lại chạy lại cặp đó. enabledWhen áp dụng cho ứng dụng và cho tác vụ prepare của nó, và Khởi chạy bị từ chối khi một trong hai đang tắt. Ứng dụng được coi là đang chạy khi bất kỳ tiến trình nào trong nhóm tiến trình của nó đang chạy, nên một launcher khởi động ứng dụng rồi thoát vẫn ổn. Nếu tất cả đã biến mất trong khoảng 5 giây sau Khởi chạy, ứng dụng hiển thị là lỗi cùng các dòng nhật ký cuối. Sau đó, thoát sạch hiển thị là đã đóng, sự cố hiện các dòng nhật ký cuối, và cả hai đều không khởi động lại ứng dụng. Khởi động lại máy chủ sẽ đóng ứng dụng và không bao giờ mở lại nó, và dừng khi nhàn rỗi không đụng đến ứng dụng đang chạy.
Quyền và giới hạn của ứng dụng máy tính
Phần tiêu đề “Quyền và giới hạn của ứng dụng máy tính”- Trên macOS, cấp cho Control Center Ghi màn hình và Trợ năng một lần trong Cài đặt hệ thống. Máy chủ cần một phiên đồ họa: máy chủ headless từ chối mở ứng dụng.
- Mở trực tiếp tệp nhị phân.
open -agiao ứng dụng cho LaunchServices và ứng dụng rời khỏi cây tiến trình mà Control Center theo dõi, nên ứng dụng hiển thị là lỗi ngay sau khi khởi chạy. - Cửa sổ ở lại trên một màn hình. macOS không chụp cửa sổ nằm ngoài mọi màn hình, nên ứng dụng mà agent đang dùng hiện trên màn hình của máy chủ. Không cần tiêu điểm.
"isolate": "home"cho ứng dụng một thư mục home riêng quaHOME,XDG_*vàCFFIXED_USER_HOME, để các bản từ hai space chạy song song.NSUserDefaultskhông được cô lập, nên tùy chọn Cocoa vàshared_preferencescủa Flutter vẫn dùng chung giữa các bản.isolatechỉ áp dụng cho tiến trình được mở. Trình khởi chạy toolchain nhưflutter runcần home thật, nên hãy dùngisolatevới tệp nhị phân đã build. Nếu ứng dụng có thiết lập riêng, như--user-data-dir, hãy ưu tiên nó.- Agent điều khiển cửa sổ bằng
app_use, chỉ có thể chạm tới cây tiến trình của môi trường này. Agent thấy cửa sổ, không thấy màn hình nền. Lần mở do agent đi qua chính sách hành động và mặc định sẽ hỏi, và đầu vào của agent dừng khi có người đang điều khiển. "input": "background"(mặc định) gửi sự kiện tới tiến trình."foreground"kích hoạt cửa sổ và chiếm con trỏ.
Tác vụ worktree
Phần tiêu đề “Tác vụ worktree”Tác vụ provision và archive chạy việc thiết lập và dọn dẹp của một kho mã cùng worktree của nó. Biểu tượng trên hàng của kho mã trong Cài đặt → Không gian làm việc → Kho lưu trữ mở định nghĩa của kho mã đó.
Các tác vụ này đi theo worktree, không theo môi trường, nên chúng chạy cả trong những space không ai nhấp Bắt đầu:
provision |
archive |
|
|---|---|---|
| Chạy khi | Worktree của vai trò được tạo, trong bất kỳ space nào | Ngay trước khi worktree đó bị hủy |
| Khi lỗi | Cấp phát thất bại và worktree bị hủy | Được ghi lại, không bao giờ chặn việc xóa |
| Thời gian chờ mặc định | 5 phút | 2 phút |
| Thấy | CC_WORKSPACE_PATH, CC_ROOT_PATH, CC_SPACE_*, CC_REPO_NAME |
Giống vậy |
Kho mã không có stack chỉ cần một định nghĩa chứa các tác vụ của nó. Vì không có gì để khởi động, không cần vai trò neo:
{ "contract": 1, "name": "Web", "repos": { "app": { "repoId": "<id>" } }, "components": [ { "kind": "task", "id": "setup", "when": ["provision"], "script": ["pnpm install", "cp \"$CC_ROOT_PATH/.env\" .env"] } ]}- Chưa có môi trường, nên các tác vụ này không thể dùng
{name},{port.*},{url.*},{opt.*}hoặcenabledWhen, và không nhậnenvcủa định nghĩa. - Chỉ một định nghĩa được giữ tác vụ
provisionvàarchivecho một kho mã. Các định nghĩa khác vẫn có thể gắn nó cho những việc còn lại. "when": ["provision", "change"]cũng cài lại khi lockfile thay đổi.- Tác vụ chạy cho worktree của vai trò
cwd, nên định nghĩa nhiều kho mã có thể thiết lập từng kho riêng. - Lần chạy thử đặt
CC_SCRIPT_TEST=1. Lần thử lại bắt đầu từ worktree sạch, nên hãy viết tác vụ chịu được việc chạy lại.
Agent
Phần tiêu đề “Agent”Agent không bao giờ nhận socket Docker. Trong space có định nghĩa đủ điều kiện, lần chạy nhận cc-env trên PATH của nó. Space lấy từ lần chạy, nên agent chỉ có thể tác động lên môi trường của mình, và mỗi lệnh đều đi qua chính sách hành động.
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>Với thành phần compose, shim docker cũng cho phép docker compose với ps, logs, exec, port, restart và top, và chỉ với dự án compose riêng của môi trường này. Không được đặt cờ trước động từ, và mỗi động từ nhận một danh sách ngắn các tùy chọn: logs không thể theo dõi đầu ra, còn exec chỉ nhận -T (hoặc --no-tty). Các tùy chọn trỏ compose tới một tệp hoặc dự án khác (-f, -p, --project-directory, --env-file, --profile) đều bị từ chối dù xuất hiện ở đâu. Mọi thứ khác thoát với mã 5 và “not available in Control Center agent runs”.
Kho mã có kỹ năng gọi công cụ riêng của nó có thể tiếp tục làm vậy. Khối agentPassthrough trên thành phần cli khai báo các lệnh agent được phép chạy. Chỉ những lệnh mà định nghĩa đã phê duyệt khai báo mới được chuyển tiếp, và mỗi lệnh chạy trên máy chủ, nên nó mang quy tắc Chạy lệnh trên máy chủ, vốn hỏi trước theo mặc định:
"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 chỉ tên thao tác có chính sách được áp dụng. positionalName ép đối số đó thành môi trường của space này, nameFilter lọc đầu ra JSON theo môi trường đó, và mỗi giá trị pathFlags phải trỏ vào bên trong worktree của lần chạy. Lệnh không khớp quy tắc nào thoát với mã 5.
Các thao tác tương tự có dưới dạng công cụ: environment_status, environment_up, environment_down, environment_reset, environment_destroy, environment_restart, environment_exec, environment_logs, environment_run_task, environment_launch_app và environment_stop_app. Agent trong sandbox tiếp cận cổng của mình trực tiếp và tên máy của môi trường qua proxy của lần chạy, nên hãy bảo chúng đọc điểm cuối từ environment_status thay vì đoán URL.
Pull request từ fork
Phần tiêu đề “Pull request từ fork”Mã của PR từ fork không đáng tin, và với vị trí trên máy chủ, nó chạy dưới người dùng hệ điều hành của máy chủ. policy.forkPrs quyết định điều xảy ra:
| Giá trị | Tác dụng | Mặc định cho |
|---|---|---|
rig |
Tệp compose chạy trong VM mà không hỏi | Định nghĩa chỉ có thành phần compose và task |
approval |
Mỗi lần khởi động cần quản trị viên | Mọi định nghĩa khác |
deny |
Từ chối | Không có |
seedFileskhông bao giờ được sao chép cho fork, vì chúng thường là bí mật. Tệp compose gắn một tệp như vậy sẽ báo tên tệp bị thiếu.- Tác vụ
provisionvàarchivebị bỏ qua trừ khi chính sách làrig, khi đó chúng chạy trong VM. - Với vị trí trên máy chủ,
privileged, không gian tên của máy chủ, gắn socket Docker,devicesvà các gắn kết ngoài worktree của space đều bị từ chối trên fork. Trong space đáng tin, chúng chỉ tạo cảnh báo.
Vị trí trong rig
Phần tiêu đề “Vị trí trong rig”"placement": "rig" chạy các thành phần compose và task trong một microVM riêng. Định nghĩa có thành phần process, cli hoặc app không đủ điều kiện. Tệp compose chạy nguyên trạng, không có socket Docker của máy chủ và không có thông tin xác thực của người vận hành, và truy cập mạng giới hạn ở các registry mà image của nó cần. Worktree được gắn trực tiếp.
- Máy khách arm64. Máy khách là arm64 trên Apple Silicon, nên image chỉ có amd64 sẽ không chạy.
- Registry riêng tư bị từ chối. Máy khách không có thông tin xác thực registry, nên image trên registry ngoài các registry công khai đã biết bị từ chối trước khi VM khởi động. Kho riêng tư trên registry công khai sẽ thất bại khi máy khách kéo về.
- Lưu trữ 16 GiB. Mọi image và volume của stack dùng chung một đĩa 16 GiB, và không thể tăng.
- Lần khởi động đầu chậm. Lớp image là riêng cho từng VM, nên lần khởi động đầu kéo về mọi thứ. Rig đã dừng vẫn giữ đĩa.
- Image gốc phải đọc được. Dockerfile đặt tên image gốc qua biến thì không lập kế hoạch được, vì truy cập mạng được cố định khi khởi động.
- Vòng đời.
policy.rigTtlHourskết thúc VM, mặc định sau 24 giờ.
Hợp đồng trạng thái cho tác giả công cụ
Phần tiêu đề “Hợp đồng trạng thái cho tác giả công cụ”Thành phần cli không có statusMap mong đợi hợp đồng gốc, cc-env/1. Động từ status in đối tượng này ra 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": "…" }}statelàready,starting,stopped,failedhoặcmissing.missingdẫn đếncreate, cònstoppedvàfaileddẫn đếnstart. Báomissingvới mã thoát 0: mộtstatusthất bại được tính làfailed.- Chỉ cần
state. Trường không biết bị bỏ qua, và đầu ra không phân tích được hiển thị là suy giảm, với văn bản thô làm chi tiết. - URL phải là loopback,
*.localhosthoặc nằm dướirouting.domain, nếu không sẽ bị loại bỏ. needsRecreate: truehiện Tạo lại, thao tác này bỏ dữ liệu. Control Center không bao giờ tự hành động theo giá trị này.- Động từ
listin một mảng JSON gồm tên, hoặc gồm đối tượng cóname.
Mã thoát áp dụng cho mọi động từ:
| Mã | Ý nghĩa |
|---|---|
| 0 | OK |
| 3 | Cần câu trả lời tại terminal, chẳng hạn mật khẩu sudo. Động từ được liệt kê trong interactive sẽ chạy lại trên một tab terminal cho người đã nhấn Start. Nếu không, Chạy trong terminal mở terminal của space với command của công cụ đã gõ nhưng chưa chạy, rồi Thử lại thử lại. Control Center không bao giờ chạy sudo và không bao giờ trả lời prompt |
| 4 | Cần đăng nhập. command của công cụ cho biết cách |
| 5 | Thứ mà nó phụ thuộc không khả dụng, chẳng hạn runtime container không chạy |
| Khác | Thất bại |
Mã 3, 4 và 5 không phải là lỗi. Môi trường hiển thị Cần thao tác và chờ, và lần khởi động tiếp theo tiếp tục từ chỗ lần trước đã dừng. Tác vụ thoát với một trong các mã này cũng có ý nghĩa tương tự.
Tiến độ được gửi tới stderr dưới dạng JSON phân tách theo dòng:
{"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"}Khi một môi trường đang khởi động, bảng điều khiển liệt kê các thành phần mà quá trình khởi động đi qua, mỗi thành phần kèm một biểu tượng đang xoay, dấu tick hoặc dấu nhân. Dòng step cho biết công cụ đang làm gì, và label của nó hiển thị dưới dòng riêng của công cụ; bước không bao giờ thêm dòng. state của một bước là pending, running, done hoặc failed, và bước không có state được coi là đang chạy. Một bước báo cáo lại với cùng id (chuỗi hoặc số, hoặc cùng label nếu không có id) sẽ thay thế nội dung trước đó, nên một công cụ chỉ có một biểu tượng đang xoay có thể giữ nguyên id và chỉ đổi label. Khi không có id, các bước nối tiếp nhau: bước mới kết thúc bước trước. Khi lệnh thoát, bước còn đang chạy kết thúc theo cách lệnh đã kết thúc.
Dòng log chứa một dòng đầu ra mà công cụ đã bọc trong JSON, và được đọc như văn bản đầu ra thông thường. Dòng note được đưa vào đầu ra của lần chạy, và dòng có "level": "warn" còn được giữ trên môi trường như một cảnh báo. Dòng cuối có loại error trở thành lỗi có cấu trúc, với command được đề nghị sao chép, và 12 dòng đầu ra cuối cùng hiển thị bên dưới message. Nếu không có, Control Center hiện 20 dòng stderr cuối. Mọi thứ không phải JSON là đầu ra nhật ký thông thường.