Документация по шаблонам пользователей

Этот документ объясняет, как работают шаблоны пользователей в PasarGuard. Шаблоны — это предварительно настроенные настройки пользователей, которые можно использовать для быстрого создания пользователей с согласованными конфигурациями. Он разработан, чтобы помочь новичкам понять управление шаблонами, применение полей и массовое создание пользователей.

Содержание

1. Обзор
2. Основы конфигурации шаблона
3. Объяснение полей шаблона
4. Как работают шаблоны
5. Обработка имени пользователя
6. Дополнительные настройки
7. Статус и истечение срока
8. Лимит данных и стратегия сброса
9. Создание пользователей из шаблонов
10. Изменение пользователей с помощью шаблонов
11. Массовое создание пользователей
12. Правила валидации и ограничения
13. API Endpoints
14. Распространенные сценарии

Обзор

Шаблоны пользователей в PasarGuard — это предварительно настроенные настройки пользователей, которые:

• Стандартизируют создание пользователей - Применяют согласованные настройки к нескольким пользователям
• Ускоряют управление пользователями - Быстро создают пользователей без настройки каждого поля
• Поддерживают массовые операции - Создают много пользователей одновременно с автоматической генерацией имен пользователей
• Включают автоматизацию - Шаблоны можно использовать в автоматизированных рабочих процессах

Поток шаблона

Template → User Creation → Applied Settings

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

1. Администратор создает шаблон с желаемыми настройками пользователя
2. При создании пользователя администратор выбирает шаблон
3. Поля шаблона автоматически применяются к новому пользователю
4. Администратору нужно только указать имя пользователя (и при необходимости примечание)
5. Пользователь создается со всеми настройками шаблона

Основы конфигурации шаблона

Обязательные поля

Каждый шаблон должен иметь:

Необязательные поля

Поля ответа шаблона

При получении шаблонов вы также получаете:

Объяснение полей шаблона

Базовые поля

name (String, Обязательно)

• Назначение: Идентификатор шаблона
• Ограничения: Макс. 64 символа
• Пример: "Premium Plan", "Basic User", "Trial Account"

group_ids (List[Integer], Обязательно при создании)

• Назначение: Группы для назначения пользователям, созданным из этого шаблона
• Поведение: Пользователи автоматически присоединяются к этим группам при создании
• Валидация: Все ID групп должны существовать
• Пример: [1, 2, 3] - Пользователь присоединяется к группам 1, 2 и 3

data_limit (Integer, Необязательно)

• Назначение: Максимальное использование данных в байтах
• По умолчанию: 0 (неограниченно)
• Формат: Байты (например, 1073741824 = 1 GB)
• Пример: 1073741824 = лимит 1 GB

expire_duration (Integer, Необязательно)

• Назначение: Продолжительность истечения срока аккаунта в секундах
• По умолчанию: 0 (неограниченно)
• Расчет: При создании пользователя истечение = сейчас + expire_duration
• Пример: 2592000 = 30 дней (30 * 24 * 60 * 60)

Поля имени пользователя

username_prefix (String, Необязательно)

• Назначение: Префикс, добавляемый перед именем пользователя при создании пользователей
• Ограничения: Макс. 20 символов
• Поведение: Добавляется к указанному имени пользователя
• Пример: Префикс "premium_" + имя пользователя "john" = "premium_john"

username_suffix (String, Необязательно)

• Назначение: Суффикс, добавляемый после имени пользователя при создании пользователей
• Ограничения: Макс. 20 символов
• Поведение: Добавляется к указанному имени пользователя
• Пример: Имя пользователя "john" + суффикс "_vip" = "john_vip"

Комбинированный пример:

prefix: "premium_"
username: "john"
suffix: "_vip"
Result: "premium_john_vip"

Поля статуса

status (UserStatusCreate, Необязательно)

• Назначение: Начальный статус пользователя
• Опции:
  • active - Пользователь активен (по умолчанию)
  • on_hold - Пользователь на удержании
• По умолчанию: active
• Поведение: Влияет на расчет истечения срока (см. раздел Статус и истечение срока)

on_hold_timeout (Integer, Необязательно)

• Назначение: Когда статус on_hold должен начаться/закончиться
• Формат: Секунды от времени создания
• Требуется: Когда status равен on_hold и expire_duration установлен
• Пример: 3600 = Пользователь становится активным через 1 час

Поля управления данными

data_limit_reset_strategy (DataLimitResetStrategy, Необязательно)

