Перейти к содержимому

Настройка окружений

Окружение — это работающий стек одного пространства: сервисы, нужные ветке, изолированные от всех других пространств, видимые на боковой панели и доступные агентам. Оно есть и у пул-реквестов, потому что у PR уже есть собственное пространство.

Администратор рабочего пространства один раз пишет определение. После этого участники нажимают Запустить в разделе Окружение боковой панели пространства или PR. Определения хранятся в базе данных рабочего пространства, поэтому ветка с новой функцией никогда не меняет то, что запускает Control Center, хотя инструменты по-прежнему выполняют код этой ветки.

  1. Откройте Настройки → Рабочее пространство → Окружения. Менять определения могут только администраторы рабочего пространства, а сохранить определение, которое работает на хосте сервера, может только владелец сервера (см. Кто что может сохранять).
  2. Нажмите Новое определение, затем Пустое определение или Черновик из репозитория. Черновик ищет в репозитории файлы compose, Procfile и скрипты package.json, а результат вы проверяете сами.
  3. Заполните форму или используйте вкладку JSON. Примеры на этой странице показывают этот JSON.
  4. Нажмите Запустить тест. Запустится одноразовое окружение; Control Center дождётся готовности и уничтожит его.

Сохранение строго проверяет определение. Неизвестное поле, значение неверного типа или неправильно написанный вариант отклоняется с указанием пути и ближайшего допустимого имени, например repos.app.requird: Unknown field. Did you mean "required"?. Верхнеуровневое $schema допускается.

Чтобы хранить определение в репозитории, используйте Связать файл репозитория. Control Center читает файл только из ветки по умолчанию и запускает только ту версию, которая одобрена: администратором рабочего пространства или, если определение работает на хосте, владельцем сервера. Более новая версия показывает Доступно обновление и ничего не меняет до одобрения.

Определение окружения может запускать команды на хосте сервера от имени собственного пользователя сервера. Это решение владельца сервера, а не роли в рабочем пространстве:

  • Определение работает на хосте, если у него размещение на хосте, проверка, которая запускает команду, или задача provision либо archive. Эти задачи выполняются в worktree пространства на хосте независимо от размещения.
  • Только владелец сервера может сохранить или одобрить определение, которое работает на хосте. Сюда входит одобрение новой версии связанного файла репозитория. Администратор рабочего пространства, который попытается это сделать, увидит «Только владелец сервера может сохранять или одобрять окружение, которое работает на хосте сервера. Администратор рабочего пространства может использовать окружение, которое работает в риге.»
  • Администратор рабочего пространства может сохранять и одобрять определение, которое работает целиком в риге: "placement": "rig", без команды проверки и без задач provision или archive.
  • Участники в любом случае запускают, останавливают и используют окружения.
  • Определение, которое работает на хосте, запускается только после того, как его сохранил или одобрил текущий владелец сервера. Сервер сам записывает это одобрение и проверяет его перед каждым запуском, проверкой, задачей и синхронизацией головы пул-реквеста. Определение, которое текущий владелец не одобрил, например сохранённое предыдущим владельцем, ждёт под своей строкой в списке окружений и в редакторе. Владелец сервера видит «Запускается на этом сервере. Одобрите, чтобы оно могло стартовать.» с кнопкой Одобрить, которая сохраняет определение без изменений; все остальные видят «Запускается на этом сервере. Владелец сервера должен его одобрить, прежде чем оно сможет стартовать.»
  • Окружение, которое ждёт этого одобрения, показывает «Владелец сервера ещё не одобрил это окружение, поэтому оно не может работать на этом сервере.» Владелец сервера вместо этого видит «Вы ещё не одобрили это окружение. Оно работает на этом сервере, поэтому запустится, когда вы одобрите его определение.» с кнопкой Проверить и одобрить, которая открывает определение.
  • Терминалы процессов окружения и терминал, который открывается при запуске, если нужен ваш ответ, работают на хосте сервера. Для ввода в такой терминал, изменения его размера или закрытия нужен доступ на запись к каждому репозиторию, который открывает пространство и который читается через ваш собственный вход в хост кода: то же, что нужно для запуска окружения. Никто другой не может добраться до этих терминалов вовсе.

