مستندات گروه‌ها

این سند نحوه کار گروه‌ها در PasarGuard را توضیح می‌دهد. گروه‌ها مکانیزم اصلی برای کنترل اینکه کاربران به کدام inboundها (و در نتیجه کدام hostها) در اشتراک‌های خود دسترسی دارند، هستند. این سند برای کمک به مبتدیان در درک مدیریت گروه‌ها، روابط و کنترل دسترسی طراحی شده است.

فهرست مطالب

1. نمای کلی
2. مبانی پیکربندی گروه
3. نحوه کار گروه‌ها
4. روابط
5. کنترل دسترسی Inbound
6. مدیریت گروه
7. عملیات دسته‌ای
8. قوانین اعتبارسنجی و محدودیت‌ها
9. نقاط پایانی API
10. سناریوهای رایج

نمای کلی

گروه‌ها در PasarGuard مکانیزم‌های کنترل دسترسی هستند که:

• اتصال کاربران به inboundها - گروه‌ها تعیین می‌کنند که کاربران به کدام تگ‌های inbound دسترسی دارند
• کنترل نمایش host - کاربران فقط hostهایی را می‌بینند که inbound_tag آنها در گروه‌هایشان است
• فعال‌سازی مدیریت دسته‌ای - اختصاص گروه‌ها به چندین کاربر به یکباره
• پشتیبانی از قالب‌ها - قالب‌های کاربری می‌توانند به گروه‌ها اختصاص داده شوند تا اختصاص خودکار گروه انجام شود

جریان گروه

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

نحوه کار:

1. کاربران به گروه‌ها اختصاص داده می‌شوند (رابطه چند به چند)
2. گروه‌ها تگ‌های inbound به آن‌ها اختصاص داده می‌شوند (رابطه چند به چند)
3. هنگام تولید اشتراک، PasarGuard تمام تگ‌های inbound را از تمام گروه‌های کاربر جمع‌آوری می‌کند
4. فقط hostهایی که inbound_tag آنها با یکی از این inboundهای قابل دسترسی مطابقت دارد در اشتراک ظاهر می‌شوند

مبانی پیکربندی گروه

فیلدهای الزامی

هر گروه باید داشته باشد:

فیلدهای اختیاری

فیلدهای پاسخ گروه

هنگام دریافت گروه‌ها، همچنین دریافت می‌کنید:

نحوه کار گروه‌ها

مفهوم پایه

گروه‌ها به عنوان ظروف مجوز عمل می‌کنند که به کاربران دسترسی به inboundهای خاص می‌دهند. اینطور فکر کنید:

• Group = مجموعه مجوز
• Inbound Tags = آنچه گروه اجازه دسترسی به آن را می‌دهد
• Users = کسانی که مجوزها را دریافت می‌کنند

جریان مثال

1. ایجاد گروه "Premium" با inbound_tags: ["vless-443", "trojan-8443"]
2. اختصاص کاربر "john" به گروه "Premium"
3. وقتی "john" اشتراک را درخواست می‌کند:
   - سیستم جمع‌آوری می‌کند: ["vless-443", "trojan-8443"] (از گروه Premium)
   - فقط hostهایی با inbound_tag مطابق با این‌ها ظاهر می‌شوند
   - Host با inbound_tag "vmess-8080" ظاهر نمی‌شود (در گروه نیست)

گروه‌های غیرفعال

وقتی یک گروه is_disabled: true دارد:

• گروه از محاسبات دسترسی inbound حذف می‌شود
• کاربران در گروه‌های غیرفعال دسترسی خود را از دست می‌دهند به آن inboundها
• گروه همچنان وجود دارد و می‌تواند دوباره فعال شود

مثال:

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"

کاربر به تمام inboundهای تمام گروه‌ها دسترسی دارد (اگر فعال باشند)

رابطه Group ↔ Inbound

• چند به چند: گروه‌ها می‌توانند چندین inbound داشته باشند، inboundها می‌توانند در چندین گروه باشند
• جدول ارتباط: inbounds_groups_association
• تگ‌های Inbound: گروه‌ها inboundها را با tag آنها (نه ID) ارجاع می‌دهند

مثال:

Group "Premium" دارد:
  - inbound_tag: "vless-443"
  - inbound_tag: "trojan-8443"
  - inbound_tag: "vmess-8080"

