Operator API ru

ClashFest Operator API

🌐 English · Русский · 中文

Спецификация для VPN-операторов: кастомизировать Android-клиент ClashFest, который вы поставляете своим пользователям — брендинг, ссылки поддержки, пер-юзер контекст, поведение по умолчанию — всё через HTTP-заголовки ответа на URL подписки.

Статус: draft (v1 в разработке). Этот документ — источник истины на время проектирования и реализации. Статус реализации по каждому заголовку — в Справочнике заголовков (v1 / v2 / v3 / proposed).

Что это

Каждый раз, когда клиент ClashFest забирает ваш URL подписки, он читает набор HTTP-заголовков ответа, описывающих:

• Идентичность бренда — имя, лого (тёмный + светлый варианты), тэглайн, акцентный цвет
• Инфо оператора — сайт, поддержка / telegram / bot, privacy / terms / help, статус, продление
• Пер-юзер контекст — уже покрыт profile-title (свободная форма, контролируется панелью)
• Упрощение UX — скрыть вкладку Routing для юзеров
• Политика подписки — политика share-link, HWID-энфорсмент, max devices
• Анонсы — broadcast-сообщения с опциональными URL

Клиент трактует всё это как подсказки оператора — никогда не доверяет слепо. Каждое значение проходит валидацию (макс. длина, формат, whitelist URL, лимиты размера изображений, защита от SSRF). См. Безопасность.

Почему заголовки, а не JSON-эндпоинт?

• Работает с существующим URL подписки — никаких доп. эндпоинтов и состояния авторизации
• Каждая Clash-совместимая панель (Pasarguard / Marzban / Marzneshin / Remnawave / 3x-ui / X-UI) уже поддерживает кастомные response-заголовки на роутах подписки — ваша команда добавляет значения, клиент читает
• Тривиально проксируется / кэшируется
• Forward-compatible: клиенты, не понимающие заголовок, просто его игнорируют

Именование заголовков

Все ClashFest-специфичные заголовки используют префикс X-Brand-*.

Часть заголовков остаётся под их конвенциональными V2Ray / Clash-совместимыми именами (profile-title, Subscription-Userinfo, announce, share-links, x-hwid-*), т.к. они уже широко поддерживаются панелями. Мы расширяем их, а не переименовываем.

Заголовки матчатся регистронезависимо.

Быстрый пример

Ответ подписки может выглядеть так:

HTTP/1.1 200 OK
Content-Type: application/x-clash
Subscription-Userinfo: upload=1234; download=5678; total=107374182400; expire=1735689600

profile-title: vasya@example.com — Premium

X-Branding-Enabled: true
X-Brand-Name: SwiftVPN
X-Brand-Tagline: Fast and private since 2024
X-Brand-Logo-URL: https://swiftvpn.example.com/static/logo-dark-256.png
X-Brand-Logo-Light-URL: https://swiftvpn.example.com/static/logo-light-256.png
X-Brand-Accent-Color: #5E35B1

X-Brand-Cabinet-URL: https://t.me/<bot>?startapp={{SHORT_UUID}}
X-Brand-Website-URL: https://swiftvpn.example.com
X-Brand-Support-URL: https://t.me/swiftvpn_support
X-Brand-Telegram-URL: https://t.me/swiftvpn_news
X-Brand-Bot-URL: https://t.me/swiftvpn_bot
X-Brand-Privacy-URL: https://swiftvpn.example.com/privacy
X-Brand-Terms-URL: https://swiftvpn.example.com/terms
X-Brand-Help-URL: https://swiftvpn.example.com/help
X-Brand-Renew-URL: https://swiftvpn.example.com/billing

announce: New servers added in Frankfurt and Amsterdam.
announce-url: https://swiftvpn.example.com/news/2026-05

После того как ClashFest это прочитает:

• Хедер главного экрана показывает SwiftVPN с лого оператора слева, а не «ClashFest» — светлый/тёмный вариант лого под текущую тему
• Основной акцентный цвет по всему UI — #5E35B1 (если прошёл контраст-фильтр — см. Безопасность)
• Экран About показывает «SwiftVPN — powered by ClashFest» со ссылками Website / Privacy / Terms / Help / Telegram / Bot
• Карточка профиля показывает имя подписки «vasya@example.com — Premium» (свободный title, контролируемый оператором)
• Строка анонса показывает сообщение оператора и ведёт на страницу новостей
• Когда до конца подписки <3 дней, существующий critical-expiry чип становится тапабельным → открывает Renew URL; пункт «Renew» также появляется в меню профиля

Документы

• Справочник заголовков — полный справочник каждого заголовка: тип, пример, семантика, правила валидации, фолбэк, статус реализации.
• Шаблонные переменные — как переменные панели ({{USERNAME}}, {{DAYS_LEFT}} и т.д.) попадают в бренд-заголовки, с шпаргалками по панелям и практическими рецептами.
• Безопасность — что валидирует клиент, threat model, защита SSRF, лимиты размера изображений.
• Быстрый старт — пошаговая настройка на Pasarguard / Marzban / Remnawave / 3x-ui.

Для разработчиков панелей

Если вы ведёте панель и хотите первоклассную поддержку бренда ClashFest, быстрейший путь:

1. Прочитайте Справочник заголовков и выберите нужное подмножество (большинство начинают с X-Brand-Name + X-Brand-Logo-URL + X-Brand-Accent-Color)
2. Добавьте в админку UI, чтобы оператор настраивал эти значения
3. Отдавайте их в каждом HTTP-ответе подписки

Большинство современных панелей уже поддерживают фичу «custom headers» — операторы могут вставить заголовки списком без изменений в панели.

Лицензия

Спека намеренно пермиссивна — внедряйте, зеркальте, форкайте, расширяйте. Если построите что-то поверх — ссылка на этот репо приветствуется, но не обязательна.