Простому репозиторию с compose нужно только это:

{
"contract": 1,
"name": "Shop",
"repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } },
"components": [ { "kind": "compose", "id": "stack" } ]
}

У всего остального есть значения по умолчанию: файл compose находится сам, запускаются все сервисы, назначаются порты, определяются конечные точки HTTP, а окружение получает имя ветки.

Окружение — это упорядоченный список компонентов. Каждый ждёт готовности предыдущего, если after не называет другие, а остановка идёт в обратном порядке. enabledWhen ставит компонент в зависимость от параметра или роли, например opt.seed, !opt.seed или repo.web. Компонент, роль которого необязательна и не входит в пространство, пропускается точно так же и без enabledWhen: он не запускается и не имеет {port.*} и {url.*}, поэтому другой компонент, который их читает, приводит к ошибке запуска.

Вид Кто запускает Для чего
compose Драйвер compose в Control Center Любой файл compose, один на окружение
cli Ваш инструмент. Control Center вызывает назначенные глаголы и читает JSON Инструмент, который сам владеет жизненным циклом, доменами и данными
process Control Center в контролируемом сеансе терминала Серверы разработки и воркеры
task Control Center, один раз на триггер Установка, миграции, тесты
app Control Center, когда кто-то нажимает Открыть Настольное приложение

Компоненты task принимают список when:

Триггер Когда выполняется
provision При создании worktree (см. задачи worktree ниже)
create Один раз на окружение и снова после сброса
start При каждом запуске
change После синхронизации, если изменённый путь совпадает с onChange
manual По запросу: Выполнить, cc-env run <id> или environment_run_task
archive Непосредственно перед уничтожением worktree

Задача, которой при запуске нечего делать, показывает Простой и не попадает в список шагов, выводимый при запуске окружения: задача manual или change, либо задача create, которая уже выполнилась.

Команда в виде массива — это argv, поэтому значения параметров никогда не проходят через оболочку. Строка или script с массивом строк выполняются в bash -lc. Заполнители вроде {name}, {branch}, {stateDir}, {repo.<role>}, {port.<key>}, {opt.<key>} и {url.<role>} раскрываются только в argv. Команды оболочки читают те же значения из переменных CC_ENV_*, например $CC_ENV_PORT_WEB. Неизвестный заполнитель в компоненте, который участвует в окружении, останавливает запуск до выполнения чего-либо.

Каждая команда и терминал пространства также получают CC_ENV_NAME, CC_ENV_STATE_DIR, CC_ENV_URL, CC_SPACE_ID, CC_ENV_REPO_<ROLE>, а в пространствах PR ещё CC_PR_NUMBER и CC_PR_IS_FORK. С компонентом compose они получают и COMPOSE_PROJECT_NAME с COMPOSE_FILE, поэтому docker compose exec в задаче попадает в нужный проект.

Определение привязывает роли к репозиториям рабочего пространства, поэтому один стек может охватывать несколько репозиториев:

"repos": {
"api": { "repoId": "<api>", "anchor": true, "required": true },
"web": { "repoId": "<web>", "anchor": true },
"e2e": { "repoId": "<e2e>", "whenMissing": "useSource" }
}
  • anchor: пространство может запустить окружение, если в нём есть хотя бы одна якорная роль. Если подходят два определения, выбирает тот, кто запускает.
  • required: без этого репозитория стек не работает.
  • whenMissing: что делать, если в пространстве нет этой роли. addToSpace добавляет репозиторий на ветке по умолчанию и является значением по умолчанию для ролей required. useSource передаёт вашу зарегистрированную копию, с которой нужно обращаться как с доступной только для чтения. skip оставляет переменную незаданной и применяется по умолчанию в остальных случаях.
  • Для запуска нужны право write на якорный репозиторий в пространстве и доступ на чтение ко всем остальным привязанным репозиториям.

