Документация по группам

Этот документ объясняет, как работают группы в PasarGuard. Группы являются основным механизмом для контроля того, к каким входящим соединениям (и, следовательно, к каким хостам) пользователи могут получить доступ в своих подписках. Он разработан, чтобы помочь новичкам понять управление группами, отношения и контроль доступа.

Содержание

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

Обзор

Группы в PasarGuard — это механизмы контроля доступа, которые:

• Подключают пользователей к входящим соединениям - Группы определяют, к каким тегам входящих соединений пользователи могут получить доступ
• Контролируют видимость хостов - Пользователи видят только хосты, чей inbound_tag находится в их группах
• Включают массовое управление - Назначение групп нескольким пользователям одновременно
• Поддерживают шаблоны - Шаблоны пользователей могут быть назначены группам для автоматического назначения групп

Поток группы

User → Groups → Inbound Tags → Hosts (in subscriptions)

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

1. Пользователи назначаются в группы (отношение многие-ко-многим)
2. Группам назначаются теги входящих соединений (отношение многие-ко-многим)
3. При генерации подписки PasarGuard собирает все теги входящих соединений из всех групп пользователя
4. В подписке появляются только хосты, чей inbound_tag соответствует одному из этих доступных входящих соединений

Основы конфигурации группы

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

Каждая группа должна иметь:

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

Поля ответа группы

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

Как работают группы

Основная концепция

Группы действуют как контейнеры разрешений, которые предоставляют пользователям доступ к определенным входящим соединениям. Думайте об этом так:

• Group = Набор разрешений
• Inbound Tags = К чему группа разрешает доступ
• Users = Кто получает разрешения

Пример потока

1. Создать группу "Premium" с inbound_tags: ["vless-443", "trojan-8443"]
2. Назначить пользователя "john" в группу "Premium"
3. Когда "john" запрашивает подписку:
   - Система собирает: ["vless-443", "trojan-8443"] (из группы Premium)
   - Появляются только хосты с inbound_tag, соответствующим этим
   - Хост с inbound_tag "vmess-8080" не появится (не в группе)

Отключенные группы

Когда у группы is_disabled: true:

• Группа исключается из расчетов доступа к входящим соединениям
• Пользователи в отключенных группах теряют доступ к этим входящим соединениям
• Группа все еще существует и может быть повторно включена

Пример:

User "john" находится в:
  - Group "Premium" (отключена) с ["vless-443"]
  - Group "Standard" (включена) с ["vmess-8080"]

Результат: Пользователь имеет доступ только к ["vmess-8080"]

Отношения

Отношение User ↔ Group

• Многие-ко-многим: Пользователи могут принадлежать нескольким группам, группы могут иметь несколько пользователей
• Таблица ассоциации: users_groups_association
• Без ограничений: Пользователь может быть в неограниченном количестве групп

Пример:

User "john" принадлежит:
  - Group "Premium"
  - Group "Standard"
  - Group "VIP"

Пользователь получает доступ ко ВСЕМ входящим соединениям из ВСЕХ групп (если включены)

Отношение Group ↔ Inbound

• Многие-ко-многим: Группы могут иметь несколько входящих соединений, входящие соединения могут быть в нескольких группах
• Таблица ассоциации: inbounds_groups_association
• Теги входящих соединений: Группы ссылаются на входящие соединения по их tag (не ID)

Пример:

Group "Premium" имеет:
  - inbound_tag: "vless-443"
  - inbound_tag: "trojan-8443"
  - inbound_tag: "vmess-8080"

Все пользователи в "Premium" могут получить доступ к хостам с этими тегами входящих соединений

Отношение Group ↔ UserTemplate

• Многие-ко-многим: Группы могут быть назначены шаблонам пользователей
• Цель: При создании пользователей из шаблонов они автоматически назначаются в группы шаблона
• Таблица ассоциации: template_group_association

Пример:

UserTemplate "Basic Plan" имеет:
  - Group "Standard"
  - Group "Free"

Новые пользователи, созданные из этого шаблона, автоматически присоединяются к обеим группам

Контроль доступа к входящим соединениям

Как рассчитывается доступ к входящим соединениям

Когда пользователь запрашивает подписку, PasarGuard:

1. Собирает все группы, к которым принадлежит пользователь
2. Фильтрует отключенные группы
3. Собирает все теги входящих соединений из включенных групп
4. Удаляет дубликаты тегов входящих соединений (пользователь может иметь одно и то же входящее соединение из нескольких групп)
5. Использует этот список для фильтрации того, какие хосты появляются в подписке

Поток кода

# Псевдокод того, что происходит
user_groups = user.groups  # Получить все группы пользователя
enabled_groups = [g for g in user_groups if not g.is_disabled]
accessible_inbounds = set()
for group in enabled_groups:
    accessible_inbounds.update(group.inbound_tags)

# Теперь фильтруем хосты
for host in all_hosts:
    if host.inbound_tag in accessible_inbounds:
        # Включить в подписку
        pass

Примеры доступа

