Перезагрузить сервер

POST /v1/infra/servers/:id/reboot

Перезагружает работающий сервер у облачного провайдера. На время перезагрузки сервер переходит в provisioning, туннель временно разрывается — blackholeStatus становится DISCONNECTED — и переподключается после старта виртуальной машины. Операция атомарная: внутренняя проверка на уровне базы предотвращает гонки, если одновременно пришло несколько вызовов. Если провайдер не поддерживает перезагрузку — возвращается 501 и статус откатывается на running.

Параметры

Тело запроса пустое.

Примеры

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

curl -X POST -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/reboot

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

curl -X POST -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/reboot

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

await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/reboot`,
  { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)

// Опрос готовности после перезагрузки
while (true) {
  await new Promise(r => setTimeout(r, 5000))
  const res = await fetch(
    `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}`,
    { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
  )
  const { data } = await res.json()
  if (data.status === 'running' && data.blackholeStatus === 'CONNECTED') break
}

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

await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/reboot`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)

Поля ответа

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

{ "success": true }

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

422 — сервер существует, но не в статусе running. В ответе — текущее состояние и доступные действия:

{
  "success": false,
  "error": {
    "code": "SERVER_WRONG_STATE",
    "message": "Server is SLEEPING; /reboot requires RUNNING.",
    "userMessage": "Server is currently SLEEPING. Reboot only applies to a RUNNING server.",
    "currentState": { "status": "sleeping", "blackholeStatus": "DISCONNECTED", "hasExternalId": true },
    "availableActions": ["wake", "start", "repair", "delete"]
  }
}

409 — статус сервера изменился во время операции (гонка):

{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "Server state changed during operation"
  }
}

Ошибки

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

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

• Атомарный переход running → provisioning. База обновляется одним updateMany с условием status = 'RUNNING'. Если в тот же момент прилетел ещё один /reboot или /stop, второй вызов получит 409 CONFLICT.
• Автоматический откат при ошибке провайдера. Если adapter.rebootServer() кинул исключение, запись возвращается к статусу running — чтобы клиент не остался с «зависшим» provisioning.
• Для перезапуска только приложения (без перезагрузки виртуальной машины) используйте POST /exec с командой systemctl restart app — это в десятки раз быстрее и не прерывает туннель.
• После перезагрузки ждите оба поля. Чтобы сервер был готов к работе, нужны одновременно status: "running" и blackholeStatus: "CONNECTED" — туннель переподключается после старта виртуальной машины.

Galaxy-приложения (kind=GALAXY_APP)

Для приложения-контейнера в галактике (kind=GALAXY_APP — у него нет собственной виртуальной машины) /reboot перезапускает контейнер на хосте, а не перезагружает ВМ. Это «пинок» самовосстановления для зависшего или крашащегося приложения: он не стирает постоянный том /data (в отличие от удаления).

Перезапуск совещательный (advisory) — он не меняет статус записи и не снимает маркер краша. После рестарта контейнер проверяется, и в ответе возвращается вердикт healthy: запустился ли контейнер и перестал ли он перезапускаться. Это проверка состояния контейнера (docker inspect), а не HTTP-ответа приложения. Крашащееся приложение авторитетно чинится редеплоем исходников через POST /v1/infra/servers/:id/deploy — именно редеплой сбрасывает состояние ошибки.

Приложение принимает /reboot в статусе running или error (обычному серверу нужен только running).

Поля ответа

Вердикт приходит вложенным в data (в отличие от перезагрузки обычного сервера, где тело — плоское { "success": true }).

{ "success": true, "data": { "restarted": true, "healthy": false, "hint": "Redeploy the fixed source via POST /v1/infra/servers/:id/deploy" } }

Ошибки

Отказ приложению попутно чинит хост

У galaxy-приложения, чей хост потерял связь с платформой, любая операция упирается в один и тот же барьер: и пробуждение, и деплой идут через хост, а хост недостижим. Поэтому перед отказом 422 SERVER_WRONG_STATE платформа запускает восстановление связи с хостом в фоне — сам отказ этим не отменяется, но следующая попытка имеет шанс пройти.

Если восстановление действительно началось, в теле ошибки появляется необязательный объект hint:

Объекта hint может не быть — и это не ошибка. Он отсутствует, когда восстановление не запускалось: связь с хостом на самом деле жива, починка уже идёт или недавно завершилась, хост сам выключен или спит, его недавно будили, гостевая система на машине не стартует, машина закрыта для пробуждения либо автоматическое восстановление отключено на платформе. Читайте hint как необязательную подсказку: есть — подождите названное время и повторите деплой, нет — действуйте по коду ошибки.

Повторные вызовы новую починку не запускают. Пока починка идёт и ещё 10 минут после того, как она закончилась — успешно или нет, — платформа новую не начинает, поэтому повторный отказ придёт уже без hint. Это то же десятиминутное окно, что и время жизни завершённой записи в Статусе восстановления. Починку, которая оборвалась и перестала подавать признаки жизни, платформа считает мёртвой через 20 минут и разрешает начать заново.

Значение retryAfterSeconds равно 300 и остаётся нижней границей ожидания, а не обещанием готовности: раньше повторять смысла нет, позже — можно.

У отказа 502 GALAXY_HOST_UNREACHABLE объект hint другой — четыре поля вместо трёх, с собственным набором значений. Состав описан в разделе «Поле error.hint у GALAXY_HOST_UNREACHABLE» страницы Galaxy-приложение. Форму подсказки задаёт код отказа, поэтому разбирайте её по коду, а не по странице, на которой отказ встретился.

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

• Запустить сервер
• Остановить сервер
• Восстановить туннель
• Выполнить команду