• Назначение: Как сбрасывается лимит данных
• Опции:
  • no_reset - Никогда не сбрасывается (по умолчанию)
  • day - Сбрасывается ежедневно
  • week - Сбрасывается еженедельно
  • month - Сбрасывается ежемесячно
  • year - Сбрасывается ежегодно
• По умолчанию: no_reset
• Примечание: Применяется только если установлен data_limit

reset_usages (Boolean, Необязательно)

• Назначение: Сброс использования данных при применении шаблона к существующему пользователю
• По умолчанию: false
• Поведение: Используется только при изменении существующих пользователей с помощью шаблонов
• Эффект: Очищает историю использования данных пользователя

Продвинутые поля

extra_settings (ExtraSettings, Необязательно)

• Назначение: Настройки, специфичные для протокола
• Поля:
  • flow - Управление потоком VLESS (enum XTLSFlows)
  • method - Метод шифрования Shadowsocks (enum ShadowsocksMethods)
• По умолчанию: null
• Пример: {"flow": "xtls-rprx-vision", "method": "chacha20-poly1305"}

is_disabled (Boolean, Необязательно)

• Назначение: Отключить шаблон, чтобы предотвратить использование
• По умолчанию: false
• Поведение: Отключенные шаблоны нельзя использовать для создания или изменения пользователей
• Случай использования: Временно отключить шаблоны без их удаления

Как работают шаблоны

Процесс применения шаблона

При создании пользователя из шаблона:

1. Валидация шаблона - Шаблон должен существовать и не быть отключенным
2. Загрузка полей - Базовые поля загружаются из шаблона
3. Построение имени пользователя - Префикс + имя пользователя + суффикс
4. Применение настроек - Применяются дополнительные настройки (flow, method)
5. Создание пользователя - Пользователь создается со всеми значениями шаблона

Порядок применения полей

Template Fields → User Creation → Final User

Что применяется:

• ✅ data_limit → Лимит данных пользователя
• ✅ expire_duration → Истечение срока пользователя (рассчитывается от сейчас)
• ✅ group_ids → Группы пользователя
• ✅ status → Начальный статус пользователя
• ✅ data_limit_reset_strategy → Стратегия сброса пользователя
• ✅ username_prefix + username + username_suffix → Финальное имя пользователя
• ✅ extra_settings.flow → Настройка потока VLESS
• ✅ extra_settings.method → Настройка метода Shadowsocks
• ✅ on_hold_timeout → Таймаут on_hold пользователя (если статус on_hold)

Что не применяется:

• ❌ name - Имя шаблона не копируется в пользователя
• ❌ is_disabled - Состояние шаблона не влияет на созданных пользователей
• ❌ reset_usages - Используется только при изменении существующих пользователей

Обработка имени пользователя

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

При создании пользователя из шаблона финальное имя пользователя строится как:

Final Username = prefix + provided_username + suffix

Правила:

• Если префикс null или пустой, он не добавляется
• Если суффикс null или пустой, он не добавляется
• Указанное имя пользователя должно быть валидным (3-128 символов, буквенно-цифровые + специальные символы)
• Финальное имя пользователя должно быть уникальным

Template: prefix = "premium_", suffix = null
Provided: username = "john"
Result: "premium_john"

Template: prefix = null, suffix = "_vip"
Provided: username = "john"
Result: "john_vip"

Template: prefix = "premium_", suffix = "_vip"
Provided: username = "john"
Result: "premium_john_vip"

Template: prefix = null, suffix = null
Provided: username = "john"
Result: "john"

Валидация имени пользователя

Финальное имя пользователя (после префикса/суффикса) должно:

• Быть длиной 3-128 символов
• Содержать только: a-z, A-Z, 0-9, -, _, @, .
• Не иметь последовательных специальных символов
• Быть уникальным (не существовать уже)

Дополнительные настройки

Flow (VLESS)

Управляет настройкой управления потоком VLESS.

Опции:

• none - Нет потока (по умолчанию)
• xtls-rprx-vision - XTLS Reality Proxy Vision

Применяется к: Настройкам прокси VLESS пользователя

Пример:

{
  "extra_settings": {
    "flow": "xtls-rprx-vision"
  }
}

Method (Shadowsocks)

Управляет методом шифрования Shadowsocks.

Опции:

• chacha20-ietf-poly1305 - ChaCha20-ietf-Poly1305 (по умолчанию)
• xchacha20-poly1305 - XChaCha20-Poly1305
• aes-128-gcm - AES-128-GCM
• aes-256-gcm - AES-256-GCM
• И другие методы Shadowsocks