Команда выполняется в первой роли, объявленной в repos, а не в другой роли, которая случайно есть в пространстве, поэтому в определении с одним репозиторием об этом можно не упоминать. Любой компонент может изменить это с помощью "cwd": { "role": "e2e", "path": "packages/ui" }. Оба поля необязательны. Если первая роль может отсутствовать в пространстве, потому что она не required и не единственный якорь, каждый компонент должен указывать свою роль.

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 на маршрутизаторе сервера, который слушает один порт loopback:

http://<endpoint>--<name>--<project>.localhost:<router port>
http://web--fix-login--shop.localhost:7355
  • <name> — ветка в виде слага или pr-<n> в пространстве PR. <project> — это naming.project, а иначе имя определения.
  • Имена *.localhost указывают на loopback, поэтому им не нужны записи hosts и DNS, а имя хоста разделяет cookie между окружениями.
  • Порты compose, отвечающие по HTTP, определяются автоматически, а http в компоненте заменяет это предположение. Процессу нужен "endpoint": { "role": "web", "primary": true }, который также делает доступным {url.web}.
  • В браузере (ВМ) используйте Открыть в 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 синхронизирует окружение PR при сдвиге его head, а при maxRunning (по умолчанию 6) кнопка Запустить предлагает остановить давно не использовавшееся окружение.

Веб-приложение и Postgres из одного файла compose, с игнорируемым git файлом .env, миграциями и задачей тестов. seedFiles копирует указанные файлы из вашей зарегистрированной копии в каждый новый worktree.

{
"contract": 1,
"name": "Shop",
"repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } },
"naming": { "project": "shop" },
"seedFiles": [".env"],
"components": [
{ "kind": "compose", "id": "stack",
"services": ["postgres", "web"],
"healthchecks": { "postgres": ["pg_isready", "-U", "postgres"] } },
{ "kind": "task", "id": "migrate", "when": ["create", "change"],
"onChange": ["db/migrations/**"],
"command": "docker compose exec -T web bin/migrate" },
{ "kind": "task", "id": "test", "when": ["manual"],
"command": "docker compose exec -T web bin/test" }
]
}

healthchecks позволяет сервису без собственной проверки работоспособности задержать следующий компонент. Без неё запущенный контейнер считается готовым, и миграции могут обогнать базу данных, которая ещё запускается.

Каждый запуск и обновление выполняют up с --remove-orphans, поэтому сервис, удалённый из compose-файла, останавливается и освобождает свой порт. Образы собираются при запуске и обновлении, если компонент не задаёт "build": false.

Вымышленный инструмент 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. Вывод, который нельзя прочитать как список, ничего не меняет.
  • {service} в logs и exec должен быть одним словом, не начинающимся с -, и одним из сервисов, о которых инструмент сообщил в последний раз, когда вообще сообщал.
  • statusMap читает собственный JSON инструмента с помощью указателей JSON, где * соответствует каждому элементу. Правила состояния упорядочены, и побеждает первое совпадение. Условие — это path с equals либо any или none с where.
  • keepsDataOnStop: false отключает остановку при простое и добавляет к Остановить предупреждение о потере данных. Задавайте его, если остановка теряет данные.
  • routing.mode: "tool" подключает имена хостов инструмента к браузеру (ВМ) и агентам. Домен должен оканчиваться на .test, .localhost или .internal, а сообщённый URL вне его отбрасывается.

Ваш собственный инструмент может обойтись без statusMap и выводить контракт статуса, описанный в конце этой страницы.

Только процессы и задачи, без контейнеров. Веб-приложение находит API через {url.api}.

