Для AI-агентов: markdown этой страницы — /docs-content/infra/database/prepare-status.md индекс документации — /llms.txt

Получить статус подготовки хоста

GET /v1/infra/servers/:id/app-db/prepare

Возвращает состояние подготовки хоста галактики для работы с базой приложения: каких компонентов не хватает и на каком шаге идёт установка. Запрос только читает состояние и подготовку не запускает.

Параметры

Параметр Тип Обяз. Описание
Параметрid (path) Типstring (UUID) Обяз.да ОписаниеID приложения с kind равным GALAXY_APP. Список: GET /v1/infra/servers

Параметры строки запроса не принимаются: любой отклоняется с 400 VALIDATION_ERROR.

Примеры

curl — личный ключ

Terminal 
curl "https://vibecode.bitrix24.tech/v1/infra/servers/APP_ID/app-db/prepare" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

Terminal 
curl "https://vibecode.bitrix24.tech/v1/infra/servers/APP_ID/app-db/prepare" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — личный ключ

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${appId}/app-db/prepare`,
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
const { success, data, error } = await res.json()
if (!success) throw new Error(error.code)
console.log(data.state, data.missing)

JavaScript — OAuth-приложение

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${appId}/app-db/prepare`,
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)
const { success, data, error } = await res.json()

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue при успешном чтении состояния
Полеdata.state Типstring Описаниеnot_prepared — компонентов не хватает, подготовка не идёт. preparing — подготовка идёт. ready — все компоненты на месте. failed — последняя подготовка завершилась ошибкой, причина в data.errorCode
Полеdata.steps Типarray ОписаниеСемь шагов в фиксированном порядке: disk, python3, zstd, age, curl, image, verify
Полеdata.steps[].id Типstring ОписаниеШаг: disk — проверка свободного места и пакетного менеджера, python3, zstd, age, curl — установка пакета, image — загрузка служебного образа для чтения базы, verify — итоговая проверка
Полеdata.steps[].state Типstring Описаниеpending — шаг не начат, running — выполняется, done — выполнен, present — компонент уже был на хосте, failed — шаг завершился ошибкой
Полеdata.missing Типstring[] ОписаниеКомпоненты, которых сейчас нет на хосте: python3, zstd, age, curl, image. При ready массив пуст
Полеdata.errorCode Типstring ОписаниеТолько при failed: LOW_DISK, DPKG_BROKEN, APT_PLAN_UNSAFE, APT_FAILED, PULL_FAILED, VERIFY_FAILED или UNSUPPORTED_HOST. Что делать с каждым кодом — в разделе «Известные особенности»
Полеdata.freeBytes Типinteger ОписаниеМеньшее из свободного места на корневом разделе и на разделе образов Docker, в байтах. Приходит при preparing и failed, если замер был

Пример ответа

Подготовка не запускалась, на хосте не хватает только служебного образа:

JSON 
{
  "success": true,
  "data": {
    "state": "not_prepared",
    "steps": [
      { "id": "disk", "state": "pending" },
      { "id": "python3", "state": "present" },
      { "id": "zstd", "state": "present" },
      { "id": "age", "state": "present" },
      { "id": "curl", "state": "present" },
      { "id": "image", "state": "pending" },
      { "id": "verify", "state": "pending" }
    ],
    "missing": ["image"]
  }
}

Хост подготовлен:

JSON 
{
  "success": true,
  "data": {
    "state": "ready",
    "steps": [
      { "id": "disk", "state": "done" },
      { "id": "python3", "state": "present" },
      { "id": "zstd", "state": "present" },
      { "id": "age", "state": "present" },
      { "id": "curl", "state": "present" },
      { "id": "image", "state": "present" },
      { "id": "verify", "state": "done" }
    ],
    "missing": []
  }
}

Пример ответа при ошибке

400 — в запросе передан параметр строки запроса, а эндпоинт параметров не принимает:

