PasarGuard
Панель

Руководство по настройкам

Полная документация по настройке системных параметров PasarGuard

Содержание

  1. Настройки Telegram-бота
  2. Настройки Webhook
  3. Настройки уведомлений
  4. Включение уведомлений (детальный контроль)
  5. Настройки подписки (Самый важный раздел)
  6. Общие настройки
  7. Полный пример конфигурации

1. Настройки Telegram-бота

Настройка Telegram-бота для управления панелью администратора и взаимодействия с пользователями.

Поля

ПолеТипОбязательноеПо умолчаниюОписание
enablebooleanДаfalseВключить/выключить функциональность Telegram-бота
tokenstringПри включенииnullТокен бота от @BotFather
webhook_urlstringДля метода webhooknullПубличный HTTPS URL для webhook-эндпоинта
webhook_secretstringДля метода webhooknullСекретный токен для безопасности webhook
proxy_urlstringНетnullURL SOCKS5/HTTP прокси (формат: protocol://host:port)
methodstringНет"webhook"Метод подключения: "webhook" или "long-polling"
mini_app_loginbooleanНетtrueВключить функцию входа через Telegram Mini App
mini_app_web_urlstringНет""URL веб-интерфейса Mini App
for_admins_onlybooleanНетtrueОграничить доступ к боту только для администраторов

Важные примечания

Требуется Inline Mode

Чтобы включить функцию поиска пользователей в реальном времени в боте, необходимо включить Inline Mode в @BotFather:

  1. Отправьте /setinline боту @BotFather
  2. Выберите своего бота
  3. Введите текст-заполнитель (например, "Поиск пользователей...")

Webhook vs Long Polling

Webhook (Рекомендуется для продакшена)

  • ✅ Мгновенная доставка сообщений
  • ✅ Меньшая нагрузка на сервер
  • ✅ Более надежный
  • ❌ Требуется публичный HTTPS URL
  • ❌ Более сложная настройка

Long Polling (Подходит для разработки)

  • ✅ Простая настройка, не требуется публичный URL
  • ✅ Работает за файрволом
  • ❌ Более высокая задержка
  • ❌ Больше серверных ресурсов

Примеры использования

{
  "telegram": {
    "enable": true,
    "token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
    "method": "webhook",
    "webhook_url": "https://panel.example.com/api/telegram/webhook",
    "webhook_secret": "your_random_secret_here",
    "mini_app_login": true,
    "mini_app_web_url": "https://panel.example.com",
    "for_admins_only": true
  }
}
{
  "telegram": {
    "enable": true,
    "token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
    "method": "long-polling",
    "mini_app_login": false,
    "for_admins_only": false
  }
}
{
  "telegram": {
    "enable": true,
    "token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
    "method": "long-polling",
    "proxy_url": "socks5://proxy.example.com:1080",
    "for_admins_only": true
  }
}

2. Настройки Webhook

Настройка внешних webhook для интеграций со сторонними системами (например, системами мониторинга).

Поля

ПолеТипОбязательноеПо умолчаниюОписание
enablebooleanДаfalseВключить/выключить уведомления через webhook
webhooksarrayПри включении[]Массив конфигураций webhook (каждый с url и secret)
days_leftarrayНет[]Пороги в днях для оповещений об истечении срока (например, [3, 7, 14])
usage_percentarrayНет[]Пороги процента использования (например, [80, 90, 100])
timeoutintegerНет10Таймаут HTTP-запроса в секундах (должен быть >0)
recurrentintegerНет3600Интервал для повторяющихся проверок в секундах (должен быть >0)
proxy_urlstringНетnullURL прокси для webhook-запросов

Примеры использования

{
  "webhook": {
    "enable": true,
    "webhooks": [
      {
        "url": "https://monitoring1.example.com/webhook",
        "secret": "secret1"
      },
      {
        "url": "https://monitoring2.example.com/webhook",
        "secret": "secret2"
      }
    ],
    "days_left": [1, 3, 7],
    "usage_percent": [90, 100],
    "timeout": 15,
    "recurrent": 1800
  }
}
{
  "webhook": {
    "enable": true,
    "webhooks": [
      {"url": "https://alerts.example.com/critical", "secret": "secret"}
    ],
    "days_left": [1, 3],
    "usage_percent": [95, 100],
    "timeout": 5,
    "recurrent": 7200
  }
}

3. Настройки уведомлений

Настройка уведомлений Telegram/Discord для системных событий с использованием системы доставки на основе очереди.

Базовая конфигурация

ПолеТипОбязательноеПо умолчаниюОписание
notify_telegrambooleanДаfalseВключить уведомления Telegram
notify_discordbooleanДаfalseВключить уведомления Discord
telegram_api_tokenstringЕсли notify_telegramnullAPI-токен бота Telegram
telegram_chat_idintegerЕсли notify_telegramnullID резервного канала/чата Telegram
telegram_topic_idintegerНетnullID резервной темы/треда Telegram (для форум-каналов)
discord_webhook_urlstringЕсли notify_discordnullURL резервного webhook Discord
proxy_urlstringНетnullПрокси для API-запросов уведомлений
max_retriesintegerНет3Максимальное количество повторных попыток для неудавшихся уведомлений (должно быть >1)

Каналы уведомлений для отдельных сущностей

Вы можете настроить отдельные каналы Telegram/Discord для разных типов сущностей. Если не настроено, уведомления отправляются в основной канал.

СущностьОписаниеТипы уведомлений
channels.adminСобытия учетных записей администраторовcreate, modify, delete, reset_usage, login
channels.coreСобытия конфигурации ядраcreate, modify, delete
channels.groupСобытия групп/inbound группcreate, modify, delete
channels.hostКонфигурация хоста/inboundcreate, modify, delete, modify_hosts
channels.nodeСобытия серверов нодовcreate, modify, delete, connect, error
channels.userСобытия учетных записей пользователейcreate, modify, delete, status_change, reset_data_usage, data_reset_by_next, subscription_revoked
channels.user_templateСобытия шаблонов пользователейcreate, modify, delete

Каждый канал сущности поддерживает:

{
  "telegram_chat_id": -1001234567890,  // Необязательно: канал для конкретной сущности
  "telegram_topic_id": 5,               // Необязательно: ID темы в форум-канале
  "discord_webhook_url": "https://..."  // Необязательно: webhook Discord для конкретной сущности
}

Система уведомлений на основе очереди

Как это работает:

  1. Уведомления добавляются в очередь в памяти
  2. Фоновый обработчик последовательно обрабатывает очередь (одно за другим)
  3. Лимиты скорости от API Telegram/Discord автоматически соблюдаются
  4. Неудавшиеся уведомления повторяются с экспоненциальной задержкой (до max_retries)
  5. Система извлекает retry_after из ответов API 429 (не жестко закодированные задержки)

Преимущества:

  • ✅ Нет потери уведомлений при ограничении скорости
  • ✅ Автоматический повтор при временных сбоях
  • ✅ Последовательная доставка сохраняет порядок сообщений
  • ✅ Динамически соблюдает лимиты API

Примеры использования

{
  "notification_settings": {
    "notify_telegram": true,
    "notify_discord": false,
    "telegram_api_token": "987654321:XYZabcDEFghiJKLmno",
    "telegram_chat_id": -1001234567890,
    "max_retries": 3
  }
}
{
  "notification_settings": {
    "notify_telegram": true,
    "telegram_api_token": "987654321:XYZabcDEFghiJKLmno",
    "telegram_chat_id": -1001111111111,  // Резервный/стандартный канал
    "max_retries": 3,
    "channels": {
      "admin": {
        "telegram_chat_id": -1002222222222,
        "telegram_topic_id": 10
      },
      "user": {
        "telegram_chat_id": -1003333333333,
        "telegram_topic_id": 20
      },
      "node": {
        "telegram_chat_id": -1004444444444
      }
    }
  }
}
{
  "notification_settings": {
    "notify_telegram": true,
    "notify_discord": true,
    "telegram_api_token": "987654321:XYZabcDEFghiJKLmno",
    "telegram_chat_id": -1001234567890,
    "discord_webhook_url": "https://discord.com/api/webhooks/123/abc",
    "max_retries": 5,
    "channels": {
      "admin": {
        "telegram_chat_id": -1005555555555  // Критические события в Telegram
      },
      "user": {
        "discord_webhook_url": "https://discord.com/api/webhooks/456/def"  // События пользователей в Discord
      }
    }
  }
}
{
  "notification_settings": {
    "notify_telegram": true,
    "telegram_api_token": "987654321:XYZabcDEFghiJKLmno",
    "telegram_chat_id": -1001234567890,
    "proxy_url": "socks5://proxy.internal:1080",
    "max_retries": 3
  }
}

4. Включение уведомлений (детальный контроль)

Точное управление тем, какие типы уведомлений отправляются для каждой сущности. Это позволяет уменьшить шум, отключая ненужные уведомления.

Обзор структуры

{
  "notification_enable": {
    "admin": { /* AdminNotificationEnable */ },
    "core": { /* BaseNotificationEnable */ },
    "group": { /* BaseNotificationEnable */ },
    "host": { /* HostNotificationEnable */ },
    "node": { /* NodeNotificationEnable */ },
    "user": { /* UserNotificationEnable */ },
    "user_template": { /* BaseNotificationEnable */ }
  }
}

Типы уведомлений по сущностям

AdminNotificationEnable

{
  "admin": {
    "create": true,       // Создана новая учетная запись администратора
    "modify": true,       // Изменена учетная запись администратора
    "delete": true,       // Удалена учетная запись администратора
    "reset_usage": true,  // Сброшено использование администратора
    "login": true         // Попытки входа администратора (успех/неудача)
  }
}

BaseNotificationEnable

{
  "core": {
    "create": true,   // Создана новая конфигурация ядра
    "modify": true,   // Изменена конфигурация ядра
    "delete": true    // Удалена конфигурация ядра
  }
}

BaseNotificationEnable

{
  "group": {
    "create": true,   // Создана новая группа
    "modify": true,   // Изменена группа
    "delete": true    // Удалена группа
  }
}

HostNotificationEnable

{
  "host": {
    "create": true,       // Создан новый хост/inbound
    "modify": true,       // Изменен хост
    "delete": true,       // Удален хост
    "modify_hosts": true  // Массовое изменение хостов
  }
}

NodeNotificationEnable

{
  "node": {
    "create": true,   // Добавлена новая нода
    "modify": true,   // Изменена конфигурация ноды
    "delete": true,   // Удалена нода
    "connect": true,  // Нода успешно подключена
    "error": true     // Ошибка подключения ноды
  }
}

UserNotificationEnable

{
  "user": {
    "create": true,               // Создан новый пользователь
    "modify": true,               // Изменен пользователь
    "delete": true,               // Удален пользователь
    "status_change": true,        // Изменен статус пользователя (активен/истек/ограничен/отключен)
    "reset_data_usage": true,     // Вручную сброшено использование данных пользователя
    "data_reset_by_next": true,   // Использование данных сброшено следующим планом
    "subscription_revoked": true  // Доступ к подписке пользователя отозван
  }
}

BaseNotificationEnable

{
  "user_template": {
    "create": true,   // Создан новый шаблон
    "modify": true,   // Изменен шаблон
    "delete": true    // Удален шаблон
  }
}

Примеры использования

{
  "notification_enable": {
    "admin": {
      "create": false,
      "modify": false,
      "delete": true,
      "reset_usage": false,
      "login": true
    },
    "core": {"create": false, "modify": false, "delete": true},
    "group": {"create": false, "modify": false, "delete": false},
    "host": {"create": false, "modify": false, "delete": true, "modify_hosts": false},
    "node": {"create": false, "modify": false, "delete": false, "connect": false, "error": true},
    "user": {
      "create": false,
      "modify": false,
      "delete": true,
      "status_change": true,
      "reset_data_usage": false,
      "data_reset_by_next": false,
      "subscription_revoked": true
    },
    "user_template": {"create": false, "modify": false, "delete": false}
  }
}
{
  "notification_enable": {
    "admin": {"create": false, "modify": false, "delete": false, "reset_usage": false, "login": false},
    "core": {"create": false, "modify": false, "delete": false},
    "group": {"create": false, "modify": false, "delete": false},
    "host": {"create": false, "modify": false, "delete": false, "modify_hosts": false},
    "node": {"create": false, "modify": false, "delete": false, "connect": false, "error": false},
    "user": {
      "create": true,
      "modify": true,
      "delete": true,
      "status_change": true,
      "reset_data_usage": true,
      "data_reset_by_next": true,
      "subscription_revoked": true
    },
    "user_template": {"create": false, "modify": false, "delete": false}
  }
}
{
  "notification_enable": {
    "admin": {"create": false, "modify": false, "delete": false, "reset_usage": false, "login": false},
    "core": {"create": false, "modify": false, "delete": false},
    "group": {"create": false, "modify": false, "delete": false},
    "host": {"create": false, "modify": false, "delete": false, "modify_hosts": false},
    "node": {"create": false, "modify": false, "delete": false, "connect": false, "error": false},
    "user": {
      "create": false,
      "modify": false,
      "delete": false,
      "status_change": false,
      "reset_data_usage": false,
      "data_reset_by_next": false,
      "subscription_revoked": false
    },
    "user_template": {"create": false, "modify": false, "delete": false}
  }
}

5. Настройки подписки

Самый важный раздел

Настройте способ доступа пользователей к их конфигурациям подписки. Этот раздел критически важен для правильной работы клиентов.

Основные поля

ПолеТипОбязательноеПо умолчаниюОписание
url_prefixstringРекомендуется""Базовый URL для ссылок подписки (например, "https://sub.example.com")
update_intervalintegerНет12Интервал обновления в часах, показываемый клиентам
support_urlstringНет"https://t.me/"URL поддержки/контактов, показываемый в клиентских приложениях
profile_titlestringНет"Subscription"Заголовок профиля подписки (поддерживает переменные)
announcestringНет""Текст объявления (макс. 128 символов, только v2RayTun и Happ)
announce_urlstringНет""URL для дополнительной информации об объявлении
host_status_filterbooleanДа-Фильтровать хосты на основе статуса пользователя
rulesarrayДа-Правила определения user-agent для автоконфигурации
manual_sub_requestobjectНетвсе trueВключить/выключить запросы форматов вручную
applicationsarrayНет[]Конфигурации клиентских приложений с URL импорта

Переменные заголовка профиля

Поле profile_title поддерживает динамические переменные:

ПеременнаяОписаниеПример вывода
{username}Имя пользователяjohn_doe
{used_traffic}Использованный трафик (отформатированный)5.2 GB
{data_limit}Лимит данных (отформатированный)50 GB
{data_left}Оставшиеся данные (отформатированные)44.8 GB
{expire_date}Дата истечения2024-12-31
{expire_days}Дней до истечения45
{status}Статус пользователяactive
{admin_username}Имя администратораadmin1

Пример:

{
  "profile_title": "{username} | {data_limit} | Истекает через: {expire_days} дней"
}

Вывод: john_doe | 50 GB | Истекает через: 45 дней

Фильтр статуса хоста

Управляет тем, фильтруются ли хосты на основе статуса пользователя.

{
  "host_status_filter": true  // или false
}

Когда true:

  • Пользователи видят только хосты, соответствующие их текущему статусу
  • Позволяет создавать отдельные группы хостов для разных статусов пользователей
  • Пример использования: Премиум-хосты для активных пользователей, ограниченные хосты для пользователей на паузе

Когда false:

  • Пользователи видят все включенные хосты независимо от их статуса
  • Более простая конфигурация, менее детальный контроль

Важно

Когда поле статуса хоста пустое (не настроено), этот хост будет показан всем пользователям независимо от настройки host_status_filter.

Пример сценария:

Хост A: status = [active, limited]
Хост B: status = [active]
Хост C: status = [on_hold]

Пользователь со статусом = "active":
  - host_status_filter=true  → видит Хост A, Хост B
  - host_status_filter=false → видит Хост A, Хост B, Хост C

Пользователь со статусом = "on_hold":
  - host_status_filter=true  → видит только Хост C
  - host_status_filter=false → видит Хост A, Хост B, Хост C

Правила определения клиента

Массив rules определяет, как определять типы клиентов на основе заголовка User-Agent и какой формат конфигурации возвращать.

{
  "rules": [
    {
      "pattern": "regex_pattern",
      "target": "config_format"
    }
  ]
}

Доступные форматы конфигурации (target):

  • links - Обычные ссылки подписки
  • links_base64 - Ссылки подписки в кодировке Base64
  • xray - JSON-конфигурация Xray-core
  • sing_box - JSON-конфигурация sing-box
  • clash - YAML-конфигурация Clash
  • clash_meta - YAML-конфигурация Clash Meta
  • outline - JSON-конфигурация Outline
  • block - Специальная цель для запрета доступа (возвращает HTTP 406)

Как это работает:

  1. Клиент запрашивает подписку с заголовком User-Agent
  2. Система проверяет User-Agent по шаблонам в порядке очереди
  3. Первый совпадающий шаблон определяет формат конфигурации
  4. Если нет совпадений и формат не включен в manual_sub_request, возвращается 406
  5. Конфигурация генерируется и возвращается с соответствующими заголовками

Готовые к продакшену шаблоны:

{
  "rules": [
    {
      "pattern": "^(Telegram|WhatsApp|TelegramBot|WhatsAppBot)",
      "target": "block"
    },
    {
      "pattern": "^([Cc]lash[\\-\\.]?[Vv]erge|[Cc]lash[\\-\\.]?[Mm]eta|[Ff][Ll][Cc]lash|[Mm]ihomo)",
      "target": "clash_meta"
    },
    {
      "pattern": "^([Cc]lash|[Ss]tash)",
      "target": "clash"
    },
    {
      "pattern": "^(SFA|SFI|SFM|SFT|[Kk]aring|[Hh]iddify[Nn]ext)|.*[Ss]ing[\\-b]?ox.*",
      "target": "sing_box"
    },
    {
      "pattern": "^(SS|SSR|SSD|SSS|Outline|Shadowsocks|SSconf)",
      "target": "outline"
    },
    {
      "pattern": "^.*",
      "target": "links_base64"
    }
  ]
}

Что ловит каждый шаблон:

  1. Заблокированные клиентыblock

    • Telegram (предотвращает доступ к подписке из приложения Telegram)
    • WhatsApp (предотвращает доступ к подписке из WhatsApp)
    • TelegramBot (блокирует автоматические запросы ботов)
    • WhatsAppBot (блокирует автоматические запросы ботов)
  2. Варианты Clash Metaclash_meta

    • Clash-Verge, Clash.Verge, ClashVerge
    • Clash-Meta, Clash.Meta, ClashMeta
    • FLClash, Mihomo
  3. Варианты Clashclash

    • Clash (оригинальный)
    • Stash (iOS-клиент)
  4. Варианты sing-boxsing_box

    • SFA (sing-box для Android)
    • SFI (sing-box для iOS)
    • SFM (sing-box для macOS)
    • SFT (sing-box terminal)
    • Karing
    • HiddifyNext
    • Любой клиент с "sing-box" или "sing box" в User-Agent
  5. Варианты Shadowsocks/Outlineoutline

    • SS, SSR, SSD, SSS
    • Outline
    • Shadowsocks
    • SSconf
  6. Запасной вариантlinks_base64

    • Совпадает со всем остальным (^.*)
    • Возвращает ссылки подписки в кодировке base64
    • Полезно для неизвестных или пользовательских клиентов

Блокировка нежелательных клиентов:

{
  "rules": [
    {"pattern": "^(Telegram|WhatsApp|TelegramBot|WhatsAppBot)", "target": "block"},
    {"pattern": "BadClient|SpamBot|Scraper", "target": "block"},
    {"pattern": "Clash", "target": "clash"}
  ]
}

Зачем блокировать Telegram/WhatsApp?

Блокировка этих user-agent предотвращает открытие ссылок подписки пользователями напрямую в мессенджерах, что может:

  • Раскрыть URL подписки в кешах приложений
  • Позволить нежелательный обмен через функции приложения
  • Обойти предназначенные клиентские приложения
  • Создать проблемы безопасности/конфиденциальности

Ручной запрос подписки

Управляет тем, какие форматы конфигурации могут быть запрошены вручную (когда user-agent не совпадает ни с одним правилом).

{
  "manual_sub_request": {
    "links": true,
    "links_base64": true,
    "xray": true,
    "sing_box": true,
    "clash": true,
    "clash_meta": true,
    "outline": true
  }
}

Примеры использования:

  • Включайте только форматы, которые вы активно поддерживаете
  • Отключайте неиспользуемые форматы для снижения поверхности атаки
  • Принудительное использование определенных клиентов через определение user-agent

Конфигурация приложений

Определите клиентские приложения с URL глубоких ссылок для простой настройки подписки в один клик.

{
  "applications": [
    {
      "name": "v2rayNG",
      "platform": "android",
      "icon_url": "https://cdn.example.com/icons/v2rayng.png",
      "import_url": "v2rayng://install-config?url={url}",
      "description": {
        "en": "Fast and lightweight VPN client for Android",
        "fa": "کلاینت سریع و سبک برای اندروید",
        "ru": "Быстрый VPN-клиент для Android",
        "zh": "适用于Android的快速VPN客户端"
      },
      "recommended": true,
      "download_links": [
        {
          "name": "Google Play",
          "url": "https://play.google.com/store/apps/details?id=com.v2ray.ang",
          "language": "en"
        },
        {
          "name": "GitHub Release",
          "url": "https://github.com/2dust/v2rayNG/releases",
          "language": "en"
        }
      ]
    }
  ]
}

Описание полей:

ПолеОбязательноеОписание
nameДаНазвание приложения (макс. 32 символа)
platformДаПлатформа: android, ios, windows, macos, linux, appletv, androidtv
icon_urlНетURL изображения иконки (макс. 512 символов)
import_urlНетШаблон URL глубокой ссылки (должен содержать заполнитель {url})
descriptionНетМногоязычные описания (en, fa, ru, zh)
recommendedНетОтметить как рекомендуемое (только одно на платформу)
download_linksНетМассив ссылок для загрузки с name, url и language

Заполнитель Import URL:

  • ДОЛЖЕН содержать заполнитель {url}
  • Система автоматически заменяет {url} на фактический URL подписки
  • Примеры:
    • v2rayng://install-config?url={url}
    • clash://install-config?url={url}
    • sing-box://import-remote-profile?url={url}

Правила валидации:

  • Только одно приложение с recommended: true на платформу
  • import_url должен содержать {url}, если указан
  • platform должна быть одной из определенных платформ

Как работает система подписки

1. Пользователь получает доступ к URL подписки

Формат: /sub/{token}
Пример: https://panel.example.com/sub/abc123def456

Токен уникально идентифицирует пользователя.

2. Определение типа запроса

HTML-запрос (браузер):

  • Заголовок Accept: text/html
  • Возвращает: HTML-страницу подписки
  • Показывает: Ссылки, QR-коды, кнопки импорта приложений
  • Использует: sub_template администратора или стандартный шаблон

API-запрос (клиентское приложение):

  • Заголовок Accept: другой (например, */*, application/json)
  • Возвращает: Файл конфигурации (YAML/JSON/обычный текст)
  • Формат определяется: Определением User-Agent или параметром формата вручную

3. Определение User-Agent

Клиент отправляет: User-Agent: v2rayNG/1.8.5

Система проверяет правила:
1. Шаблон: "^(Clash|ClashForAndroid)" → Нет совпадения
2. Шаблон: "v2rayN" → Совпадение! → Цель: "xray"

Возвращает: JSON-конфигурацию Xray

4. Генерация конфигурации

  1. Загрузка данных пользователя: Получение информации о пользователе, inbound, группах, квотах
  2. Применение фильтров:
    • Фильтрация inbound по членству пользователя в группах
    • Применение host_status_filter, если включено
  3. Генерация конфигурации: Создание соответствующего формата (Clash YAML, Xray JSON и т.д.)
  4. Кодирование: Кодирование в Base64, если требуется (например, links_base64)
  5. Установка заголовков: Добавление заголовков подписки
  6. Возврат: Отправка конфигурации клиенту

5. Заголовки ответа

Content-Disposition: attachment; filename="john_doe"
Profile-Web-Page-URL: https://panel.example.com/sub/abc123
Support-URL: https://t.me/support
Profile-Title: john_doe%20%7C%2050%20GB
Profile-Update-Interval: 12
Subscription-Userinfo: upload=0; download=5589934592; total=53687091200; expire=1735689599

Полные примеры использования

{
  "subscription": {
    "url_prefix": "https://sub.example.com",
    "update_interval": 12,
    "support_url": "https://t.me/support",
    "profile_title": "{username} - {data_limit}",
    "host_status_filter": false,
    "rules": [
      {"pattern": "Clash", "target": "clash"},
      {"pattern": "v2ray", "target": "xray"},
      {"pattern": "Hiddify", "target": "sing_box"}
    ],
    "manual_sub_request": {
      "links": true,
      "xray": true,
      "clash": true,
      "sing_box": true
    }
  }
}
{
  "subscription": {
    "url_prefix": "https://sub.example.com",
    "update_interval": 24,
    "profile_title": "Безопасная подписка",
    "host_status_filter": false,
    "rules": [
      {"pattern": "BadClient|Scraper|Bot", "target": "block"},  // Блокировать их
      {"pattern": "Clash", "target": "clash"},
      {"pattern": "v2ray", "target": "xray"}
    ],
    "manual_sub_request": {
      "links": false,
      "links_base64": false,
      "xray": true,
      "clash": true
    }
  }
}
{
  "subscription": {
    "url_prefix": "https://sub.example.com",
    "update_interval": 12,
    "profile_title": "{username}",
    "host_status_filter": false,
    "rules": [
      {"pattern": "Clash", "target": "clash"},
      {"pattern": "v2ray", "target": "xray"}
    ],
    "applications": [
      {
        "name": "v2rayNG",
        "platform": "android",
        "icon_url": "https://cdn.example.com/v2rayng.png",
        "import_url": "v2rayng://install-config?url={url}",
        "description": {
          "en": "Best Android VPN client",
          "ru": "Лучший Android VPN-клиент"
        },
        "recommended": true,
        "download_links": [
          {"name": "Play Store", "url": "https://play.google.com/...", "language": "en"},
          {"name": "Прямой APK", "url": "https://github.com/.../v2rayNG.apk", "language": "ru"}
        ]
      },
      {
        "name": "Hiddify",
        "platform": "ios",
        "icon_url": "https://cdn.example.com/hiddify.png",
        "import_url": "hiddify://import-remote-profile?url={url}",
        "description": {
          "en": "Best iOS VPN client",
          "ru": "Лучший iOS VPN-клиент"
        },
        "recommended": true,
        "download_links": [
          {"name": "App Store", "url": "https://apps.apple.com/...", "language": "en"}
        ]
      },
      {
        "name": "Clash Verge",
        "platform": "windows",
        "icon_url": "https://cdn.example.com/clash.png",
        "import_url": "clash://install-config?url={url}",
        "description": {
          "en": "Modern Clash GUI for Windows",
          "ru": "Современный Clash GUI для Windows"
        },
        "recommended": true,
        "download_links": [
          {"name": "GitHub", "url": "https://github.com/.../releases", "language": "en"}
        ]
      }
    ]
  }
}
{
  "subscription": {
    "url_prefix": "https://sub.example.com",
    "update_interval": 6,
    "support_url": "https://t.me/support",
    "profile_title": "⚡ {username} | 📊 {data_left}/{data_limit} | ⏰ {expire_days}д",
    "announce": "🎉 Добавлены новые серверы! Обновите подписку.",
    "announce_url": "https://example.com/news/new-servers",
    "host_status_filter": false,
    "rules": [
      {"pattern": "v2ray", "target": "xray"}
    ]
  }
}

Лучшие практики

ДЕЛАЙТЕ

  • Всегда устанавливайте url_prefix для правильной генерации глубоких ссылок
  • Тестируйте регулярные выражения с помощью онлайн-тестеров перед развертыванием
  • Упорядочивайте правила осторожно - сначала специфичные шаблоны, затем общие
  • Используйте host_status_filter только если у вас настроены хосты для конкретных статусов
  • Держите объявления краткими - макс. 128 символов
  • Валидируйте URL импорта - должен содержать заполнитель {url}
  • Одно рекомендуемое приложение на платформу максимум
  • Используйте осмысленные заголовки профилей с переменными для лучшего UX

НЕ ДЕЛАЙТЕ

  • Не оставляйте url_prefix пустым в продакшене (ломает URL импорта)
  • Не используйте перекрывающиеся регулярные выражения (побеждает первое совпадение)
  • Не включайте host_status_filter без настройки статусов хостов
  • Не превышайте 128 символов в поле announce
  • Не забывайте заполнитель {url} в import_url
  • Не устанавливайте несколько приложений как recommended: true для одной платформы
  • Не используйте специальные символы в profile_title, которые ломают URL

Тестирование

# Тестирование эндпоинта подписки
curl -v "https://panel.example.com/sub/TOKEN" \
  -H "User-Agent: v2rayNG/1.8.5"

# Тестирование HTML-страницы
curl -v "https://panel.example.com/sub/TOKEN" \
  -H "Accept: text/html"

# Проверка заголовков ответа
curl -I "https://panel.example.com/sub/TOKEN"

6. Общие настройки

Стандартные настройки прокси-протокола, применяемые при создании новых конфигураций.

Важно

Эти настройки применяются только фронтендом в качестве значений по умолчанию при создании новых конфигураций. Они НЕ влияют на:

  • Прямые API-запросы (API обходит эти значения по умолчанию)
  • Ручные изменения во фронтенде (пользователи могут переопределить эти значения)
  • Существующие конфигурации (применяется только к новым конфигурациям)

Поля

ПолеТипПо умолчаниюОписание
default_flowstring"none"Стандартное управление потоком XTLS (только по умолчанию для фронтенда)
default_methodstring"chacha20-poly1305"Стандартный метод шифрования Shadowsocks (только по умолчанию для фронтенда)

Опции XTLS Flow

ЗначениеОписание
noneНет XTLS (стандартный TLS)
xtls-rprx-visionПоток XTLS Vision (рекомендуется для VLESS)

Методы Shadowsocks

ЗначениеБезопасностьПроизводительность
chacha20-poly1305ВысокаяБыстрая
chacha20-ietf-poly1305ВысокаяБыстрая
aes-256-gcmВысокаяСредняя
aes-128-gcmСредняяБыстрая

Пример

{
  "general": {
    "default_flow": "xtls-rprx-vision",
    "default_method": "chacha20-poly1305"
  }
}

Полный пример конфигурации

Этот пример демонстрирует готовую к продакшену конфигурацию со всеми включенными функциями:

{
  "telegram": {
    "enable": true,
    "token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz0123456",
    "method": "webhook",
    "webhook_url": "https://panel.example.com/api/telegram/webhook",
    "webhook_secret": "random_secret_string_here",
    "proxy_url": null,
    "mini_app_login": true,
    "mini_app_web_url": "https://panel.example.com",
    "for_admins_only": true
  },
  "webhook": {
    "enable": true,
    "webhooks": [
      {
        "url": "https://uptime.example.com/api/push/abc123",
        "secret": "uptime_kuma_secret"
      },
      {
        "url": "https://monitoring.example.com/webhook",
        "secret": "monitoring_secret"
      }
    ],
    "days_left": [1, 3, 7, 14],
    "usage_percent": [80, 90, 95, 100],
    "timeout": 10,
    "recurrent": 3600,
    "proxy_url": null
  },
  "notification_settings": {
    "notify_telegram": true,
    "notify_discord": false,
    "telegram_api_token": "987654321:XYZabcDEFghiJKLmno9876543210ABCDEF",
    "telegram_chat_id": -1001234567890,
    "telegram_topic_id": null,
    "discord_webhook_url": null,
    "proxy_url": null,
    "max_retries": 3,
    "channels": {
      "admin": {
        "telegram_chat_id": -1002222222222,
        "telegram_topic_id": 10,
        "discord_webhook_url": null
      },
      "user": {
        "telegram_chat_id": -1003333333333,
        "telegram_topic_id": 20,
        "discord_webhook_url": null
      },
      "node": {
        "telegram_chat_id": -1004444444444,
        "telegram_topic_id": null,
        "discord_webhook_url": null
      }
    }
  },
  "notification_enable": {
    "admin": {
      "create": true,
      "modify": false,
      "delete": true,
      "reset_usage": true,
      "login": true
    },
    "core": {
      "create": true,
      "modify": false,
      "delete": true
    },
    "group": {
      "create": true,
      "modify": false,
      "delete": true
    },
    "host": {
      "create": true,
      "modify": false,
      "delete": true,
      "modify_hosts": true
    },
    "node": {
      "create": true,
      "modify": false,
      "delete": true,
      "connect": true,
      "error": true
    },
    "user": {
      "create": true,
      "modify": true,
      "delete": true,
      "status_change": true,
      "reset_data_usage": true,
      "data_reset_by_next": true,
      "subscription_revoked": true
    },
    "user_template": {
      "create": true,
      "modify": false,
      "delete": true
    }
  },
  "subscription": {
    "url_prefix": "https://sub.example.com",
    "update_interval": 12,
    "support_url": "https://t.me/example_support",
    "profile_title": "{username} | {data_limit} | Истекает: {expire_days}д",
    "announce": "Добро пожаловать! Обновляйте каждые 12 часов для лучшей производительности.",
    "announce_url": "https://example.com/announcements",
    "host_status_filter": true,
    "rules": [
      {"pattern": "^(Clash|ClashForAndroid)", "target": "clash"},
      {"pattern": "ClashMeta", "target": "clash_meta"},
      {"pattern": "Stash", "target": "clash"},
      {"pattern": "Shadowrocket", "target": "links"},
      {"pattern": "v2rayN", "target": "xray"},
      {"pattern": "v2rayNG", "target": "xray"},
      {"pattern": "Hiddify|SFI|SFA", "target": "sing_box"},
      {"pattern": "Outline", "target": "outline"}
    ],
    "manual_sub_request": {
      "links": true,
      "links_base64": true,
      "xray": true,
      "sing_box": true,
      "clash": true,
      "clash_meta": true,
      "outline": true
    },
    "applications": [
      {
        "name": "v2rayNG",
        "platform": "android",
        "icon_url": "https://cdn.example.com/icons/v2rayng.png",
        "import_url": "v2rayng://install-config?url={url}",
        "description": {
          "en": "Recommended Android client",
          "ru": "Рекомендуемый Android-клиент"
        },
        "recommended": true,
        "download_links": [
          {
            "name": "GitHub Release",
            "url": "https://github.com/2dust/v2rayNG/releases",
            "language": "en"
          }
        ]
      },
      {
        "name": "Hiddify",
        "platform": "ios",
        "icon_url": "https://cdn.example.com/icons/hiddify.png",
        "import_url": "hiddify://import-remote-profile?url={url}",
        "description": {
          "en": "Recommended iOS client",
          "ru": "Рекомендуемый iOS-клиент"
        },
        "recommended": true,
        "download_links": [
          {
            "name": "App Store",
            "url": "https://apps.apple.com/app/hiddify",
            "language": "en"
          }
        ]
      }
    ]
  },
  "general": {
    "default_flow": "xtls-rprx-vision",
    "default_method": "chacha20-poly1305"
  }
}

Дополнительные ресурсы


Поддержка

По вопросам, проблемам или предложениям:


On this page

Содержание1. Настройки Telegram-ботаПоляВажные примечанияПримеры использования2. Настройки WebhookПоляПримеры использования3. Настройки уведомленийБазовая конфигурацияКаналы уведомлений для отдельных сущностейПримеры использования4. Включение уведомлений (детальный контроль)Обзор структурыТипы уведомлений по сущностямПримеры использования5. Настройки подпискиОсновные поляПеременные заголовка профиляФильтр статуса хостаПравила определения клиентаРучной запрос подпискиКонфигурация приложенийКак работает система подписки1. Пользователь получает доступ к URL подписки2. Определение типа запроса3. Определение User-Agent4. Генерация конфигурации5. Заголовки ответаПолные примеры использованияЛучшие практики6. Общие настройкиПоляОпции XTLS FlowМетоды ShadowsocksПримерПолный пример конфигурацииДополнительные ресурсыПоддержка