Принудительно освободить канал

POST /v1/infra/servers/:id/unstick

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

Используйте восстановление для подтверждённой утечки синхронного exec-мьютекса после независимого подтверждения простоя сервера. Прежде чем действовать при EXEC_BUSY, прочитайте операции сервера с kind=exec и их исходы. Эта ручка не отменяет независимые длительные задачи отдельной машины и не снимает их ограничение приёма, в том числе с force=true. При подтверждённой синхронной утечке соблюдайте Retry-After, если он есть, затем используйте эту гардированную ручку; безусловное удаление лока идёт последним, после проверки простоя. На STANDALONE работающая длительная задача занимает канал после освобождения платформенного лока с 202. Опрашивайте её операцию; при неизвестном исходе нужны поддержка и независимое подтверждение полной остановки. Отсутствие autoExpiresInSeconds не доказывает утечку мьютекса. Восстановление туннеля и удаление лока не снимают ограничение приёма длительной задачи. В Galaxy команды выполняются синхронно с пределом 600 секунд и общим каналом для всех приложений и выкладок; задача соседнего приложения может не попасть в ваш список операций, поэтому пустой список не доказывает простой хоста.

Параметры

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

Примеры

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

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

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/unstick

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

const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/unstick`,
  { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
const body = await res.json()
if (!body.success) {
  console.error(body.error.code, body.error.message)
} else if (!body.data.reconnected) {
  console.log('Агент ещё переподключается — прочитайте предыдущую операцию до повтора')
}

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

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

Чтобы обойти проверку блокировки операции, отправьте тот же запрос с ?force=true в строке запроса. Это может прервать синхронное выполнение; независимую длительную задачу отдельной машины и её ограничение приёма параметр не отменяет.

Поля ответа

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

{
  "success": true,
  "data": {
    "backendLockReleased": true,
    "agentBounced": true,
    "reconnected": true
  }
}

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

404 — сервер не найден:

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

Ошибки

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

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

• Проверка блокировки действует на момент запроса. Общая блокировка операции держит отказ, но не любая: если запись держателя пережила свой срок и это была команда (op: exec), вызов проходит — канал сбрасывается, туннель перетряхивается, ответ 200. У выкладки такая же протухшая запись отказ не снимает: законная выкладка живёт дольше своего TTL. Проверка не резервирует канал: операция может начаться после неё, а при недоступности базы некоторые операции могут работать без общей блокировки. Отсутствие отказа не гарантирует, что работающих команд нет.

• Что происходит с зависшей синхронной командой. Разрыв туннеля заставляет агента завершить процесс-группу зависшей синхронной команды и подключиться заново. Сервис приложения при этом не перезапускается, файлы на диске не меняются, переустановки агента не происходит — в отличие от Восстановить туннель, который переустанавливает агента целиком. Длительные задачи отдельной машины выполняются независимо; переподключение не доказывает их остановку и не снимает ограничение приёма.

• Освобождение канала не будит спящий сервер. Если сервер в статусе sleeping или у него стоит запрет пробуждения, туннеля нет и разрывать нечего: платформа снимает серверную блокировку и отвечает успехом с agentBounced: false.

• Окно ожидания переподключения короткое и не влияет на исход. Платформа наблюдает за туннелем несколько секунд после разрыва и отвечает, не дожидаясь дольше. Агент подключается сам, поэтому reconnected: false означает «ещё не увидели», а не «не вернулся» — прочитайте исход предыдущей операции перед решением о повторе.

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

• Выполнение команд
• Снять зависший лок
• Восстановить туннель
• Полный деплой