-
Notifications
You must be signed in to change notification settings - Fork 4
Operator API Template Variables ru
Современные Clash-панели (Remnawave, Pasarguard, Marzban, Marzneshin, 3x-ui) позволяют админам писать шаблонные плейсхолдеры в кастомные response-заголовки. Панель подставляет их в момент запроса, до отправки ответа в ClashFest. С точки зрения клиента значение заголовка приходит как обычная строка — на стороне клиента нет движка подстановки, каждое X-Brand-* значение трактуется как финальный текст.
Это значит, что каждый заголовок этой спеки уже template-aware. Что ваша панель умеет интерполировать в строку — вы можете интерполировать в X-Brand-* заголовок.
Админ панели вводит в UI кастомных заголовков:
X-Brand-Tagline: Welcome {{USERNAME}}, {{DAYS_LEFT}} days remaining
Панель обрабатывает запрос подписки от юзера "vasya":
X-Brand-Tagline: Welcome vasya, 12 days remaining
ClashFest получает этот заголовок и рендерит его как есть.
Клиент никогда не видит {{USERNAME}}. Только vasya.
Имена переменных и семантика отличаются между панелями. Списки ниже отражают документацию на момент написания — если сомневаетесь, проверьте UI кастомных заголовков вашей панели или прогоните плейсхолдер по тестовой подписке и посмотрите ответ через
curl -I.
| Переменная | Что (вероятно) получите |
|---|---|
{{USERNAME}} |
Юзернейм из админки |
{{EMAIL}} |
Email юзера (если задан) |
{{TELEGRAM_ID}} |
Telegram ID юзера (если привязан) |
{{TAG}} |
Свободный user tag от админа — метка вроде "premium-2024" или "vip" |
{{STATUS}} |
Статус подписки (напр. active, expired) |
{{DAYS_LEFT}} |
Целое — дней до истечения |
{{TRAFFIC_USED}} / {{TRAFFIC_LEFT}} / {{TOTAL_TRAFFIC}}
|
Человекочитаемо (напр. 12.4GB) |
{{TRAFFIC_USED_BYTES}} / {{TRAFFIC_LEFT_BYTES}} / {{TOTAL_TRAFFIC_BYTES}}
|
Байты, integer |
{{EXPIRE_UNIX}} / {{CREATED_AT_UNIX}} / {{LAST_TRAFFIC_RESET_AT_UNIX}}
|
Unix epoch секунды |
{{RESET_STRATEGY}} |
Каденция сброса (daily, monthly, no_reset) |
{{SUBSCRIPTION_URL}} |
Сам URL подписки |
{{SHORT_UUID}} / {{ID}}
|
Короткий идентификатор / внутренний ID юзера |
{{SS_SUPPORT_LINK}} / {{SS_PROFILE_UPDATE_INTERVAL}} / {{SS_HWID_LIMIT}}
|
Панель-wide настройки |
| Переменная | Что (вероятно) получите |
|---|---|
{{PROFILE_TITLE}} |
Заголовок профиля |
{url} |
URL подписки (в этой панели — lowercase, одинарные скобки) |
{format} |
Формат подписки (clash, v2ray и т.д.) |
{{USERNAME}} / {{ADMIN_USERNAME}}
|
Юзернейм / юзернейм создавшего админа |
{{SERVER_IP}} / {{SERVER_IPV6}}
|
IP сервера |
{{DATA_USAGE}} / {{DATA_LEFT}} / {{DATA_LIMIT}}
|
Форматировано (12.4GB) |
{{USAGE_PERCENTAGE}} |
Процент использования (53%) |
{{DAYS_LEFT}} / {{TIME_LEFT}}
|
Дней / форматированное оставшееся время (12d 5h) |
{{EXPIRE_DATE}} / {{JALALI_EXPIRE_DATE}}
|
Дата (григорианская / джалали) |
{{STATUS_EMOJI}} |
Эмодзи статуса (✅ / ⛔ и т.д.) |
Эти панели обычно дают подмножество вышеперечисленного; частые имена — {USERNAME}, {DATA_LIMIT}, {DATA_USED}, {DAYS_LEFT}, {EXPIRE_DATE}. Смотрите секцию Custom Headers / Subscription Headers админки.
X-Brand-Help-URL: https://help.example.com/u/{{USERNAME}}
Тап по Help на Operator-табе открывает страницу помощи, преднастроенную под юзера.
X-Brand-Tagline: {{DAYS_LEFT}} days · {{DATA_LEFT}} left
Тэглайн становится живым индикатором прямо под именем бренда.
X-Brand-Greeting: Hi {{USERNAME}} — {{DAYS_LEFT}} days, {{DATA_LEFT}} left
X-Brand-Renew-URL: https://billing.example.com/renew?user={{USERNAME}}&token={{SHORT_UUID}}
Тап по critical-expiry чипу открывает биллинг уже нацеленным на запись юзера.
X-Brand-Support-URL: https://t.me/yoursupportbot?text=user%20{{USERNAME}}%20needs%20help
Telegram открывается с преднабранным сообщением, включающим имя юзера.
- ClashFest не парсит
{{...}}. Если заголовок пришёл с буквальным{{USERNAME}}(панель не подставила) — клиент покажет буквальный текст. Чините на стороне панели, не здесь. - Клиент также не знает юзернейм, email и т.д. Всё, что хотите показать, должно прийти уже подставленным в заголовке.
Каждое значение всё равно проходит валидаторы из Безопасности:
- Truncation по макс. длине (напр.
X-Brand-Nameмакс 32 символа ПОСЛЕ подстановки) - HTTPS-only для URL (никакой шаблон не протащит
http://) - Hex-regex для акцента + WCAG контраст-фильтр
- SSRF-guard на logo URL (шаблон не обойдёт отклонение приватных IP)
Так что враждебная / кривая подстановка не вырвется из существующего safety-конверта.
curl -I -H "User-Agent: ClashforAndroid" https://your-domain.example/sub/<token>Смотрите X-Brand-* заголовки. Видите буквальный {{...}} — подстановка не сработала, проверьте логи/конфиг панели. Видите правильное значение — ClashFest подхватит на следующем обновлении.
- Справочник заголовков — полная спека
- Быстрый старт — туториал по панелям
- Безопасность — правила валидации
📱 User Guide
- Getting Started
- Profiles & Nodes
- Routing & Rules
- Settings
- Deep Links
- Encrypted Subscriptions
- Troubleshooting
🏢 Operator API
📺 Companion