{
"contract": 1,
"name": "Monorepo",
"repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } },
"naming": { "project": "mono" },
"options": [ { "key": "seed", "type": "bool", "default": true, "agentDefault": false } ],
"components": [
{ "kind": "task", "id": "install", "when": ["provision", "change"],
"onChange": ["pnpm-lock.yaml"],
"command": ["pnpm", "install", "--frozen-lockfile"] },
{ "kind": "process", "id": "api", "label": "API", "port": "api",
"cwd": { "path": "apps/api" },
"command": ["pnpm", "dev"],
"endpoint": { "role": "api" },
"ready": { "http": "http://127.0.0.1:{port.api}/health", "timeout": 120 },
"restartOn": ["pnpm-lock.yaml"] },
{ "kind": "task", "id": "seed", "when": ["create"], "enabledWhen": "opt.seed",
"cwd": { "path": "apps/api" },
"command": ["pnpm", "db:seed"] },
{ "kind": "process", "id": "web", "label": "Dev server", "port": "web",
"cwd": { "path": "apps/web" },
"env": { "API_URL": "{url.api}" },
"command": ["pnpm", "dev", "--port", "{port.web}", "--host", "127.0.0.1"],
"endpoint": { "role": "web", "primary": true },
"ready": { "http": "http://127.0.0.1:{port.web}/" } },
{ "kind": "task", "id": "lint", "when": ["manual"], "command": ["pnpm", "lint"] }
]
}
  • Каждый процесс — это вкладка терминала, которую можно открыть, читать и в которой можно печатать, если у вас есть доступ на запись ко всем репозиториям пространства (см. Кто что может сохранять). Закрытие вкладки его не останавливает.
  • ready принимает http (полный URL), tcp (host:port) или logMatch (регулярное выражение). restart принимает on-failure (по умолчанию), always или never. restartOn перезапускает процесс при совпадении изменённого пути.
  • options превращаются в форму у Запустить, а agentDefault применяется к запускам агентом.

Настольное приложение с шагом сборки. Приложение работает одинаково, на чём бы оно ни было написано, потому что Control Center работает на уровне окон ОС и не требует хуков или 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 разрешения Запись экрана и Универсальный доступ в Системных настройках. На хосте сервера нужен графический сеанс: сервер без GUI отказывается запускать приложение.
  • Запускайте бинарный файл напрямую. open -a передаёт приложение LaunchServices, и оно покидает дерево процессов, которое отслеживает Control Center, поэтому приложение сразу после запуска отображается как сбойное.
  • Окна остаются на дисплее. macOS не захватывает окно за пределами всех дисплеев, поэтому приложение, с которым работает агент, видно на экране сервера. Фокус ему не нужен.
  • "isolate": "home" даёт приложению приватный домашний каталог через HOME, XDG_* и CFFIXED_USER_HOME, чтобы копии из двух пространств работали рядом. NSUserDefaults не изолируется, поэтому настройки Cocoa и shared_preferences во Flutter остаются общими для копий.
  • isolate действует только на запущенный процесс. Лаунчеру инструментов вроде flutter run нужен настоящий домашний каталог, поэтому сочетайте isolate с собранным бинарным файлом. Если у приложения есть своя настройка, например --user-data-dir, лучше использовать её.
  • Агенты управляют окном через app_use, которому доступно только дерево процессов этого окружения. Агент видит окно, а не рабочий стол. Запуски агентами проходят через политику действий и по умолчанию требуют подтверждения, а ввод агента останавливается, пока управление у человека.
  • "input": "background" (по умолчанию) отправляет события процессу. "foreground" активирует окно и перехватывает курсор.

Задачи provision и archive выполняют настройку и очистку репозитория вместе с его worktree. Значок в строке репозитория в Настройки → Рабочее пространство → Репозитории открывает определение этого репозитория.

Эти задачи следуют за worktree, а не за окружением, поэтому выполняются и в пространствах, где никто не нажимает Запустить:

provision archive
Выполняется При создании worktree роли в любом пространстве Непосредственно перед уничтожением этого worktree
При сбое Подготовка завершается ошибкой, и worktree уничтожается Записывается, никогда не блокирует удаление
Тайм-аут по умолчанию 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"] также переустанавливает зависимости при изменении lock-файла.
  • Задача выполняется для worktree своей роли cwd, поэтому определение с несколькими репозиториями может настраивать каждый отдельно.
  • Тестовый запуск задаёт CC_SCRIPT_TEST=1. Повторная попытка начинается с чистого worktree, поэтому пишите задачи, которые переживут повторный запуск.

Агенты никогда не получают сокет Docker. В пространстве с подходящим определением запуск получает cc-env в своём PATH. Пространство берётся из запуска, поэтому агент может действовать только в своём окружении, а каждая команда проходит через политику действий.

Окно терминала
cc-env status
cc-env up
cc-env down
cc-env reset
cc-env destroy
cc-env restart <process>
cc-env logs <name>
cc-env exec <service> -- <cmd>
cc-env run <task> -- <args>

С компонентом compose шим docker также разрешает 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».

Репозиторий, чьи навыки вызывают его собственный инструмент, может делать это и дальше. Блок agentPassthrough в компоненте cli объявляет, какие команды могут выполнять агенты. Проходят только команды, объявленные одобренным определением, и каждая из них выполняется на хосте, поэтому на неё распространяется правило Выполнение команд на хосте, которое по умолчанию спрашивает сначала:

"agentPassthrough": {
"binary": "acme",
"allow": [
{ "argv": ["env", "ls"], "maps": "status", "nameFilter": true },
{ "argv": ["env", "status|url"], "maps": "status", "positionalName": 2 },
{ "argv": ["env", "create"], "maps": "up", "positionalName": 2,
"pathFlags": ["--web-dir"], "denyFlags": ["--force"] },
{ "argv": ["env", "logs"], "maps": "logs", "positionalName": 2,
"denyFlags": ["--follow"] }
]
}

maps называет операцию, чья политика применяется. positionalName принудительно подставляет в этот аргумент окружение этого пространства, nameFilter фильтрует по нему вывод JSON, а каждое значение pathFlags должно разрешаться внутри worktree запуска. Команда, не подошедшая ни под одно правило, завершается с кодом 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 выполняется в ВМ без запроса Определений только с компонентами compose и task
approval Каждый запуск требует администратора Всех остальных определений
deny Отказ Никаких
  • seedFiles никогда не копируются для форка, потому что обычно это секреты. Файл compose, который монтирует такой файл, сообщает об отсутствующем файле по имени.
  • Задачи provision и archive пропускаются, кроме случая, когда политика равна rig: тогда они выполняются в ВМ.
  • При размещении на хосте для форка отклоняются privileged, пространства имён хоста, монтирование сокета Docker, devices и монтирования вне worktree пространства. В доверенных пространствах они дают только предупреждение.

"placement": "rig" выполняет компоненты compose и task в выделенной microVM. Определения с компонентами process, cli или app не подходят. Файл compose выполняется без изменений, без сокета Docker хоста и учётных данных оператора, а доступ к сети ограничен реестрами, нужными его образам. Worktree монтируется вживую.

  • Гостевые системы arm64. На Apple Silicon гостевые системы работают на arm64, поэтому образы только для amd64 не запустятся.
  • Частные реестры отклоняются. У гостевых систем нет учётных данных реестров, поэтому образ из реестра вне известных публичных отклоняется до загрузки ВМ. Частный репозиторий в публичном реестре завершится ошибкой при скачивании гостем.
  • 16 ГиБ хранилища. Все образы и тома стека делят один диск на 16 ГиБ, и увеличить его нельзя.
  • Первая загрузка медленная. Слои образов у каждой ВМ свои, поэтому первая загрузка скачивает всё. Остановленный rig сохраняет свой диск.
  • Базовые образы должны быть читаемы. Dockerfile, называющий базовый образ через переменную, нельзя спланировать, потому что доступ к сети фиксируется при загрузке.
  • Время жизни. policy.rigTtlHours завершает ВМ, по умолчанию через 24 часа.