Применяется к: Настройкам прокси Shadowsocks пользователя

Пример:

{
  "extra_settings": {
    "method": "aes-256-gcm"
  }
}

Комбинированные дополнительные настройки

Вы можете установить и flow, и method:

{
  "extra_settings": {
    "flow": "xtls-rprx-vision",
    "method": "aes-256-gcm"
  }
}

Статус и истечение срока

Активный статус

Когда status равен active:

• Расчет истечения срока:
  • Если expire_duration > 0: expire = now + expire_duration
  • Если expire_duration = 0: expire = 0 (неограниченно)

Пример:

Template: status = "active", expire_duration = 2592000 (30 дней)
User created: 2024-01-01 00:00:00
Result: expire = 2024-01-31 00:00:00

Статус On Hold

Когда status равен on_hold:

• Истечение срока: Всегда устанавливается в 0 (неограниченно)
• Продолжительность истечения On Hold: Использует expire_duration как on_hold_expire_duration
• Таймаут On Hold:
  • Если on_hold_timeout установлен: on_hold_timeout = now + on_hold_timeout
  • Если on_hold_timeout не установлен: on_hold_timeout = null

Пример:

Template: 
  status = "on_hold"
  expire_duration = 2592000 (30 дней)
  on_hold_timeout = 3600 (1 час)

User created: 2024-01-01 00:00:00
Result:
  expire = 0 (неограниченно)
  on_hold_expire_duration = 2592000
  on_hold_timeout = 2024-01-01 01:00:00 (становится активным через 1 час)

Лимит данных и стратегия сброса

Лимит данных

• Формат: Байты (целое число)
• По умолчанию: 0 (неограниченно)
• Применяется к: Полю data_limit пользователя

Примеры:

• 1073741824 = 1 GB
• 5368709120 = 5 GB
• 0 = Неограниченно

Стратегия сброса

Управляет тем, как сбрасывается лимит данных (применяется только если data_limit > 0):

Поведение:

• При сбросе used_traffic пользователя сбрасывается до 0
• Время сброса рассчитывается от времени создания пользователя
• Логи сброса поддерживаются в UserUsageResetLogs

Пример:

Template:
  data_limit = 1073741824 (1 GB)
  data_limit_reset_strategy = "month"

User created: 2024-01-01
Result:
  - Пользователь имеет лимит 1 GB
  - Лимит сбрасывается 2024-01-31, 2024-03-01 и т.д.

Создание пользователей из шаблонов

Создание одного пользователя

Endpoint: POST /api/user/from_template

Request:

{
  "user_template_id": 1,
  "username": "john",
  "note": "Premium customer"
}

Процесс:

1. Шаблон валидируется (существует, не отключен)
2. Базовые поля загружаются из шаблона
3. Имя пользователя строится: prefix + "john" + suffix
4. Применяются дополнительные настройки
5. Пользователь создается со всеми значениями шаблона

Response: Объект пользователя со всеми примененными настройками

Что применяется

Все поля шаблона применяются к новому пользователю:

• ✅ Группы из group_ids
• ✅ Лимит данных из data_limit
• ✅ Истечение срока из expire_duration (рассчитано)
• ✅ Статус из status
• ✅ Стратегия сброса лимита данных
• ✅ Поток VLESS (если установлен в extra_settings)
• ✅ Метод Shadowsocks (если установлен в extra_settings)
• ✅ Таймаут on hold (если статус on_hold)

Изменение пользователей с помощью шаблонов

Применение шаблона к существующему пользователю

Endpoint: PUT /api/user/{username}/from_template

Request:

{
  "user_template_id": 2,
  "note": "Updated to premium plan"
}

Процесс:

1. Шаблон валидируется (существует, не отключен)
2. Базовые поля загружаются из шаблона
3. Существующие proxy_settings пользователя сохраняются
4. Поля шаблона применяются (переопределяют текущие значения пользователя)
5. Если reset_usages равен true, использование данных пользователя сбрасывается
6. Пользователь обновляется

Что применяется

При изменении пользователя с помощью шаблона:

• ✅ Группы из group_ids (заменяет группы пользователя)
• ✅ Лимит данных из data_limit
• ✅ Истечение срока из expire_duration (пересчитывается)
• ✅ Статус из status
• ✅ Стратегия сброса лимита данных
• ✅ Поток VLESS (если установлен в extra_settings)
• ✅ Метод Shadowsocks (если установлен в extra_settings)
• ✅ Таймаут on hold (если статус on_hold)
• ✅ Сброс использования данных (если reset_usages равен true)