User "john" → Group "Premium" → ["vless-443", "trojan-8443"]
Результат: Пользователь может видеть хосты с inbound_tag "vless-443" или "trojan-8443"

User "john" → 
  - Group "Premium" → ["vless-443"]
  - Group "Standard" → ["vmess-8080", "vless-443"]
  
Результат: Пользователь может видеть хосты с inbound_tag "vless-443" или "vmess-8080"
Примечание: "vless-443" появляется в обеих группах, но дубликаты удаляются

User "john" →
  - Group "Premium" (отключена) → ["vless-443"]
  - Group "Standard" (включена) → ["vmess-8080"]
  
Результат: Пользователь может видеть ТОЛЬКО хосты с inbound_tag "vmess-8080"
Примечание: Группа Premium игнорируется, потому что она отключена

User "john" → Группы не назначены
Результат: Пользователь не видит хостов в подписке (пустая подписка)

Управление группами

Создание групп

При создании группы:

1. Валидация имени: Должно быть 3-64 символа, только a-z и 0-9
2. Валидация входящих соединений: Все теги входящих соединений должны существовать в конфигурациях ядра XRay
3. Уникальность: Имя группы должно быть уникальным
4. Автоматическое создание: Теги входящих соединений автоматически создаются в базе данных, если они не существуют

Пример:

POST /api/group
{
  "name": "premium",
  "inbound_tags": ["vless-443", "trojan-8443"],
  "is_disabled": false
}

Валидация:

• ✅ Имя валидно (3-64 символа)
• ✅ Все теги входящих соединений существуют в конфигурациях ядра

Изменение групп

При изменении группы:

1. Имя может быть изменено (должно оставаться уникальным)
2. Теги входящих соединений могут быть обновлены (все должны существовать в конфигурациях ядра)
3. Может быть отключена/включена
4. Теги входящих соединений могут быть очищены (установлены в пустой список/null)
5. Пользователи автоматически обновляются - Активные и on_hold пользователи получают обновленные конфигурации узлов

Пример:

PUT /api/group/1
{
  "name": "premium-v2",
  "inbound_tags": ["vless-443", "trojan-8443", "vmess-8080"],
  "is_disabled": false
}

Что происходит:

• Имя группы изменяется
• Теги входящих соединений обновляются
• Все пользователи в этой группе получают обновленные конфигурации узлов
• Их подписки теперь включают хосты с новыми тегами входящих соединений

Удаление групп

При удалении группы:

1. Группа удаляется из базы данных
2. Ассоциации пользователей удаляются (пользователи больше не в этой группе)
3. Пользователи обновляются - Все затронутые пользователи получают обновленные конфигурации узлов
4. Ассоциации входящих соединений удаляются (но сами входящие соединения остаются)

Пример:

Перед удалением:
  User "john" → Group "Premium" → ["vless-443"]
  User "john" → Group "Standard" → ["vless-443", "vmess-8080"]
  
Удалить Group "Premium":
  User "john" → Group "Standard" → ["vless-443", "vmess-8080"]
  
Результат: Пользователь все еще имеет доступ к обоим входящим соединениям (через группу Standard)

Массовые операции

PasarGuard поддерживает массовые операции для эффективного управления назначением групп.

Массовое добавление групп пользователям

Добавьте одну или несколько групп нескольким пользователям одновременно.

Endpoint: POST /api/groups/bulk/add

Request Body:

{
  "group_ids": [1, 2, 3],
  "users": [10, 11, 12],
  "admins": [5, 6],
  "has_group_ids": [4]
}

Поведение:

• Если указан users: Добавить группы этим конкретным пользователям
• Если указан admins: Добавить группы всем пользователям, созданным этими администраторами
• Если ни users, ни admins не указаны: Добавить группы ВСЕМ пользователям
• has_group_ids: Фильтровать только пользователей, которые уже имеют эти группы
• Существующие ассоциации игнорируются (дубликаты не создаются)

{
  "group_ids": [1, 2],
  "users": [10, 11, 12]
}

{
  "group_ids": [1],
  "admins": [5]
}

{
  "group_ids": [1, 2]
}

{
  "group_ids": [2],
  "has_group_ids": [1]
}

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

Удалите одну или несколько групп у нескольких пользователей одновременно.

Endpoint: POST /api/groups/bulk/remove

Request Body:

{
  "group_ids": [1, 2, 3],
  "users": [10, 11, 12],
  "admins": [5, 6],
  "has_group_ids": [4]
}

Поведение:

• Аналогично массовому добавлению, но удаляет ассоциации групп
• Удаляются только существующие ассоциации
• Пользователи теряют доступ к входящим соединениям, которые были только в удаленных группах

Пример:

{
  "group_ids": [1],
  "users": [10, 11]
}

Результат: Пользователи 10 и 11 теряют группу 1 (и доступ к её входящим соединениям)

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

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

Валидация тегов входящих соединений

Процесс валидации:

1. При создании: Все теги входящих соединений проверяются на соответствие конфигурациям ядра XRay
2. При изменении: Если указаны inbound_tags, все проверяются
3. Автоматическое создание: Теги входящих соединений автоматически создаются в базе данных, если они существуют в конфигурациях ядра