تمام کاربران در "Premium" می‌توانند به hostهایی با این تگ‌های inbound دسترسی داشته باشند

رابطه Group ↔ UserTemplate

• چند به چند: گروه‌ها می‌توانند به قالب‌های کاربری اختصاص داده شوند
• هدف: هنگام ایجاد کاربران از قالب‌ها، آن‌ها به طور خودکار به گروه‌های قالب اختصاص داده می‌شوند
• جدول ارتباط: template_group_association

مثال:

UserTemplate "Basic Plan" دارد:
  - Group "Standard"
  - Group "Free"

کاربران جدید ایجاد شده از این قالب به طور خودکار به هر دو گروه می‌پیوندند

کنترل دسترسی Inbound

نحوه محاسبه دسترسی Inbound

وقتی یک کاربر اشتراک را درخواست می‌کند، PasarGuard:

1. تمام گروه‌ها را که کاربر به آن‌ها تعلق دارد جمع‌آوری می‌کند
2. گروه‌های غیرفعال را فیلتر می‌کند
3. تمام تگ‌های inbound را از گروه‌های فعال جمع‌آوری می‌کند
4. تگ‌های inbound را یکتا می‌کند (کاربر ممکن است همان inbound را از چندین گروه داشته باشد)
5. از این لیست استفاده می‌کند تا فیلتر کند کدام hostها در اشتراک ظاهر می‌شوند

جریان کد

# کد شبه از آنچه اتفاق می‌افتد
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)

# حالا hostها را فیلتر کن
for host in all_hosts:
    if host.inbound_tag in accessible_inbounds:
        # در اشتراک شامل کن
        pass

مثال‌های دسترسی

User "john" → Group "Premium" → ["vless-443", "trojan-8443"]
نتیجه: کاربر می‌تواند hostهایی با inbound_tag "vless-443" یا "trojan-8443" را ببیند

User "john" → 
  - Group "Premium" → ["vless-443"]
  - Group "Standard" → ["vmess-8080", "vless-443"]
  
نتیجه: کاربر می‌تواند hostهایی با inbound_tag "vless-443" یا "vmess-8080" را ببیند
نکته: "vless-443" در هر دو گروه ظاهر می‌شود اما یکتا می‌شود

User "john" →
  - Group "Premium" (غیرفعال) → ["vless-443"]
  - Group "Standard" (فعال) → ["vmess-8080"]
  
نتیجه: کاربر فقط می‌تواند hostهایی با inbound_tag "vmess-8080" را ببیند
نکته: گروه Premium نادیده گرفته می‌شود چون غیرفعال است

User "john" → هیچ گروهی اختصاص داده نشده
نتیجه: کاربر هیچ hostی در اشتراک نمی‌بیند (اشتراک خالی)

مدیریت گروه

ایجاد گروه‌ها

هنگام ایجاد یک گروه:

1. اعتبارسنجی نام: باید 3-64 کاراکتر باشد، فقط a-z و 0-9
2. اعتبارسنجی Inbound: تمام تگ‌های inbound باید در پیکربندی‌های هسته XRay وجود داشته باشند
3. یکتایی: نام گروه باید منحصر به فرد باشد
4. ایجاد خودکار: تگ‌های inbound به طور خودکار در پایگاه داده ایجاد می‌شوند اگر وجود نداشته باشند

مثال:

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

اعتبارسنجی:

• ✅ نام معتبر است (3-64 کاراکتر)
• ✅ تمام تگ‌های inbound در پیکربندی‌های هسته وجود دارند

تغییر گروه‌ها

هنگام تغییر یک گروه:

1. نام می‌تواند تغییر کند (باید همچنان منحصر به فرد باشد)
2. تگ‌های inbound می‌توانند به‌روزرسانی شوند (همه باید در پیکربندی‌های هسته وجود داشته باشند)
3. می‌تواند غیرفعال/فعال شود
4. تگ‌های inbound می‌توانند پاک شوند (به لیست خالی/null تنظیم شوند)
5. کاربران به طور خودکار به‌روزرسانی می‌شوند - کاربران فعال و on_hold پیکربندی‌های node خود را به‌روزرسانی می‌کنند

مثال:

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

چه اتفاقی می‌افتد:

• نام گروه تغییر می‌کند
• تگ‌های inbound به‌روزرسانی می‌شوند
• تمام کاربران در این گروه پیکربندی‌های node به‌روزرسانی شده را دریافت می‌کنند
• اشتراک‌های آن‌ها اکنون شامل hostهایی با تگ‌های inbound جدید می‌شود

