设置环境
环境是一个空间运行中的技术栈:分支所需的服务,与所有其他空间隔离,显示在侧边栏中,智能体可以访问。拉取请求也有环境,因为 PR 本来就有自己的空间。
工作区管理员只需编写一次定义。之后成员在空间或 PR 侧边栏的 环境 部分点击 开始。定义保存在工作区数据库中,因此功能分支永远不会改变 Control Center 运行的内容,不过工具仍会运行该分支的代码。
创建定义
标题为“创建定义”的部分- 打开 设置 → 工作区 → 环境。只有工作区管理员可以更改定义,并且只有服务器所有者可以保存在服务器主机上运行的定义(参见谁可以保存什么)。
- 点击 新建定义,然后选择 空白定义 或 从仓库生成草稿。草稿会在仓库中查找 compose 文件、
Procfile和package.json脚本,由你审阅结果。 - 填写表单,或使用 JSON 选项卡。本页的示例就是该 JSON。
- 点击 运行测试。它会启动一个一次性环境,等待就绪后将其销毁。
保存时会严格检查定义。未知字段、类型错误的值或拼写错误的选项都会被拒绝,并给出其路径和最接近的有效名称,例如 repos.app.requird: Unknown field. Did you mean "required"?。顶层允许使用 $schema。
要把定义保存在仓库中,请使用 关联仓库文件。Control Center 只从默认分支读取该文件,并且只运行已批准的版本:由工作区管理员批准,或当定义在主机上运行时由服务器所有者批准。较新的版本会显示 有可用更新,在批准之前不会改变任何内容。
谁可以保存什么
标题为“谁可以保存什么”的部分环境定义可以以服务器自身用户的身份在服务器主机上运行命令。这是服务器所有者的决定,而不是工作区角色的决定:
- 当定义具有主机放置方式、包含运行命令的检查,或包含
provision或archive任务时,它会在主机上运行。无论放置方式如何,这些任务都会在主机上的空间工作树中运行。 - 只有服务器所有者可以保存或批准在主机上运行的定义。这包括批准关联仓库文件的新版本。工作区管理员如果尝试这样做,会看到“只有服务器所有者才能保存或批准在服务器主机上运行的环境。工作区管理员可以使用在 rig 中运行的环境。”
- 工作区管理员可以保存并批准完全在 rig 中运行的定义:
"placement": "rig",没有检查命令,也没有provision或archive任务。 - 无论哪种方式,成员都可以启动、停止和使用环境。
- 在主机上运行的定义,只有在当前服务器所有者保存或批准之后才会运行。服务器自己记录该批准,并在每次启动、检查、任务以及拉取请求 head 同步之前进行检查。当前所有者尚未批准的定义(例如由前任所有者保存的定义)会在环境列表和编辑器中它所在的行下等待。服务器所有者会看到“在此服务器上运行。批准后即可启动。”以及批准按钮,点击它会在不作改动的情况下保存该定义;其他人则会看到“在此服务器上运行。服务器所有者须先批准,才能启动。”
- 因等待该批准而被搁置的环境会显示“服务器所有者尚未批准此环境,因此它无法在此服务器上运行。”服务器所有者看到的则是“你尚未批准此环境。它在此服务器上运行,因此你批准其定义后才会启动。”以及审阅并批准按钮,点击它会打开该定义。
- 环境的进程终端,以及启动在需要你时打开的终端,都运行在服务器主机上。在这些终端中输入、调整大小或关闭它们,都需要对空间所暴露的每个仓库具有写入权限,且该权限须通过你自己的代码托管平台登录来读取:与启动环境相同。其他任何人都无法访问这些终端。
最小的定义
标题为“最小的定义”的部分一个普通的 compose 仓库只需要这些:
{ "contract": 1, "name": "Shop", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "components": [ { "kind": "compose", "id": "stack" } ]}其他内容都有默认值:自动发现 compose 文件,运行所有服务,分配端口,检测 HTTP 端点,环境以分支命名。
组件类型
标题为“组件类型”的部分环境是一个有序的组件列表。除非 after 指定了其他组件,否则每个组件都会等待前一个就绪,停止时按相反顺序进行。enabledWhen 让组件取决于某个选项或角色,例如 opt.seed、!opt.seed 或 repo.web。若组件的角色为可选且在空间中缺失,同样会被排除,无需 enabledWhen:它不会启动,也没有 {port.*} 或 {url.*},因此读取这些占位符的其他组件会导致启动失败。
| 类型 | 由谁运行 | 用途 |
|---|---|---|
compose |
Control Center 的 compose 驱动 | 任意 compose 文件,每个环境一个 |
cli |
你的工具。Control Center 调用映射的动词并读取 JSON | 自行管理生命周期、域名和数据的工具 |
process |
Control Center,在受监管的终端会话中 | 开发服务器和 worker |
task |
Control Center,每个触发器运行一次 | 安装、迁移、测试 |
app |
Control Center,在有人点击 启动应用 时 | 桌面应用 |
task 组件接受 when 列表:
| 触发器 | 运行时机 |
|---|---|
provision |
创建工作树时(见下文的工作树任务) |
create |
每个环境一次,重置后再运行一次 |
start |
每次启动时 |
change |
同步之后,已更改的路径匹配 onChange 时 |
manual |
按需:运行、cc-env run <id> 或 environment_run_task |
archive |
工作树销毁前 |
启动时无事可做的任务会显示 空闲,并且不会出现在环境启动时显示的步骤列表中:即 manual 或 change 任务,或已经运行过的 create 任务。
以数组形式给出的命令是 argv,因此选项值绝不会经过 shell。字符串,或带行数组的 script,在 bash -lc 下运行。{name}、{branch}、{stateDir}、{repo.<role>}、{port.<key>}、{opt.<key>} 和 {url.<role>} 等占位符只在 argv 中展开。shell 命令通过 CC_ENV_* 变量读取相同的值,例如 $CC_ENV_PORT_WEB。在本空间环境中的组件里若出现未知占位符,启动会在任何内容运行之前停止。
每条命令和空间终端还会获得 CC_ENV_NAME、CC_ENV_STATE_DIR、CC_ENV_URL、CC_SPACE_ID、CC_ENV_REPO_<ROLE>,在 PR 空间中还有 CC_PR_NUMBER 和 CC_PR_IS_FORK。有 compose 组件时还会获得 COMPOSE_PROJECT_NAME 和 COMPOSE_FILE,因此任务中的 docker compose exec 能到达正确的项目。
角色和工作目录
标题为“角色和工作目录”的部分定义将角色绑定到工作区仓库,因此一个技术栈可以跨多个仓库:
"repos": { "api": { "repoId": "<api>", "anchor": true, "required": true }, "web": { "repoId": "<web>", "anchor": true }, "e2e": { "repoId": "<e2e>", "whenMissing": "useSource" }}anchor:空间至少包含一个锚点角色时才能启动环境。如果有两个定义匹配,由启动的人选择。required:没有这个仓库,技术栈无法运行。whenMissing:空间缺少该角色时的处理方式。addToSpace以默认分支添加仓库,是required角色的默认值。useSource传入你注册的检出,应将其视为只读。skip不设置变量,是其他情况下的默认值。- 启动需要对空间内某个锚点仓库拥有
write授权,并对所有其他绑定的仓库拥有读取权限。
命令在 repos 中声明的第一个角色里运行,绝不会在空间恰好拥有的其他角色里运行,因此单仓库定义无需提及。任何组件都可以用 "cwd": { "role": "e2e", "path": "packages/ui" } 覆盖。两个字段都是可选的。当第一个角色可能在某个空间中缺失(即它既不是 required,也不是唯一的锚点角色)时,每个组件都必须指明其角色。
端口和 URL
标题为“端口和 URL”的部分Control Center 在任何内容启动之前,从主机范围内的区间分配主机端口(默认 42000 到 49999,每块 32 个)。端口在环境的整个生命周期内保持不变,compose 端口只绑定到 127.0.0.1。
- compose 端口无需声明。用
{port.postgres.5432}或CC_ENV_PORT_POSTGRES_5432读取。 - 其他端口在使用之处用
"port": "web"或"ports": ["web", "hmr"]声明,并用{port.web}读取。带端口的进程还会获得PORT和HOST=127.0.0.1。
HTTP 端点在服务器的路由器上获得一个 URL,路由器只监听一个环回端口:
http://<endpoint>--<name>--<project>.localhost:<router port>http://web--fix-login--shop.localhost:7355<name>是分支的 slug,PR 空间中为pr-<n>。<project>是naming.project,否则是定义的名称。*.localhost名称指向环回地址,因此不需要 hosts 条目或 DNS,主机名还能让环境之间的 Cookie 相互隔离。- 响应 HTTP 的 compose 端口会被检测到,组件上的
http可覆盖这一判断。进程需要"endpoint": { "role": "web", "primary": true },这也会让{url.web}可用。 - 在浏览器 (VM) 中,使用 在 Browser (VM) 中打开。在那里
https://web--fix-login--shop.localhost/会到达相同的路由。 - 整个标签不超过 63 个字符,因此长名称会用哈希缩短。
- 两个端点没有共同的父域。需要在两者之间共用一个 Cookie 的应用必须从一个端点提供服务。
对于必须预先注册的 URL,例如 OAuth 重定向,"naming": { "pool": { "names": "cc{n}", "size": 8 }, "project": "shop" } 提供一组固定的名称。
policy 决定环境何时运行。autoCreate 为 off、prSpaces 或 allSpaces,idleStopMinutes 默认为 240,followPrHead 在 head 移动时同步 PR 环境,maxRunning(默认 6)让 开始 提议停止最久未使用的环境。
示例:compose 应用
标题为“示例:compose 应用”的部分一个 compose 文件中的 Web 应用和 Postgres,带有被 git 忽略的 .env、迁移和测试任务。seedFiles 将指定文件从你注册的检出复制到每个新工作树。
{ "contract": 1, "name": "Shop", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "naming": { "project": "shop" }, "seedFiles": [".env"], "components": [ { "kind": "compose", "id": "stack", "services": ["postgres", "web"], "healthchecks": { "postgres": ["pg_isready", "-U", "postgres"] } }, { "kind": "task", "id": "migrate", "when": ["create", "change"], "onChange": ["db/migrations/**"], "command": "docker compose exec -T web bin/migrate" }, { "kind": "task", "id": "test", "when": ["manual"], "command": "docker compose exec -T web bin/test" } ]}healthchecks 让没有自带健康检查的服务也能阻塞下一个组件。没有它,运行中的容器就算就绪,迁移可能抢在仍在启动的数据库之前运行。
每次启动和刷新都会以 --remove-orphans 运行 up,因此从 compose 文件中删除的服务会停止并释放其端口。除非组件设置了 "build": false,否则启动和刷新时都会构建镜像。
示例:自定义 CLI
标题为“示例:自定义 CLI”的部分一个虚构的 acme 工具,自行管理容器、域名和 TLS。Control Center 提供 {name},其余一切从 status 获知。它绝不推导工具的主机名,也绝不编辑 /etc/hosts。
{ "contract": 1, "name": "Acme", "repos": { "server": { "repoId": "<server>", "anchor": true, "required": true }, "web": { "repoId": "<web>", "anchor": true } }, "routing": { "mode": "tool", "domain": "acme.test", "upstream": "127.0.0.1:443", "tls": true, "caFile": "~/.acme/tls/ca.crt" }, "components": [ { "kind": "cli", "id": "acme", "verbs": { "create": ["acme", "env", "create", "{name}", { "if": "!interactive", "args": ["--json"] }, { "if": "repo.web", "args": ["--web-dir", "{repo.web}"] }], "start": ["acme", "env", "start", "{name}"], "stop": ["acme", "env", "stop", "{name}"], "destroy": ["acme", "env", "destroy", "{name}", "--yes"], "reset": ["acme", "env", "reset-db", "{name}"], "status": ["acme", "env", "status", "{name}", "--json"], "list": ["acme", "env", "ls", "--json"], "logs": ["acme", "env", "logs", "{name}", { "if": "service", "args": ["{service}"] }, "--tail", "{tail}", { "if": "follow", "args": ["--follow"] }], "exec": ["acme", "env", "exec", "{name}", "{service}", "{command}"] }, "interactive": ["create"], "keepsDataOnStop": false, "statusMap": { "state": [ { "when": { "path": "/status/ready", "equals": true }, "state": "ready" }, { "when": { "none": "/status/containers", "where": { "state": "running" } }, "state": "stopped" }, { "when": { "path": "/status/phase", "equals": "failed" }, "state": "failed" }, { "state": "starting" } ], "detail": "phase: {/status/phase}", "warnings": [ { "when": { "path": "/status/dnsWorking", "equals": false }, "message": "Not resolvable on this host" } ], "endpoints": [ { "role": "app", "label": "App", "url": "/urls/app", "primary": true }, { "role": "db", "hostPort": "/ports/db" } ], "services": "/status/containers/*/service", "list": "/*/slug", "missingErrorCodes": ["env.not-found"] } } ]}create、status和destroy是必需的。Control Center 根据读取的状态选择create或start。任何动词都可以用{ "shell": "…" }代替 argv。interactive列出可在终端中请求所需输入的动词,选自create、start和reset。当此类动词因按下 开始 的人而以退出码 3 结束时,Control Center 会在终端标签页中再次运行同一动词,待其以 0 退出后,启动继续进行。在那里,条件interactive为真,并设置了CC_ENV_INTERACTIVE=1,因此{ "if": "!interactive", "args": ["--json"] }会为管道保留机器输出。由智能体发起的启动或自动启动绝不会打开终端:环境显示 需要处理 并等待。destroy失败后,若status随后报告missing,环境仍会被删除,因此工具已不再拥有的环境总能被删除。list让 Control Center 察觉工具已丢失的环境。只有当其名称不再出现在list中且status随后显示missing时,它才会被标记为已消失。无法读取为列表的输出不会产生任何改变。logs和exec中的{service}必须是一个不以-开头的单词,并且是工具最近一次报告的服务之一(如果工具报告过服务)。statusMap用 JSON 指针读取工具自身的 JSON,其中*匹配每一项。状态规则有序,第一个匹配的规则生效。条件是path加equals,或any、none加where。keepsDataOnStop: false关闭空闲停止,并在 停止 上添加数据丢失警告。当停止会丢失数据时设置它。routing.mode: "tool"把工具的主机名连接到浏览器 (VM) 和智能体。域名必须以.test、.localhost或.internal结尾,超出范围的 URL 会被丢弃。
你自己的工具可以省略 statusMap,直接输出本页末尾描述的状态契约。
示例:pnpm 单体仓库
标题为“示例:pnpm 单体仓库”的部分只有进程和任务,没有容器。Web 应用通过 {url.api} 找到 API。
{ "contract": 1, "name": "Monorepo", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "naming": { "project": "mono" }, "options": [ { "key": "seed", "type": "bool", "default": true, "agentDefault": false } ], "components": [ { "kind": "task", "id": "install", "when": ["provision", "change"], "onChange": ["pnpm-lock.yaml"], "command": ["pnpm", "install", "--frozen-lockfile"] }, { "kind": "process", "id": "api", "label": "API", "port": "api", "cwd": { "path": "apps/api" }, "command": ["pnpm", "dev"], "endpoint": { "role": "api" }, "ready": { "http": "http://127.0.0.1:{port.api}/health", "timeout": 120 }, "restartOn": ["pnpm-lock.yaml"] }, { "kind": "task", "id": "seed", "when": ["create"], "enabledWhen": "opt.seed", "cwd": { "path": "apps/api" }, "command": ["pnpm", "db:seed"] }, { "kind": "process", "id": "web", "label": "Dev server", "port": "web", "cwd": { "path": "apps/web" }, "env": { "API_URL": "{url.api}" }, "command": ["pnpm", "dev", "--port", "{port.web}", "--host", "127.0.0.1"], "endpoint": { "role": "web", "primary": true }, "ready": { "http": "http://127.0.0.1:{port.web}/" } }, { "kind": "task", "id": "lint", "when": ["manual"], "command": ["pnpm", "lint"] } ]}- 每个进程都是一个终端选项卡,只要你对空间中的每个仓库都有写入权限,即可打开、阅读和输入(参见谁可以保存什么)。关闭选项卡不会停止进程。
ready接受http(完整 URL)、tcp(host:port)或logMatch(正则表达式)。restart为on-failure(默认)、always或never。restartOn在已更改的路径匹配时重启进程。options会变成 开始 上的表单,agentDefault适用于智能体启动的运行。
示例:桌面应用
标题为“示例:桌面应用”的部分一个带构建步骤的桌面应用。无论用什么技术构建,应用的工作方式都一样,因为 Control Center 在操作系统窗口层面工作,不需要在应用中加入钩子或 SDK。
{ "contract": 1, "name": "Studio", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "components": [ { "kind": "task", "id": "build", "when": ["manual"], "command": ["pnpm", "build"] }, { "kind": "app", "id": "desktop", "label": "Studio", "prepare": "build", "command": ["dist/mac-arm64/Studio.app/Contents/MacOS/Studio"], "isolate": "home" } ]}应用不会随环境启动。有人点击 启动应用 后,先运行 prepare。重新构建并启动 会再次运行这一组合。enabledWhen 同时作用于应用及其 prepare 任务,两者中任一关闭时,启动应用 都会被拒绝。只要进程组中有任何进程在运行,应用就算作正在运行,因此启动应用后立即退出的启动器没有问题。若在点击 启动应用 后约 5 秒内所有进程都已消失,应用会显示为失败,并给出最后的日志行。此后,正常退出显示为已关闭,崩溃显示最后的日志行,两者都不会重启应用。服务器重启会关闭应用且绝不会重新启动它,空闲停止也不会动运行中的应用。
桌面应用的权限和限制
标题为“桌面应用的权限和限制”的部分- 在 macOS 上,在系统设置中为 Control Center 授予一次屏幕录制和辅助功能权限。服务器主机需要图形会话:无头服务器会拒绝启动应用。
- 直接启动二进制文件。
open -a会把应用交给 LaunchServices,应用随之离开 Control Center 跟踪的进程树,因此应用在启动后会立即显示为失败。 - 窗口留在显示器上。macOS 不会捕获位于所有显示器之外的窗口,因此智能体使用的应用在服务器屏幕上可见。它不需要焦点。
"isolate": "home"通过HOME、XDG_*和CFFIXED_USER_HOME为应用提供私有主目录,让两个空间的副本可以并行运行。NSUserDefaults不隔离,因此 Cocoa 偏好设置和 Flutter 的shared_preferences仍在副本之间共享。isolate只作用于启动的进程。flutter run之类的工具链启动器需要真实的主目录,所以请把isolate与构建好的二进制文件搭配使用。如果应用有自己的设置,例如--user-data-dir,请优先使用。- 智能体用
app_use操作窗口,它只能触及此环境的进程树。智能体看到的是窗口,不是桌面。智能体的启动要经过操作策略,默认会询问,而在有人掌握控制权时,智能体的输入会暂停。 "input": "background"(默认)将事件发送给进程。"foreground"激活窗口并接管光标。
工作树任务
标题为“工作树任务”的部分provision 和 archive 任务随仓库的工作树运行该仓库的设置与拆除。设置 → 工作区 → 仓库 中仓库行上的图标会打开该仓库的定义。
这些任务跟随工作树而不是环境,因此在没有人点击 开始 的空间中也会运行:
provision |
archive |
|
|---|---|---|
| 运行时机 | 角色的工作树创建时,在任何空间中 | 该工作树销毁前 |
| 失败时 | 配置失败,工作树被销毁 | 记录下来,绝不阻止删除 |
| 默认超时 | 5 分钟 | 2 分钟 |
| 可见内容 | CC_WORKSPACE_PATH、CC_ROOT_PATH、CC_SPACE_*、CC_REPO_NAME |
相同 |
没有技术栈的仓库只需要一个包含其任务的定义。由于没有可启动的内容,所以不需要锚点角色:
{ "contract": 1, "name": "Web", "repos": { "app": { "repoId": "<id>" } }, "components": [ { "kind": "task", "id": "setup", "when": ["provision"], "script": ["pnpm install", "cp \"$CC_ROOT_PATH/.env\" .env"] } ]}- 此时还没有环境,因此这些任务不能使用
{name}、{port.*}、{url.*}、{opt.*}或enabledWhen,也不会获得定义的env。 - 一个仓库的
provision和archive任务只能由一个定义持有。其他定义仍可为其他用途绑定它。 "when": ["provision", "change"]还会在锁文件变化时重新安装。- 任务针对其
cwd角色的工作树运行,因此多仓库定义可以分别设置每个仓库。 - 测试运行会设置
CC_SCRIPT_TEST=1。重试从干净的工作树开始,所以任务要能承受重新运行。
智能体
标题为“智能体”的部分智能体绝不会获得 Docker 套接字。在有符合条件的定义的空间中,运行的 PATH 上会有 cc-env。空间来自运行本身,因此智能体只能操作自己的环境,每条命令都要经过操作策略。
cc-env statuscc-env upcc-env downcc-env resetcc-env destroycc-env restart <process>cc-env logs <name>cc-env exec <service> -- <cmd>cc-env run <task> -- <args>有 compose 组件时,docker shim 还允许 docker compose 使用 ps、logs、exec、port、restart 和 top,并且只能作用于该环境自己的 compose 项目。动词之前不能有标志,每个动词只接受一小组选项:logs 不能跟踪输出,exec 只接受 -T(或 --no-tty)。任何把 compose 指向其他文件或项目的选项(-f、-p、--project-directory、--env-file、--profile)无论出现在哪里都会被拒绝。其他情况以代码 5 退出,并显示“not available in Control Center agent runs”。
技能调用自身工具的仓库可以继续这样做。cli 组件上的 agentPassthrough 块声明智能体可以运行哪些命令。只有已批准的定义所声明的命令才会被放行,并且每条命令都在主机上运行,因此它受在主机上运行命令规则约束,该规则默认会先询问:
"agentPassthrough": { "binary": "acme", "allow": [ { "argv": ["env", "ls"], "maps": "status", "nameFilter": true }, { "argv": ["env", "status|url"], "maps": "status", "positionalName": 2 }, { "argv": ["env", "create"], "maps": "up", "positionalName": 2, "pathFlags": ["--web-dir"], "denyFlags": ["--force"] }, { "argv": ["env", "logs"], "maps": "logs", "positionalName": 2, "denyFlags": ["--follow"] } ]}maps 指定适用其策略的操作。positionalName 将该参数强制为此空间的环境,nameFilter 将 JSON 输出过滤到该环境,每个 pathFlags 值都必须解析到运行的工作树内。不匹配任何规则的命令以代码 5 退出。
相同的操作也以工具形式提供:environment_status、environment_up、environment_down、environment_reset、environment_destroy、environment_restart、environment_exec、environment_logs、environment_run_task、environment_launch_app 和 environment_stop_app。沙盒中的智能体可直接访问自己的端口,并通过运行的代理访问环境的主机名,所以请让它们从 environment_status 读取端点,不要猜测 URL。
来自复刻的拉取请求
标题为“来自复刻的拉取请求”的部分来自复刻的 PR 的代码不可信,在主机放置下它以服务器的操作系统用户身份运行。policy.forkPrs 决定如何处理:
| 值 | 效果 | 默认用于 |
|---|---|---|
rig |
compose 文件在 VM 中运行,无需确认 | 只含 compose 和 task 组件的定义 |
approval |
每次启动都需要管理员 | 所有其他定义 |
deny |
拒绝 | 无 |
seedFiles绝不会复制给复刻,因为它们通常是机密。绑定其中某个文件的 compose 文件会按名称报告缺失的文件。provision和archive任务会被跳过,除非策略为rig,此时它们在 VM 中运行。- 在主机放置下,复刻上的
privileged、主机命名空间、Docker 套接字绑定、devices以及空间工作树之外的绑定都会被拒绝。在受信任的空间中只发出警告。
Rig 放置
标题为“Rig 放置”的部分"placement": "rig" 在专用的 microVM 中运行 compose 和 task 组件。含有 process、cli 或 app 组件的定义不符合条件。compose 文件原样运行,没有主机 Docker 套接字,也没有操作员凭据,网络访问仅限其镜像所需的镜像仓库。工作树以实时方式挂载。
- arm64 客户机。 在 Apple Silicon 上客户机是 arm64,因此仅支持 amd64 的镜像无法运行。
- 私有镜像仓库会被拒绝。 客户机没有镜像仓库凭据,因此已知公共镜像仓库之外的镜像在 VM 启动前就会被拒绝。公共镜像仓库中的私有仓库会在客户机拉取时失败。
- 16 GiB 存储。 技术栈的所有镜像和卷共用一块 16 GiB 磁盘,且无法扩大。
- 首次启动较慢。 镜像层按 VM 分开,因此首次启动要拉取全部内容。已停止的 rig 会保留磁盘。
- 基础镜像必须可读。 通过变量指定基础镜像的 Dockerfile 无法规划,因为网络访问在启动时就已固定。
- 生命周期。
policy.rigTtlHours终止 VM,默认 24 小时后。
面向工具作者的状态契约
标题为“面向工具作者的状态契约”的部分没有 statusMap 的 cli 组件期望原生契约 cc-env/1。status 动词将此对象打印到 stdout:
{ "state": "ready", "detail": "migrations applied, HTTP 200", "endpoints": [ { "role": "app", "label": "App", "url": "https://fix-login.acme.test", "primary": true }, { "role": "postgres", "label": "Postgres", "hostPort": 49213 } ], "services": ["server", "postgres"], "needsRecreate": false, "error": { "code": "post-start-failed", "message": "…", "hint": "…", "command": "…" }}state为ready、starting、stopped、failed或missing。missing导向create,stopped和failed导向start。请以退出码 0 报告missing:失败的status算作failed。- 只有
state是必需的。未知字段会被忽略,无法解析的输出显示为降级,原始文本作为详情。 - URL 必须是环回地址、
*.localhost或位于routing.domain之下,否则会被丢弃。 needsRecreate: true显示 重新创建,它会丢弃数据。Control Center 绝不会自行据此操作。list动词打印名称数组或带name的对象数组(JSON)。
退出码适用于所有动词:
| 代码 | 含义 |
|---|---|
| 0 | 成功 |
| 3 | 需要在终端中作答,例如输入 sudo 密码。interactive 中列出的动词会在按下 开始 的人的终端标签页中再次运行。否则 在终端中运行 会打开空间终端,并输入工具的 command(但不运行),然后用 重试 重试。Control Center 绝不运行 sudo,也绝不替代回答提示 |
| 4 | 需要登录。工具的 command 说明方法 |
| 5 | 其依赖的内容不可用,例如容器运行时未在运行 |
| 其他 | 失败 |
退出码 3、4 和 5 都不是失败。环境会显示 需要处理 并等待,下一次启动会从上次停止的地方继续。以其中任一退出码结束的任务含义相同。
进度以换行分隔的 JSON 输出到 stderr:
{"type":"step","id":"images","label":"Pull images","state":"running"}{"type":"log","stream":"stdout","line":"postgres Pulled"}{"type":"step","id":"images","label":"Pulled 4 images","state":"done"}{"type":"note","level":"warn","message":"Hosts entries stayed behind after destroy"}{"type":"error","code":"hosts-missing","message":"Add the hosts entry","hint":"Needs sudo","command":"sudo acme hosts add fix-login"}环境启动期间,面板会列出启动所经过的各个组件,每项带有旋转指示器、对勾或叉号。step 行说明工具当前正在做什么,其 label 显示在工具自身那一行下方;步骤从不新增行。步骤的 state 为 pending、running、done 或 failed,没有 state 的步骤视为正在运行。以相同 id(字符串或数字,或无 id 时相同的 label)再次报告的步骤会替换之前的内容,因此只有一个旋转指示器的工具可以保持同一 id 并只更改 label。没有 id 时,步骤依次衔接,新步骤会结束前一个。命令退出时,仍在运行的步骤会按命令的结果结束。
log 行承载工具以 JSON 包装的一行输出,并按普通输出文本读取。note 会输出到本次运行的输出中,带有 "level": "warn" 的那一条还会作为警告保留在环境上。最后一行类型为 error 时会成为结构化错误,并提供 command 供复制,其 message 下方会显示输出的最后 12 行。否则 Control Center 显示 stderr 的最后 20 行。非 JSON 内容都是普通日志输出。