Что не меняется:

• ❌ Имя пользователя (не может быть изменено)
• ❌ Структура настроек прокси (обновляются только flow/method)
• ❌ Дата создания пользователя
• ❌ Администратор пользователя (кто их создал)

Флаг Reset Usages

Когда reset_usages равен true в шаблоне:

• used_traffic пользователя сбрасывается до 0
• История использования очищается
• Создается запись лога сброса

Случай использования: При обновлении пользователя до нового плана вы можете захотеть сбросить их использование.

Массовое создание пользователей

Обзор

Массовое создание пользователей позволяет создавать несколько пользователей из шаблона одновременно с автоматической генерацией имен пользователей.

Endpoint: POST /api/users/bulk/from_template

Возможности:

• Создание до 500 пользователей одновременно
• Автоматическая генерация имен пользователей
• Две стратегии генерации имен пользователей
• URL подписок возвращаются для всех созданных пользователей

Стратегии генерации имен пользователей

{
  "user_template_id": 1,
  "count": 10,
  "strategy": "random",
  "username": null,
  "note": "Bulk created users"
}

{
  "user_template_id": 1,
  "count": 10,
  "strategy": "sequence",
  "username": "user",
  "start_number": 1,
  "note": "Sequential users"
}

Base: "user", start: 1 → "user1", "user2", "user3"
Base: "user10", start: 1 → "user11", "user12", "user13" (10 игнорируется)
Base: "test", start: 100 → "test100", "test101", "test102"

Префикс/суффикс имени пользователя при массовом создании

username_prefix и username_suffix шаблона применяются к всем сгенерированным именам пользователей:

Пример:

Template: prefix = "premium_", suffix = "_vip"
Strategy: sequence, base = "user", start = 1

Generated usernames:
  "premium_user1_vip"
  "premium_user2_vip"
  "premium_user3_vip"

Процесс массового создания

1. Валидация шаблона - Шаблон существует и не отключен
2. Валидация стратегии - Проверяются правила стратегии имени пользователя
3. Генерация имен пользователей - Имена пользователей генерируются на основе стратегии
4. Фильтрация дубликатов - Существующие имена пользователей фильтруются
5. Создание пользователей - Все пользователи создаются с настройками шаблона
6. URL подписок - URL генерируются для всех созданных пользователей

Response

{
  "subscription_urls": [
    "https://example.com/sub/user1?token=...",
    "https://example.com/sub/user2?token=..."
  ],
  "created": 10
}

Ограничения

• Максимальное количество: 500 пользователей на запрос
• Минимальное количество: 1 пользователь
• Уникальность имени пользователя: Дублирующиеся имена пользователей автоматически пропускаются
• Валидация шаблона: Шаблон должен существовать и не быть отключенным

Правила валидации и ограничения

Валидация имени

Валидация Group IDs

Валидация префикса/суффикса имени пользователя

Валидация статуса

Валидация лимита данных

Валидация продолжительности истечения срока

Валидация отключенного шаблона

API Endpoints

Создать шаблон

Endpoint: POST /api/user_template

Authentication: Требуется sudo администратор

Request Body:

{
  "name": "Premium Plan",
  "data_limit": 1073741824,
  "expire_duration": 2592000,
  "username_prefix": "premium_",
  "username_suffix": "_vip",
  "group_ids": [1, 2],
  "status": "active",
  "data_limit_reset_strategy": "month",
  "extra_settings": {
    "flow": "xtls-rprx-vision",
    "method": "aes-256-gcm"
  },
  "is_disabled": false
}

Response:

{
  "id": 1,
  "name": "Premium Plan",
  "data_limit": 1073741824,
  "expire_duration": 2592000,
  "username_prefix": "premium_",
  "username_suffix": "_vip",
  "group_ids": [1, 2],
  "status": "active",
  "data_limit_reset_strategy": "month",
  "extra_settings": {
    "flow": "xtls-rprx-vision",
    "method": "aes-256-gcm"
  },
  "is_disabled": false
}

Получить все шаблоны

Endpoint: GET /api/user_templates

Authentication: Требуется администратор

Query Parameters:

• offset (необязательно): Смещение пагинации
• limit (необязательно): Лимит пагинации

Response:

[
  {
    "id": 1,
    "name": "Premium Plan",
    "group_ids": [1, 2],
    ...
  }
]

Получить шаблон по ID

Endpoint: GET /api/user_template/{template_id}

Authentication: Требуется администратор

Response: То же, что и ответ создания шаблона

