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

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

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

#Параметры

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

#Примеры

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

# Установить порт 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-приложение

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 — личный ключ

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

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": true,
  "data": { "port": 8080, "mode": "manual", "verified": true }
}

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

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

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

409 — агент отклонил смену порта (фиксированный порт / устаревший бинарь):

{
  "success": false,
  "error": {
    "code": "PORT_NOT_APPLIED",
    "message": "The server agent runs in fixed-port mode and cannot change its port at runtime. Repair the server (POST /v1/infra/servers/:id/repair) to switch the agent to port auto-detection, then retry.",
    "agentError": "NO_SCANNER"
  }
}

#Ошибки

Полный список общих ошибок 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.
• Платформа подтверждает смену порта (data.verified). После set_port платформа опрашивает агента и проверяет, что туннель действительно проксирует на запрошенный порт. verified: true — маршрутизация готова. verified: false + data.warning — порт сохранён, но агент ещё не подтвердил порт (автоопределение сработает в течение ~30 с). Если приложение остаётся недоступным дольше — `/repair`. 409 PORT_NOT_APPLIED — агент в принципе не принял смену порта: при agentError: NO_SCANNER сервер работает в режиме фиксированного порта (запустите приложение на текущем порту, либо /repair для перехода в автоопределение), при ином agentError — агент устарел (/repair обновит его).

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

• Полный деплой — поле port в /deploy также конфигурирует туннель.
• Метрики туннеля — есть ли HTTP-соединения и lastRequestAt.
• Выполнить команду — ss -tlnp для проверки слушающих портов.