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

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

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

Это не способ снять EXEC_BUSY. /repair — полная переустановка агента туннеля: живые процессы, запущенные через `/exec`, при этом прерываются вместе с их побочными эффектами (например, открытая транзакция COPY во внешней базе повиснет и будет держать блокировки до таймаута на её стороне). Если сервер отвечает 409 EXEC_BUSY, снимите лок вызовом `DELETE /v1/infra/servers/:id/lock` — агент и запущенные процессы при этом не затрагиваются. /repair оставьте для случая по назначению: туннель действительно не подключается.

#Параметры

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

#Примеры

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

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

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

#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-приложение

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": true,
  "data": { "status": "started" }
}

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

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

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

#Ошибки

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

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

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

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

• Статус ремонта — GET /v1/infra/servers/:id/repair-status — прогресс текущей операции.
• Обновить статус — проверить, поправился ли blackholeStatus после ремонта.
• Получить сервер — проверить blackholeStatus и status.
• Перезагрузить сервер — альтернатива, если repair не помог.

#Статус восстановления

GET /v1/infra/servers/:id/repair-status

Возвращает прогресс фонового восстановления туннеля, запущенного через `POST /repair`. Используется для периодического опроса: клиент видит текущий шаг (wake / serial_console / ssh_install / connect / …), финальный статус (running / done / failed) и в случае ошибки — поле error. Завершённые записи автоматически очищаются через 10 минут.

#Параметры

#Примеры

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

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

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

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

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

// Цикл опроса прогресса
while (true) {
  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()

  if (data.status === 'idle') { console.log('Ремонт не запущен'); break }
  if (data.status === 'done')  { console.log(`Готово, шаг: ${data.step}`); break }
  if (data.status === 'failed'){ console.error(`Ошибка на шаге ${data.step}: ${data.error}`); break }

  console.log(`Шаг: ${data.step}`)
  await new Promise(r => setTimeout(r, 10000))
}

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

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

#Поля ответа

Для status: "idle" возвращается только поле status, остальные поля отсутствуют.

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

Ремонт не запускался:

{
  "success": true,
  "data": {
    "status": "idle"
  }
}

Ремонт идёт, завершён шаг установки агента:

{
  "success": true,
  "data": {
    "status": "running",
    "step": "connect",
    "agentVersion": "1.2.3",
    "wasSlept": false,
    "startedAt": 1745312400000
  }
}

Ремонт провалился:

{
  "success": true,
  "data": {
    "status": "failed",
    "step": "ssh_install",
    "agentVersion": null,
    "wasSlept": false,
    "error": "SSH connection refused",
    "startedAt": 1745312400000
  }
}

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

404 — сервер не существует:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Server not found"
  }
}

#Ошибки

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

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

• Порядок выполнения шагов: wake (если сервер в sleeping) → serial_console (впрыск SSH-ключа через serial console Bitrix Cloud) → ssh_install (SSH-подключение и переустановка агента: скачивание бинаря, запись конфигурации, запуск сервиса) → connect (ожидание подключения агента к Gateway) → iptables (восстановление файрвола для BLACKHOLE) → cleanup (возвращение в sleeping, если сервер был спящим) → done.
• Сразу после `POST /repair` статус уже running, не idle. Статус выставляется в running синхронно при старте ремонта, поэтому первый же опрос repair-status (даже спустя миллисекунды) видит running. Раньше был короткий промежуток, где опрос мог увидеть idle и цикл опроса завершался преждевременно — теперь этого окна нет.
• TTL завершённых записей — 10 минут. После этого повторный опрос вернёт idle. Если нужно подтвердить результат после TTL, смотрите на blackholeStatus в `GET /v1/infra/servers/:id` — если он CONNECTED, ремонт сработал.
• Одновременный ремонт невозможен — на уровне сервиса стоит замок в памяти repairingServers. Повторный `POST /repair` на сервере с уже идущим ремонтом корректно обрабатывается: второй вызов не запускает новую процедуру.

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

• Восстановить туннель — POST /v1/infra/servers/:id/repair — запуск ремонта.
• Получить сервер — проверить итоговый blackholeStatus.
• Обновить статус — принудительно опросить провайдера после ремонта.