Изменить шаблон

Endpoint: PUT /api/user_template/{template_id}

Authentication: Требуется sudo администратор

Request Body: Те же поля, что и при создании (все необязательны)

Response: Обновленный шаблон

Удалить шаблон

Endpoint: DELETE /api/user_template/{template_id}

Authentication: Требуется sudo администратор

Response: 204 No Content

Создать пользователя из шаблона

Endpoint: POST /api/user/from_template

Authentication: Требуется администратор

Request Body:

{
  "user_template_id": 1,
  "username": "john",
  "note": "Premium customer"
}

Response: Объект пользователя

Изменить пользователя с помощью шаблона

Endpoint: PUT /api/user/{username}/from_template

Authentication: Требуется администратор

Request Body:

{
  "user_template_id": 2,
  "note": "Upgraded to premium"
}

Response: Обновленный объект пользователя

Массовое создание пользователей из шаблона

Endpoint: POST /api/users/bulk/from_template

Authentication: Требуется администратор

Request Body:

{
  "user_template_id": 1,
  "count": 10,
  "strategy": "random",
  "username": null,
  "note": "Bulk created"
}

Response:

{
  "subscription_urls": ["..."],
  "created": 10
}

Распространенные сценарии

POST /api/user_template
{
  "name": "Premium Plan",
  "data_limit": 1073741824,
  "expire_duration": 2592000,
  "group_ids": [1],
  "status": "active"
}

{
  "name": "Premium Plan",
  "username_prefix": "premium_",
  "group_ids": [1]
}

{
  "name": "Advanced Plan",
  "group_ids": [1],
  "extra_settings": {
    "flow": "xtls-rprx-vision",
    "method": "aes-256-gcm"
  }
}

{
  "name": "Trial Plan",
  "status": "on_hold",
  "expire_duration": 2592000,
  "on_hold_timeout": 3600,
  "group_ids": [1]
}

{
  "name": "Monthly Plan",
  "data_limit": 5368709120,
  "data_limit_reset_strategy": "month",
  "group_ids": [1]
}

POST /api/user/from_template
{
  "user_template_id": 1,
  "username": "john",
  "note": "New customer"
}

POST /api/users/bulk/from_template
{
  "user_template_id": 1,
  "count": 50,
  "strategy": "random",
  "username": null
}

POST /api/users/bulk/from_template
{
  "user_template_id": 1,
  "count": 100,
  "strategy": "sequence",
  "username": "user",
  "start_number": 1
}

PUT /api/user/john/from_template
{
  "user_template_id": 2,
  "note": "Upgraded to premium"
}

// Сначала обновите шаблон, чтобы включить reset_usages
PUT /api/user_template/2
{
  "reset_usages": true
}

// Затем примените шаблон к пользователю
PUT /api/user/john/from_template
{
  "user_template_id": 2
}

PUT /api/user_template/1
{
  "is_disabled": true
}

{
  "name": "Multi-Group Plan",
  "group_ids": [1, 2, 3],
  "data_limit": 1073741824
}

{
  "name": "Unlimited Plan",
  "data_limit": 0,
  "expire_duration": 0,
  "group_ids": [1]
}

{
  "name": "VIP Plan",
  "username_prefix": "premium_",
  "username_suffix": "_vip",
  "group_ids": [1]
}

Резюме

• ✅ Шаблоны — это чертежи - Они предоставляют значения по умолчанию для создания пользователей
• ✅ Все поля применяются - Настройки шаблона переопределяют значения по умолчанию при создании пользователей
• ✅ Префикс/суффикс имени пользователя - Автоматически добавляются к именам пользователей
• ✅ Дополнительные настройки - Применяют настройки, специфичные для протокола (flow, method)
• ✅ Назначение группы - Пользователи автоматически присоединяются к группам шаблона
• ✅ Обработка статуса - Поддерживает active и on_hold с таймаутом
• ✅ Расчет истечения срока - Автоматически рассчитывается из expire_duration
• ✅ Сброс лимита данных - Настраиваемые стратегии сброса
• ✅ Массовое создание - Создание до 500 пользователей с автоматической генерацией имен пользователей
• ✅ Отключенные шаблоны - Нельзя использовать до повторного включения
• ✅ Изменение пользователя - Применение шаблонов к существующим пользователям
• ✅ Сброс использования - Опция сброса использования данных при изменении пользователей

Для получения дополнительной информации о:

• Группах: См. groups.mdx
• Хостах: См. hosts.mdx
• Конфигурации XRay: См. xray.mdx