Пример:

Конфигурация ядра имеет входящие соединения: ["vless-443", "trojan-8443"]

Валидная группа:
  inbound_tags: ["vless-443", "trojan-8443"] ✅

Невалидная группа:
  inbound_tags: ["vmess-8080"] ❌ (не в конфигурации ядра)

Валидация состояния группы

• Отключенные группы исключаются из расчетов доступа
• Удаленные группы удаляют все ассоциации пользователей
• Пустые inbound_tags (при изменении) означает, что группа не предоставляет доступ

API Endpoints

Создать группу

Endpoint: POST /api/group

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

Request Body:

{
  "name": "premium",
  "inbound_tags": ["vless-443", "trojan-8443"],
  "is_disabled": false
}

Response:

{
  "id": 1,
  "name": "premium",
  "inbound_tags": ["vless-443", "trojan-8443"],
  "is_disabled": false,
  "total_users": 0
}

Получить все группы

Endpoint: GET /api/groups

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

Query Parameters:

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

Response:

{
  "groups": [
    {
      "id": 1,
      "name": "premium",
      "inbound_tags": ["vless-443"],
      "is_disabled": false,
      "total_users": 5
    }
  ],
  "total": 1
}

Получить группу по ID

Endpoint: GET /api/group/{group_id}

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

Response:

{
  "id": 1,
  "name": "premium",
  "inbound_tags": ["vless-443", "trojan-8443"],
  "is_disabled": false,
  "total_users": 10
}

Изменить группу

Endpoint: PUT /api/group/{group_id}

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

Request Body:

{
  "name": "premium-v2",
  "inbound_tags": ["vless-443", "trojan-8443", "vmess-8080"],
  "is_disabled": false
}

Response: То же, что и получить группу по ID

Удалить группу

Endpoint: DELETE /api/group/{group_id}

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

Response: 204 No Content

Массовое добавление групп

Endpoint: POST /api/groups/bulk/add

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

Request Body:

{
  "group_ids": [1, 2],
  "users": [10, 11, 12],
  "admins": [5],
  "has_group_ids": [3]
}

Response:

{
  "detail": "operation has been successfuly done on 15 users"
}

Массовое удаление групп

Endpoint: POST /api/groups/bulk/remove

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

Request Body: То же, что и массовое добавление

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

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

POST /api/group
{
  "name": "premium",
  "inbound_tags": ["vless-443", "trojan-8443"],
  "is_disabled": false
}

PUT /api/user/john
{
  "group_ids": [1, 2]
}

PUT /api/group/1
{
  "inbound_tags": ["vless-443", "trojan-8443", "vmess-8080"]
}

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

POST /api/groups/bulk/add
{
  "group_ids": [1]
}

POST /api/groups/bulk/add
{
  "group_ids": [1],
  "admins": [5]
}

// Создать группу Free
POST /api/group
{
  "name": "free",
  "inbound_tags": ["vmess-8080"]
}

// Создать группу Standard
POST /api/group
{
  "name": "standard",
  "inbound_tags": ["vmess-8080", "vless-443"]
}

// Создать группу Premium
POST /api/group
{
  "name": "premium",
  "inbound_tags": ["vmess-8080", "vless-443", "trojan-8443"]
}

PUT /api/group/1
{
  "inbound_tags": ["vless-443"]
}

PUT /api/group/1
{
  "inbound_tags": []
}

// Шаг 1: Удалить из Standard
POST /api/groups/bulk/remove
{
  "group_ids": [2],
  "users": [10, 11, 12]
}

// Шаг 2: Добавить в Premium
POST /api/groups/bulk/add
{
  "group_ids": [1],
  "users": [10, 11, 12]
}

POST /api/groups/bulk/add
{
  "group_ids": [2],
  "has_group_ids": [1]
}

PUT /api/user/john
{
  "group_ids": [1, 2, 3]
}

Резюме

• ✅ Группы контролируют доступ к входящим соединениям - Пользователи видят только хосты, чей inbound_tag находится в их группах
• ✅ Отношения многие-ко-многим - Пользователи могут быть в нескольких группах, группы могут иметь несколько входящих соединений
• ✅ Отключенные группы исключаются - Пользователи теряют доступ, когда их группы отключены
• ✅ Ограничения имени - 3-64 символа
• ✅ Валидация входящих соединений - Все теги входящих соединений должны существовать в конфигурациях ядра XRay
• ✅ Автоматические обновления - Конфигурации узлов пользователей обновляются при изменении/удалении групп
• ✅ Массовые операции - Эффективное управление назначением групп для нескольких пользователей
• ✅ Пустые группы - Группы без входящих соединений не предоставляют доступ
• ✅ Интеграция шаблонов - Шаблоны пользователей могут автоматически назначать группы
• ✅ Доступ накапливается - Пользователи получают доступ к входящим соединениям из ВСЕХ своих включенных групп

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

• Как хосты используют теги входящих соединений: См. hosts.md
• Конфигурация XRay: См. xray.md