#Восстановить туннель

POST /v1/infra/servers/:id/repair

Запускает фоновое восстановление туннеля Black Hole через serial console облачного провайдера. Используйте, когда виртуальная машина в running, но blackholeStatus застрял в DISCONNECTED или WAITING — то есть агент туннеля не подключается. Процедура проходит через serial console (минуя файрвол) и включает: впрыск SSH-ключа → SSH-подключение → полную переустановку агента с актуальной версией → ожидание переподключения. Длится до 2 минут; сам вызов возвращается сразу и не ждёт завершения, прогресс смотрите через `GET /repair-status`.

#Параметры

Параметр В Тип Обяз. Описание
id path string (UUID) да ID сервера

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

#Примеры

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

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

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

Terminal 
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/repair

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

javascript 
// Запустить ремонт и периодически опрашивать статус
await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/repair`,
  { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)

while (true) {
  await new Promise(r => setTimeout(r, 10000))
  const res = await fetch(
    `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/repair-status`,
    { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
  )
  const { data } = await res.json()
  console.log(`Шаг: ${data.step ?? data.status}`)
  if (data.status === 'idle' || data.status === 'completed' || data.status === 'failed') break
}

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

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

#Поля ответа

Поле Тип Описание
success boolean true — ремонт успешно запущен в фоне
data.status string Всегда "started" при успехе

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

JSON 
{
  "success": true,
  "data": { "status": "started" }
}

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

409 — ремонт заблокирован (например, сервер помечен preventWake=true):

JSON 
{
  "success": false,
  "error": {
    "code": "REPAIR_BLOCKED",
    "message": "Repair blocked: server prevents wake"
  }
}

#Ошибки

HTTP Код Описание
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 INVALID_API_KEY Неверный или просроченный API-ключ
404 NOT_FOUND Сервер не существует, удалён или принадлежит другому API-ключу
409 REPAIR_BLOCKED Ремонт заблокирован: preventWake=true (биллинговая заморозка, административный блок) или сервер в особом состоянии
422 VM_MISSING У записи нет externalId — виртуальная машина не создана у провайдера. Удалите сервер и создайте новый
429 RATE_LIMIT_EXCEEDED Превышен общий лимит запросов платформы

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

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

  • Почему serial console, а не SSH. Когда агент не подключён, SSH через iptables BLACKHOLE-сервера недоступен. Serial console провайдера Yandex Cloud минует файрвол на уровне гипервизора и позволяет внедрить SSH-ключ в уже работающую виртуальную машину, не перезагружая её.
  • Идемпотентно. Процедура выполняет полный цикл (стоп агента → скачивание свежего бинарника → чистая конфигурация → запуск) и безопасна для здорового сервера — навредить не может. Повторный вызов во время идущего ремонта просто вернёт 409/то же started, ничего не ломает.
  • Режим сервера сохраняется. OPEN-сервер остаётся OPEN (iptables не трогается), BLACKHOLE — BLACKHOLE.
  • Как разблокировать REPAIR_BLOCKED. Если сервер помечен preventWake (биллинговая заморозка, истёкший trial, админблок) — сначала устраните причину (пополните баланс, обновите тариф), потом повторите /repair.

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