حذف گروه‌ها

هنگام حذف یک گروه:

1. گروه از پایگاه داده حذف می‌شود
2. ارتباط‌های کاربر حذف می‌شوند (کاربران دیگر در این گروه نیستند)
3. کاربران به‌روزرسانی می‌شوند - تمام کاربران تأثیرگذار پیکربندی‌های node خود را به‌روزرسانی می‌کنند
4. ارتباط‌های inbound حذف می‌شوند (اما خود inboundها باقی می‌مانند)

مثال:

قبل از حذف:
  User "john" → Group "Premium" → ["vless-443"]
  User "john" → Group "Standard" → ["vless-443", "vmess-8080"]
  
حذف Group "Premium":
  User "john" → Group "Standard" → ["vless-443", "vmess-8080"]
  
نتیجه: کاربر همچنان به هر دو inbound دسترسی دارد (از طریق گروه 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]
}

رفتار:

• مشابه افزودن دسته‌ای، اما ارتباط‌های گروه را حذف می‌کند
• فقط ارتباط‌های موجود حذف می‌شوند
• کاربران دسترسی خود را به inboundهایی که فقط در گروه‌های حذف شده بودند از دست می‌دهند

مثال:

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

نتیجه: کاربران 10 و 11 گروه 1 را از دست می‌دهند (و دسترسی به inboundهای آن)

قوانین اعتبارسنجی و محدودیت‌ها

اعتبارسنجی نام

اعتبارسنجی تگ‌های Inbound

فرآیند اعتبارسنجی:

1. هنگام ایجاد: تمام تگ‌های inbound در برابر پیکربندی‌های هسته XRay اعتبارسنجی می‌شوند
2. هنگام تغییر: اگر inbound_tags ارائه شود، همه اعتبارسنجی می‌شوند
3. ایجاد خودکار: تگ‌های inbound به طور خودکار در پایگاه داده ایجاد می‌شوند اگر در پیکربندی‌های هسته وجود داشته باشند

مثال:

پیکربندی هسته inboundها دارد: ["vless-443", "trojan-8443"]

گروه معتبر:
  inbound_tags: ["vless-443", "trojan-8443"] ✅

گروه نامعتبر:
  inbound_tags: ["vmess-8080"] ❌ (در پیکربندی هسته نیست)

اعتبارسنجی وضعیت گروه

• گروه‌های غیرفعال از محاسبات دسترسی حذف می‌شوند
• گروه‌های حذف شده تمام ارتباط‌های کاربر را حذف می‌کنند
• inbound_tags خالی (در تغییر) به معنای عدم اعطای دسترسی توسط گروه است

نقاط پایانی API

ایجاد گروه

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 را کنترل می‌کنند - کاربران فقط hostهایی را می‌بینند که inbound_tag آنها در گروه‌هایشان است
• ✅ رابطه‌های چند به چند - کاربران می‌توانند در چندین گروه باشند، گروه‌ها می‌توانند چندین inbound داشته باشند
• ✅ گروه‌های غیرفعال حذف می‌شوند - کاربران دسترسی خود را از دست می‌دهند وقتی گروه‌هایشان غیرفعال می‌شوند
• ✅ محدودیت‌های نام - 3-64 کاراکتر
• ✅ اعتبارسنجی Inbound - تمام تگ‌های inbound باید در پیکربندی‌های هسته XRay وجود داشته باشند
• ✅ به‌روزرسانی‌های خودکار - پیکربندی‌های node کاربر هنگام تغییر/حذف گروه‌ها به‌روزرسانی می‌شوند
• ✅ عملیات دسته‌ای - مدیریت کارآمد اختصاص گروه‌ها برای چندین کاربر
• ✅ گروه‌های خالی - گروه‌هایی با هیچ inbound دسترسی نمی‌دهند
• ✅ یکپارچه‌سازی قالب - قالب‌های کاربری می‌توانند به طور خودکار گروه‌ها را اختصاص دهند
• ✅ دسترسی تجمعی است - کاربران به inboundهای تمام گروه‌های فعال خود دسترسی دارند

برای اطلاعات بیشتر درباره:

• نحوه استفاده hostها از تگ‌های inbound: hosts.md را ببینید
• پیکربندی XRay: xray.md را ببینید