JSON 
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid preparation parameters"
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодVALIDATION_ERROR ОписаниеПередан параметр строки запроса
HTTP400 КодAPP_DB_UNSUPPORTED_PLACEMENT ОписаниеПриложение размещено не в Галактике
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key
HTTP401 КодINVALID_API_KEY ОписаниеКлюч не опознан
HTTP402 КодBILLING_FROZEN ОписаниеХост галактики спит, а счёт портала заморожен: разбудить хост нельзя
HTTP403 КодINFRA_SCOPE_REQUIRED ОписаниеУ ключа нет скоупа vibe:infra
HTTP403 КодAPP_DB_DISABLED ОписаниеРабота с базой приложения не включена для портала
HTTP403 КодSERVER_WAKE_BLOCKED ОписаниеХост галактики спит, а его пробуждение запрещено
HTTP404 КодNOT_FOUND ОписаниеПриложение или его хост не найдены, удалены или недоступны этому ключу
HTTP409 КодAPP_DB_BUSY ОписаниеХост не успел проснуться за 10 секунд или занят другой операцией. Повторите после паузы из Retry-After
HTTP429 КодRATE_LIMITED ОписаниеПревышен лимит запросов на чтение для портала — Лимиты. Пауза — в заголовке Retry-After
HTTP503 КодAPP_DB_TOOL_UNAVAILABLE ОписаниеСлужебный канал к хосту недоступен, или хост вернул некорректное состояние. Повторите после паузы из Retry-After
HTTP503 Кодuser_self_deletion_pending ОписаниеВладелец ключа удаляет свой аккаунт на портале

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

Известные особенности

Запуск — отдельным вызовом. При not_prepared и failed подготовку запускает POST /app-db/prepare по тому же адресу.

Опрос будит спящий хост — см. Когда база доступна.

Как опрашивать. После запуска подготовки опрашивайте этот адрес раз в 3 секунды, а при 409, 429 и 503 выдерживайте паузу из Retry-After, если она длиннее. При ready перечитайте базу, при failed остановите опрос и покажите причину из data.errorCode. not_prepared во время опроса означает, что подготовка не идёт: остановите опрос и запустите её снова. В интерфейсе приостанавливайте опрос, пока вкладка скрыта, а при смене приложения или закрытии экрана отменяйте запросы.

Что делать при failed. Повторный запуск пропускает уже установленные компоненты.

  • LOW_DISK — на корневом разделе или разделе образов Docker меньше 6 ГиБ свободного места. Освободите место в данных приложений или обратитесь в поддержку.
  • DPKG_BROKEN — пакетный менеджер хоста в неисправном состоянии. Обратитесь в поддержку.
  • APT_PLAN_UNSAFE — установка потребовала бы обновить или удалить уже установленные пакеты, и платформа её остановила. Обратитесь в поддержку.
  • UNSUPPORTED_HOST — на хосте не Ubuntu 24.04 или нет нужных системных утилит. Обратитесь в поддержку.
  • APT_FAILED, PULL_FAILED, VERIFY_FAILED — не удалось установить пакет, загрузить служебный образ или пройти итоговую проверку. Повторите POST /app-db/prepare.

Цикл ожидания готовности (готовый пример):

javascript 
async function waitForPreparation(url, headers, signal) {
  while (!signal.aborted) {
    const response = await fetch(url, { headers, signal })
    const retry = Number(response.headers.get('Retry-After'))
    const waitMs = Math.max(3000, Number.isFinite(retry) ? retry * 1000 : 0)
    if (response.ok) {
      const { data } = await response.json()
      // ready, failed и not_prepared — конечные для опроса состояния
      if (data.state !== 'preparing') return data
    } else if (![409, 429, 503].includes(response.status)) {
      throw new Error(`HTTP ${response.status}`)
    }
    await new Promise((resolve, reject) => {
      const cancel = () => {
        clearTimeout(timer)
        reject(signal.reason)
      }
      const timer = setTimeout(() => {
        signal.removeEventListener('abort', cancel)
        resolve()
      }, waitMs)
      signal.addEventListener('abort', cancel, { once: true })
    })
  }
  throw signal.reason
}

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