#Задать порт приложения

PATCH /v1/infra/servers/:id/port

Задаёт TCP-порт, на который агент туннеля проксирует входящие HTTPS-запросы с субдомена. По умолчанию туннель идёт на :3000 — это стандарт платформы, большинство приложений должны слушать именно его. Этот эндпоинт нужен в редких случаях: приложение по историческим причинам работает на другом порту или вы хотите 0 (авто-определение), чтобы агент сам нашёл слушающий порт. Порты 1–1023 запрещены — это системные (SSH, HTTP, HTTPS, SQL), их использование создало бы риск перенаправления трафика на служебные процессы.

#Параметры

Параметр В Тип Обяз. Описание
id path string (UUID) да ID BLACKHOLE-сервера, status: running, blackholeStatus: CONNECTED

#Поля запроса (body)

Поле Тип Обяз. Описание
port number да 0 (авто-определение) или 1024–65535. Порты 1–1023 отклоняются с PORT_RESTRICTED

#Примеры

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

Terminal 
# Установить порт 8080
curl -X PATCH https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/port \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"port": 8080}'

# Автоматическое определение
curl -X PATCH https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/port \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"port": 0}'

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

Terminal 
curl -X PATCH https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/port \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"port": 8080}'

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

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/port`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ port: 8080 }),
  }
)
const { data } = await res.json()
console.log(`Порт приложения: ${data.port}`)

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

javascript 
await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/port`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ port: 0 }),
  }
)

#Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.port number Итоговый порт. При port: 0 вернётся 3000 (значение по умолчанию при автоопределении)

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

JSON 
{
  "success": true,
  "data": { "port": 8080 }
}

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

400 — системный порт запрещён:

JSON 
{
  "success": false,
  "error": {
    "code": "PORT_RESTRICTED",
    "message": "System ports (1-1023) are not allowed. Use port >= 1024 or 0 for auto-detect"
  }
}

#Ошибки

HTTP Код Описание
400 VALIDATION_ERROR port не число, вне диапазона 0–65535
400 PORT_RESTRICTED Порт в диапазоне 1–1023 (системные порты)
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 INVALID_API_KEY Неверный или просроченный API-ключ
404 NOT_FOUND Сервер не BLACKHOLE + RUNNING, удалён или принадлежит другому API-ключу
409 SERVER_NOT_READY Агент туннеля не в статусе CONNECTED
429 RATE_LIMIT_EXCEEDED Превышен общий лимит запросов платформы
502 GATEWAY_ERROR Gateway не смог доставить команду агенту

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

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

  • Системные порты (1–1023) запрещены не случайно. SSH (22), HTTP (80), HTTPS (443), DNS (53), PostgreSQL (5432), MySQL (3306) — открытие туннеля на них создало бы риск перенаправления внешнего трафика на служебные процессы внутри виртуальной машины.
  • Как работает port: 0. Агент сканирует /proc/net/tcp и /proc/net/tcp6, находит процесс, слушающий на прикладном порту (≥1024), и проксирует туда. Полезно для приложений, выбирающих порт динамически при запуске.
  • Значение сохраняется между перезапусками агента. Платформа пишет localPort в базу сервера — после `/repair` или перезагрузки агент возьмёт то же значение. При /deploy с явным port значение перезапишется.
  • port: 0 в ответе возвращается как 3000. Это не ошибка: «при автоопределении возвращаем 3000, если ничего подходящего не нашли». Реальный слушающий порт проверяйте через `/exec` с командой ss -tlnp.

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