Admin API: proxy-серверы и Cloudflare

Через API доступны те же действия, что и в разделе панели Proxy-серверы: добавить ноду, проверить её, удалить, подключить и отключить аккаунт Cloudflare. Все методы требуют токен с доступом Полный доступ (full). Авторизация описана на странице Admin API: обзор и авторизация, формат запросов и ошибок — на странице Формат запросов, ответов и ошибок.

Общие правила

• Записи принадлежат команде: токен видит и меняет только ноды и аккаунты своей команды.
• Метода изменения нет ни у ноды, ни у аккаунта Cloudflare. Чтобы поменять параметры, удалите запись и создайте новую.
• Постраничности и фильтров в списках нет.
• Пароль SSH и токен Cloudflare принимаются только при создании. Ни один метод их не возвращает.
• Если в адресе вместо {id} передано значение, которое не является UUID, ответ — 400 с кодом bad_request и сообщением некорректный идентификатор или значение.
• При неактивной лицензии методы отвечают 402 — см. Истёкшая лицензия.

Направление доменов на ноду — отдельные методы POST /api/v1/domains/{id}/route и POST /api/v1/domains/route-bulk, они описаны на странице Admin API: домены.

Proxy-серверы

Объект ноды

Значения status:

Список нод

GET /api/v1/proxy-nodes

Возвращает все ноды команды.

Права токена: full. Параметров нет.

Ответ — код 200 и массив объектов ноды. Новые ноды идут первыми. Если нод нет, приходит пустой массив [].

[
  {
    "id": "5d2f8c14-9a3b-4e7d-b1c6-0f8e7d6c5b4a",
    "workspace_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "label": "DE-1",
    "ip": "203.0.113.10",
    "ssh_port": 22,
    "ssh_user": "root",
    "status": "ready",
    "last_seen": "2026-10-04T09:15:42.118204Z",
    "created_at": "2026-10-04T09:14:10.552871Z",
    "host_key_fingerprint": "SHA256:Zk3v0q1mYb7Qe2xL9aHn4TtR8sWc5uJd6oPfGiK1lMw"
  }
]

Добавить ноду

POST /api/v1/proxy-nodes

Создаёт ноду и запускает её настройку по SSH. Требования к серверу — на странице Proxy-серверы.

Права токена: full. Тело — JSON-объект:

Ответ — код 201:

Настройка идёт в фоне, на неё отводится до 3 минут. Ответ приходит сразу и результата настройки не содержит. Запрашивайте список нод и ждите, пока status сменится на ready или error. После ready подождите около минуты: сервер трекера сам начнёт принимать запросы с этой ноды.

Ошибки:

Ошибки самой настройки — неверный пароль, недоступный сервер, несовпадение отпечатка — в ответ не попадают. Они записываются в last_error ноды со статусом error. Тексты разобраны на странице Proxy-серверы.

Пример запроса:

curl -X POST https://panel.example.com/api/v1/proxy-nodes \
  -H "Api-Key: <токен>" \
  -H "Content-Type: application/json" \
  -d '{"label":"DE-1","ip":"203.0.113.10","ssh_port":22,"ssh_user":"root","ssh_password":"<пароль SSH>"}'

Проверить ноду

POST /api/v1/proxy-nodes/{id}/health

Подключается к ноде по SSH с сохранённым ключом и проверяет, что веб-сервер на ней запущен. Проверка длится до 25 секунд.

Права токена: full. Тела запроса нет. В адресе {id} — ID ноды из списка.

Ответ — код 200 в обоих случаях, результат в поле status:

{"status": "ready"}

При успехе обновляется last_seen ноды, её status становится ready, а last_error очищается. При неудаче текст ошибки с пометкой ручная проверка: записывается в last_error, а status самой ноды не меняется. Автоматический контроль нод и перенос доменов описаны на странице Proxy-серверы.

Ошибки:

Пример запроса:

curl -X POST https://panel.example.com/api/v1/proxy-nodes/5d2f8c14-9a3b-4e7d-b1c6-0f8e7d6c5b4a/health \
  -H "Api-Key: <токен>"

Удалить ноду

DELETE /api/v1/proxy-nodes/{id}

Удаляет ноду из трекера и снимает привязку её доменов.

Права токена: full. Тела запроса нет. В адресе {id} — ID ноды из списка.

Ответ — код 204 без тела.

Если ноды с таким ID нет или она уже удалена, ответ — 404 с кодом not_found.

Аккаунты Cloudflare

Аккаунт — сохранённый API-токен Cloudflare. Через него трекер ставит A-запись домена на IP ноды. Какие права нужны токену и что трекер делает в DNS — на странице Работа с Cloudflare.

Объект аккаунта

Список аккаунтов

GET /api/v1/cf-accounts

Возвращает подключённые аккаунты Cloudflare команды без токенов.

Права токена: full. Параметров нет.

Ответ — код 200 и массив объектов аккаунта в порядке добавления. Если аккаунтов нет, приходит пустой массив [].

Подключить аккаунт

POST /api/v1/cf-accounts

Проверяет токен Cloudflare запросом списка зон и сохраняет его.

Права токена: full. Тело — JSON-объект:

Ответ — код 201:

Ошибки:

Пример запроса:

curl -X POST https://panel.example.com/api/v1/cf-accounts \
  -H "Api-Key: <токен>" \
  -H "Content-Type: application/json" \
  -d '{"label":"Основной аккаунт","token":"<API-токен Cloudflare>"}'

Отключить аккаунт

DELETE /api/v1/cf-accounts/{id}

Удаляет сохранённый токен Cloudflare.

Права токена: full. Тела запроса нет. В адресе {id} — ID аккаунта из списка.

Ответ — код 204 без тела. DNS-записи в Cloudflare не меняются. Домены этого аккаунта трекер больше не сможет направлять на ноды.

Если аккаунта с таким ID нет или он уже удалён, ответ — 404 с кодом not_found.

Когда функция выключена

Код 503 с code = disabled означает, что на сервере трекера не заданы параметры proxy-серверов: NODE_ENC_KEY или NODE_ORIGIN_HOST. Установщик записывает оба параметра сам, поэтому на установке, развёрнутой по странице Установка, этот ответ не появляется.

При добавлении ноды текст в message зависит от того, какого параметра нет:

• фича прокси-нод выключена: задайте NODE_ENC_KEY (openssl rand -hex 32);
• NODE_ORIGIN_HOST не задан (адрес origin для нод).

Списки и удаление работают и без этих параметров: GET и DELETE ответ disabled не возвращают.