#Galaxy-приложение

Galaxy-приложение — это отдельное приложение Black Hole, которое живёт в контейнере на общем хосте — галактике — вместе с другими такими же приложениями. Каждое приложение получает свой HTTPS-субдомен и изоляцию, как у отдельной виртуальной машины, но все они делят одну галактику — это кратно дешевле, чем держать отдельный сервер под каждое приложение. Если администратор портала включил размещение в галактиках, тот же вызов POST /v1/infra/servers создаёт galaxy-приложение, а не виртуальную машину.

Скоуп: vibe:infra · Базовый URL: https://vibecode.bitrix24.tech/v1 · Авторизация: заголовок X-Api-Key

#Кто выбирает модель размещения

Режим размещения выбирает администратор портала в кабинете на странице «Галактики», в разделе «Размещение». Обычный участник портала видит режим только для чтения, а вызывающий API его не задаёт. Один и тот же запрос POST /v1/infra/servers создаёт либо отдельную виртуальную машину, либо galaxy-приложение, в зависимости от режима портала. Параметра «создать именно galaxy-приложение» в запросе нет.

Режим портала — один из трёх:

• Сначала галактика (galaxies-only) — новые приложения размещаются плотно внутри галактик. Если приложение перерастает свой контейнер, его переносят на отдельный сервер Black Hole.
• Гибридный (both) — приложение попадает в галактику, когда в ней есть место, иначе разворачивается на отдельной виртуальной машине.
• Отдельные серверы (standalone-only) — галактики не используются, каждое приложение получает свою виртуальную машину.

Что с этим делать вызывающему:

• Определяйте модель по ответу, а не задавайте её. Признак galaxy-приложения — поле createdVia равно galaxy в ответе создания. Полный список признаков — в разделе «Как отличить galaxy-приложение в ответе» ниже.
• Нужна именно отдельная виртуальная машина — запросите её явно. Если портал размещает приложения в галактиках, но конкретному приложению нужен выделенный сервер, передайте в теле `POST /v1/infra/servers` поле placement равным dedicated — платформа создаст отдельную виртуальную машину вместо galaxy-приложения. По умолчанию placement равен auto, и применяется настройка портала.

Готовность у моделей разная:

• Отдельная виртуальная машина — по status: "running" и blackholeStatus: "CONNECTED".
• Galaxy-приложение — только через загрузку кода, ожидание CONNECTED здесь не работает (см. «Жизненный цикл» ниже).

#Как отличить galaxy-приложение в ответе

У galaxy-приложения нет своего SSH-доступа (ssh равно null), публичного IP-адреса и внешнего идентификатора виртуальной машины — у контейнера их нет. Поля region и plan в ответе — это регион и тариф галактики-носителя: переданные при создании значения ни на что не влияют, размещение платформа выбирает сама.

#Жизненный цикл — сборка при загрузке кода

Galaxy-приложение никогда само не доходит до blackholeStatus: "CONNECTED". Его контейнер и агент туннеля создаёт сама загрузка кода — отдельного шага провижининга, как у виртуальной машины, здесь нет.

Из этого следует главное правило: загружайте код сразу после создания, не дожидаясь CONNECTED. Если создать galaxy-приложение и просто опрашивать статус, оно останется в provisioning, а примерно через 20 минут платформа пометит его как error и запишет в поле provisionError, что код так и не был загружен.

#Создание и загрузка кода

Создание идёт тем же вызовом `POST /v1/infra/servers`. Код загружают одним из двух сценариев.

• Сценарий 1 — одним запросом. Передайте код в поле source вместе с runtime и start прямо в POST /v1/infra/servers. Сборка пойдёт в фоновом режиме, отдельный вызов загрузки не нужен.
• Сценарий 2 — в два шага. Создайте приложение без source, получите в ответе next: "deploy", затем загрузите код через `POST /v1/infra/servers/:id/deploy`. Создание без source требует provider/plan/region (для galaxy они информационны — см. пример в create.md).

Полные тела запросов, поля и примеры для обоих сценариев — на странице Создать сервер.

Создание galaxy-приложения по сценарию 1 — source передан, сборка идёт в фоне. Признак модели — createdVia равно galaxy:

{
  "success": true,
  "data": {
    "id": "7c2b1f08-3a4d-4e91-9b6c-2f5e8a1d0c33",
    "status": "provisioning",
    "name": "my-crm-app",
    "kind": "GALAXY_APP",
    "galaxyId": "<galaxy-host-id>",
    "ssh": null,
    "ip": null,
    "plan": "bc-medium",
    "region": "ru-central1-a",
    "mode": "BLACKHOLE",
    "createdVia": "galaxy",
    "subdomain": "app-7c2b1f08",
    "blackholeStatus": "NONE",
    "appUrl": "https://app-7c2b1f08.vibecode.bitrix24.tech",
    "createdAt": "2026-04-22T10:50:11.477Z"
  }
}

#Деплой

Деплой galaxy-приложения отличается от деплоя виртуальной машины. Полный контракт — на странице Деплой приложения.

• Источник кода — только встроенный source.content (архив в base64). Варианты source.url и source.versionId отклоняются с 400 GALAXY_DEPLOY_CONTENT_ONLY.
• Поля runtime и start обязательны. Без runtime запрос вернёт 400 GALAXY_DEPLOY_RUNTIME_REQUIRED. Список рантаймов — `GET /v1/infra/runtimes`.
• Свой Dockerfile класть не нужно — платформа генерирует его из полей runtime, port и start.
• Переменные env подставляются в контейнер при запуске, а не вшиваются в образ, поэтому секреты не попадают в слои образа.
• Рабочая директория контейнера — /opt/app, путь /app тоже ведёт на неё как ссылка. Постоянные данные сохраняйте в томе /data.

#Стоимость

Стоимость считается за галактику, а не за каждое приложение. Несколько galaxy-приложений в одной галактике делят её стоимость — пять приложений на тарифе bc-small обходятся примерно как одна галактика, а не как пять серверов. В лимит серверов на API-ключ (GET /v1/me → infra.limits.used) galaxy-приложения не входят — он считает только отдельные виртуальные машины.

#Логи

Для galaxy-приложения `GET /v1/infra/servers/:id/logs` возвращает поток вывода самого контейнера (stdout и stderr), а не системный журнал галактики. Чтение логов не будит спящую галактику. Если галактика спит или недоступна, ответ — пустой массив data.logs плюс диагностическое поле data.hint. Параметр since для galaxy-приложения принимает только длительность (10m, 2h, 24h) или метку времени в формате RFC 3339 (например, 2026-04-22T10:50:11Z).

#Удаление

Galaxy-приложение снимается тем же вызовом `DELETE /v1/infra/servers/:id` — платформа разбирает его контейнер в галактике и помечает запись удалённой. Спящую галактику платформа будит сама перед удалением. Галактика с работающими приложениями этим вызовом не удаляется — сначала снимите её приложения.

#Коды ошибок

Полный справочник общих ошибок API — Ошибки.

#Смотрите также

• Создать сервер
• Деплой приложения
• Логи сервера
• Удалить сервер
• Инфраструктура