Документация API панели
Цель
Показать назначение раздела API Docs в 3x-ui и объяснить, как безопасно подходить к автоматизации панели.
Теория
API Docs описывает HTTP API панели: endpoints, параметры запросов, ответы и сценарии автоматизации. API удобен для интеграций, но по уровню риска близок к административному интерфейсу.
История
Панельный API нужен, когда ручной UI становится узким местом: массовое создание клиентов, интеграция с биллингом, аудит, self-service или внешняя система управления. Чем больше автоматизации, тем выше требования к контролю доступа и журналированию.
Архитектура
API связан с:
| Слой | Риск |
|---|---|
| Auth/session | захват токена дает административный доступ |
| Inbounds API | можно создать или сломать публичные входы |
| Clients API | можно выдать, изменить или отозвать доступ |
| Settings API | можно изменить безопасность панели |
| Xray API/JSON | можно нарушить работу Xray |
Настройка
Перед использованием API:
1. Проверить, что доступ к панели ограничен. 2. Определить минимальный сценарий автоматизации. 3. Не хранить токены в коде репозитория. 4. Логировать операции без публикации секретов. 5. Тестировать на стенде до production.
Разбор параметров
В API Docs нужно смотреть:
| Элемент | Что проверить |
|---|---|
| Method | GET/POST/PUT/DELETE и последствия |
| Endpoint | какая сущность меняется |
| Request body | обязательные поля и секреты |
| Response | как понять успех и ошибку |
| Auth | как передается сессия или токен |
| Error codes | как автоматизация должна реагировать |
Типовые ошибки
- использовать API с публичного IP без ограничений;
- хранить cookie/token в скриптах открытым текстом;
- запускать массовые операции без dry run;
- не проверять response и считать запрос успешным;
- не делать backup перед автоматизированными изменениями.
Безопасность
API должен рассматриваться как административный доступ. Минимум: ограничение источников, защищенное хранение токенов, audit log, ротация секретов, отдельная учетная запись или сценарий доступа, если версия панели это поддерживает, и запрет на публикацию request examples с реальными секретами.
Чек-лист
- API доступен только доверенным источникам.
- Секреты не хранятся в репозитории.
- Массовые операции тестируются на стенде.
- Ответы API проверяются программно.
- Перед изменениями делается backup.