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

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

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

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

## Параметры

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

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

## Примеры

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

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

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

```bash
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 | Код | Описание |
|------|-----|----------|
| 400 | `INVALID_INPUT` | У записи нет облачной виртуальной машины: создание не завершилось, машина удалена у провайдера — тогда удалите сервер и создайте новый. Тот же код отвечает galaxy-приложению: у контейнера своей машины нет, ремонт к нему не применяется — [Galaxy-приложение](/docs/infra/galaxy) |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Неверный или просроченный API-ключ |
| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | Вызов сделан ключом Cowork/Code — такой ключ работает только с данными, изменяющие операции ему закрыты. Что делать — [Проектный ключ для деплоя](/docs/cowork/deploy-key) |
| 404 | `NOT_FOUND` | Сервер не существует, удалён или принадлежит другому API-ключу |
| 409 | `REPAIR_BLOCKED` | Ремонт заблокирован: `preventWake=true` (биллинговая заморозка, административный блок) или сервер в особом состоянии |
| 422 | `GUEST_NOT_BOOTING` | Гостевая операционная система машины не загружается. Ремонт этого не лечит, поэтому вызов отклоняется до обращения к машине и не будит её — сервер нужно пересоздать |
| 429 | `RATE_LIMITED` | Превышен общий лимит запросов платформы |

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

- **Почему serial console, а не SSH.** Когда агент не подключён, SSH через iptables BLACKHOLE-сервера недоступен. Serial console провайдера Bitrix Cloud минует файрвол на уровне гипервизора и позволяет внедрить SSH-ключ в уже работающую виртуальную машину, не перезагружая её.
- **Два пути установки агента.** По умолчанию агент доустанавливается по входящему SSH — это быстро. Если входящий SSH недоступен (порт 22 не отвечает, IP в базе устарел, правила облачного файрвола, sshd не поднят), процедура устанавливает агента out-of-band через ту же serial console: агенту нужен только ИСХОДЯЩИЙ коннект к gateway, поэтому входящий доступ для переустановки не требуется. У машины без публичного IP используется сразу serial console. Резервная попытка добавляет до двух минут к уже неуспешному вызову; если не сработали оба пути, `error` в [`GET /repair-status`](./repair-status.md) содержит обе причины через `; serial fallback:`.
- **Идемпотентно.** Процедура выполняет полный цикл (стоп агента → скачивание свежего бинарника → чистая конфигурация → запуск) и безопасна для здорового сервера — навредить не может. Повторный вызов во время идущего ремонта просто вернёт 409/то же `started`, ничего не ломает.
- **Режим сервера сохраняется.** OPEN-сервер остаётся OPEN (iptables не трогается), BLACKHOLE — BLACKHOLE.
- **Как разблокировать `REPAIR_BLOCKED`.** Если сервер помечен `preventWake` (биллинговая заморозка, истёкший trial, админблок) — сначала устраните причину (пополните баланс, обновите тариф), потом повторите `/repair`.
- **`GUEST_NOT_BOOTING` ремонтом не лечится.** Признак виден заранее в поле `provisionErrorCode` карточки сервера — [`GET /v1/infra/servers/:id`](/docs/infra/servers/get). Прочитайте его перед вызовом: у такой машины ремонт отклоняется, а единственное доступное действие — удалить сервер и создать новый.

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

- [Статус ремонта](./repair-status.md)
- [Обновить статус](./refresh.md)
- [Получить сервер](/docs/infra/servers/get)
- [Перезагрузить сервер](./reboot.md)