Контракт статуса для авторов инструментов

Заголовок раздела «Контракт статуса для авторов инструментов»

Компонент cli без statusMap ожидает нативный контракт cc-env/1. Глагол status выводит этот объект в stdout:

{
"state": "ready",
"detail": "migrations applied, HTTP 200",
"endpoints": [
{ "role": "app", "label": "App", "url": "https://fix-login.acme.test", "primary": true },
{ "role": "postgres", "label": "Postgres", "hostPort": 49213 }
],
"services": ["server", "postgres"],
"needsRecreate": false,
"error": { "code": "post-start-failed", "message": "…", "hint": "…", "command": "…" }
}
  • state принимает значения ready, starting, stopped, failed или missing. missing приводит к create, а stopped и failed приводят к start. Сообщайте missing с кодом выхода 0: неудачный status считается failed.
  • Обязателен только state. Неизвестные поля игнорируются, а вывод, который нельзя разобрать, отображается как деградировавший, с исходным текстом в деталях.
  • URL должен быть loopback, *.localhost или находиться под routing.domain, иначе он отбрасывается.
  • needsRecreate: true показывает Пересоздать, что удаляет данные. Control Center никогда не действует по этому флагу сам.
  • Глагол list выводит массив JSON из имён или объектов с name.

Коды выхода действуют для всех глаголов:

Код Значение
0 ОК
3 Нужен ответ в терминале, например пароль sudo. Глагол, перечисленный в interactive, снова запускается во вкладке терминала для человека, нажавшего Запустить. Иначе Выполнить в терминале открывает терминал пространства с введённой, но не выполненной командой command инструмента, затем Повторить пробует снова. Control Center никогда не выполняет sudo и не отвечает на запрос
4 Требуется вход. Команда command инструмента указывает, как
5 Недоступно то, от чего он зависит, например не запущена среда выполнения контейнеров
Другой Сбой

Коды 3, 4 и 5 не являются сбоями. Окружение показывает Нужны ваши действия и ждёт, а следующий запуск продолжает с того места, где остановился предыдущий. Задача, которая завершается с одним из этих кодов, означает то же самое.

Ход выполнения идёт в stderr как JSON с разделением по строкам:

{"type":"step","id":"images","label":"Pull images","state":"running"}
{"type":"log","stream":"stdout","line":"postgres Pulled"}
{"type":"step","id":"images","label":"Pulled 4 images","state":"done"}
{"type":"note","level":"warn","message":"Hosts entries stayed behind after destroy"}
{"type":"error","code":"hosts-missing","message":"Add the hosts entry","hint":"Needs sudo","command":"sudo acme hosts add fix-login"}

Пока окружение запускается, панель показывает компоненты, через которые проходит запуск, каждый с индикатором вращения, галочкой или крестиком. Строка step говорит, что инструмент делает сейчас, а её label показывается под строкой самого инструмента; шаги никогда не добавляют строк. Поле state шага имеет значение pending, running, done или failed, а шаг без state считается выполняющимся. Шаг, который сообщает снова под тем же id (строкой или числом, либо тем же label, если его нет), заменяет то, что сообщал раньше, поэтому инструмент с одним индикатором может сохранить один id и менять label. Без id шаги идут друг за другом: новый завершает предыдущий. Когда команда завершается, шаг, который ещё выполняется, завершается так же, как команда.

Строка log содержит одну строку вывода, которую инструмент упаковал в JSON, и читается как обычный вывод. Строка note попадает в вывод запуска, а строка с "level": "warn" также остаётся в окружении как предупреждение. Последняя строка типа error становится структурированной ошибкой, command предлагается скопировать, а последние 12 строк вывода показываются под её message. Без неё Control Center показывает последние 20 строк stderr. Всё, что не JSON, считается обычным журналом.