پاسارگارد
پنل

پیکربندی قالب‌های کاربری

مدیریت قالب‌ها، اعمال فیلدها، ایجاد دسته‌ای کاربران و مستندات API

مستندات قالب‌های کاربری

این سند نحوه کار قالب‌های کاربری در PasarGuard را توضیح می‌دهد. قالب‌ها تنظیمات از پیش پیکربندی شده کاربری هستند که می‌توانند برای ایجاد سریع کاربران با پیکربندی‌های یکنواخت استفاده شوند. این سند برای کمک به مبتدیان در درک مدیریت قالب‌ها، اعمال فیلدها و ایجاد دسته‌ای کاربران طراحی شده است.

فهرست مطالب

  1. نمای کلی
  2. مبانی پیکربندی قالب
  3. توضیح فیلدهای قالب
  4. نحوه کار قالب‌ها
  5. مدیریت نام کاربری
  6. تنظیمات اضافی
  7. وضعیت و انقضا
  8. محدودیت داده و استراتژی بازنشانی
  9. ایجاد کاربران از قالب‌ها
  10. تغییر کاربران با قالب‌ها
  11. ایجاد دسته‌ای کاربران
  12. قوانین اعتبارسنجی و محدودیت‌ها
  13. نقاط پایانی API
  14. سناریوهای رایج

نمای کلی

قالب‌های کاربری در PasarGuard تنظیمات از پیش پیکربندی شده کاربری هستند که:

  • استانداردسازی ایجاد کاربر - اعمال تنظیمات یکنواخت به چندین کاربر
  • سرعت بخشیدن به مدیریت کاربر - ایجاد سریع کاربران بدون پیکربندی هر فیلد
  • پشتیبانی از عملیات دسته‌ای - ایجاد چندین کاربر به یکباره با تولید خودکار نام کاربری
  • فعال‌سازی خودکارسازی - قالب‌ها می‌توانند در گردش‌های کاری خودکار استفاده شوند

جریان قالب

Template → User Creation → Applied Settings

نحوه کار:

  1. ادمین یک قالب با تنظیمات کاربری مورد نظر ایجاد می‌کند
  2. هنگام ایجاد کاربر، ادمین یک قالب را انتخاب می‌کند
  3. فیلدهای قالب به طور خودکار به کاربر جدید اعمال می‌شوند
  4. ادمین فقط باید نام کاربری را ارائه دهد (و به صورت اختیاری یادداشت)
  5. کاربر با تمام تنظیمات قالب ایجاد می‌شود

قالب‌ها الگوها برای ایجاد کاربر هستند. آن‌ها خود کاربر ایجاد نمی‌کنند - آن‌ها مقادیر پیش‌فرض را هنگام ایجاد کاربر ارائه می‌دهند.


مبانی پیکربندی قالب

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

هر قالب باید داشته باشد:

FieldTypeConstraintsDescription
namestringنمی‌تواند خالی باشد، حداکثر 64 کاراکتر، باید منحصر به فرد باشدشناسه/نام قالب
group_idslist[integer]حداقل یک گروه الزامی است (در ایجاد)گروه‌هایی که به کاربران ایجاد شده از این قالب اختصاص داده می‌شوند

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

FieldTypeDefaultDescription
data_limitinteger0 (نامحدود)محدودیت داده به بایت (0 = نامحدود)
expire_durationinteger0 (نامحدود)مدت انقضا به ثانیه (0 = نامحدود)
username_prefixstringnullپیشوند اضافه شده به نام‌های کاربری (حداکثر 20 کاراکتر)
username_suffixstringnullپسوند اضافه شده به نام‌های کاربری (حداکثر 20 کاراکتر)
extra_settingsExtraSettingsnullتنظیمات خاص پروتکل (flow, method)
statusUserStatusCreateactiveوضعیت اولیه کاربر (active یا on_hold)
reset_usagesbooleanfalseبازنشانی استفاده داده هنگام اعمال قالب به کاربر موجود
on_hold_timeoutintegernullتایم‌اوت به ثانیه برای وضعیت on_hold
data_limit_reset_strategyDataLimitResetStrategyno_resetنحوه بازنشانی محدودیت داده
is_disabledbooleanfalseغیرفعال کردن قالب (جلوگیری از استفاده)

فیلدهای پاسخ قالب

هنگام دریافت قالب‌ها، همچنین دریافت می‌کنید:

FieldTypeDescription
idintegerشناسه منحصر به فرد (خودکار تولید می‌شود)

توضیح فیلدهای قالب

فیلدهای پایه

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 ساعت فعال می‌شود)

اعتبارسنجی: اگر status برابر on_hold باشد و expire_duration > 0، پس on_hold_timeout باید تنظیم شود.


محدودیت داده و استراتژی بازنشانی

محدودیت داده

  • فرمت: بایت (عدد صحیح)
  • پیش‌فرض: 0 (نامحدود)
  • اعمال شده به: فیلد data_limit کاربر

مثال‌ها:

  • 1073741824 = 1 GB
  • 5368709120 = 5 GB
  • 0 = نامحدود

استراتژی بازنشانی

کنترل نحوه بازنشانی محدودیت داده (فقط اگر data_limit > 0 اعمال می‌شود):

StrategyDescriptionReset Interval
no_resetهرگز بازنشانی نمی‌شودهرگز
dayروزانه بازنشانی می‌شودهر 24 ساعت
weekهفتگی بازنشانی می‌شودهر 7 روز
monthماهانه بازنشانی می‌شودهر 30 روز
yearسالانه بازنشانی می‌شودهر 365 روز

رفتار:

  • وقتی بازنشانی رخ می‌دهد، 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های اشتراک برای تمام کاربران ایجاد شده برگردانده می‌شوند

استراتژی‌های تولید نام کاربری

Strategy: random

رفتار:

  • نام‌های کاربری تصادفی تولید می‌کند
  • فرمت: 5 کاراکتر الفبایی عددی تصادفی (A-Z, 0-9)
  • مثال: "A3K9M", "X7P2Q"

Request:

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

محدودیت‌ها:

  • username باید null یا خالی باشد
  • start_number نباید ارائه شود

Strategy: sequence

رفتار:

  • نام‌های کاربری ترتیبی تولید می‌کند
  • فرمت: base_username + number
  • مثال: "user1", "user2", "user3"

Request:

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

محدودیت‌ها:

  • username الزامی است
  • start_number اختیاری است (پیش‌فرض 1)
  • اگر نام کاربری پایه به رقم ختم شود، نادیده گرفته می‌شود

مثال‌ها:

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
}

نکته: تعداد created ممکن است کمتر از count باشد اگر برخی نام‌های کاربری از قبل وجود داشته باشند.

محدودیت‌ها

  • حداکثر تعداد: 500 کاربر در هر درخواست
  • حداقل تعداد: 1 کاربر
  • یکتایی نام کاربری: نام‌های کاربری تکراری به طور خودکار رد می‌شوند
  • اعتبارسنجی قالب: قالب باید وجود داشته باشد و غیرفعال نباشد

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

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

RuleConstraintError Message
Requiredنمی‌تواند خالی باشد"name can't be empty"
Lengthحداکثر 64 کاراکترName too long
Uniquenessباید منحصر به فرد باشد"Template by this name already exists"

اعتبارسنجی Group IDs

RuleConstraintError Message
Creationحداقل یکی الزامی است"you must select at least one group"
Existenceتمام IDها باید وجود داشته باشندGroup not found
Modificationمی‌تواند خالی/null باشدهنگام تغییر مجاز است

اعتبارسنجی پیشوند/پسوند نام کاربری

RuleConstraintError Message
Lengthحداکثر 20 کاراکترPrefix/suffix too long
Charactersهمان قوانین نام کاربریInvalid characters

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

RuleConstraintError Message
On Holdاگر on_hold و expire_duration > 0، on_hold_timeout الزامی است"User cannot be on hold without a valid on_hold_expire_duration"
On Holdنمی‌تواند expire داشته باشد وقتی on_hold است"User cannot be on hold with specified expire"

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

RuleConstraintError Message
Minimumباید >= 0 باشدData limit must be 0 or greater

اعتبارسنجی مدت انقضا

RuleConstraintError Message
Minimumباید >= 0 باشدExpire duration must be 0 or greater
Formatثانیه (عدد صحیح)Must be integer

اعتبارسنجی قالب غیرفعال

  • قالب‌های غیرفعال نمی‌توانند برای ایجاد کاربران استفاده شوند
  • قالب‌های غیرفعال نمی‌توانند برای تغییر کاربران استفاده شوند
  • خطا: "this template is disabled"

نقاط پایانی API

ایجاد قالب

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
}

سناریوهای رایج

مشکل: می‌خواهید یک قالب برای کاربران پریمیوم با محدودیت 1 GB و انقضای 30 روزه.

راه‌حل:

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

مشکل: می‌خواهید تمام کاربران از یک قالب پیشوند "premium_" داشته باشند.

راه‌حل:

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

هنگام ایجاد کاربر با نام کاربری "john"، نام کاربری نهایی "premium_john" است.

مشکل: می‌خواهید قالب جریان VLESS و روش Shadowsocks را تنظیم کند.

راه‌حل:

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

مشکل: می‌خواهید قالبی که کاربران را به مدت 1 ساعت on hold ایجاد می‌کند، سپس برای 30 روز فعال می‌شود.

راه‌حل:

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

کاربر با on hold شروع می‌کند، بعد از 1 ساعت فعال می‌شود، بعد از 30 روز کل منقضی می‌شود.

مشکل: می‌خواهید قالبی با محدودیت 5 GB که ماهانه بازنشانی می‌شود.

راه‌حل:

{
  "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"
}

کاربر با تمام تنظیمات قالب به طور خودکار اعمال شده ایجاد می‌شود.

مشکل: می‌خواهید 50 کاربر با نام‌های کاربری تصادفی ایجاد کنید.

راه‌حل:

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

50 کاربر با نام‌های کاربری 5 کاراکتری تصادفی ایجاد شدند.

مشکل: می‌خواهید 100 کاربر با نام‌های "user1"، "user2" و غیره ایجاد کنید.

راه‌حل:

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"
}

کاربر "john" تمام تنظیمات از قالب 2 را دریافت می‌کند، ساختار تنظیمات پروکسی آن‌ها حفظ می‌شود.

مشکل: هنگام ارتقای کاربر، می‌خواهید استفاده داده آن‌ها را بازنشانی کنید.

راه‌حل:

// ابتدا، قالب را برای فعال‌سازی reset_usages به‌روزرسانی کنید
PUT /api/user_template/2
{
  "reset_usages": true
}

// سپس قالب را به کاربر اعمال کنید
PUT /api/user/john/from_template
{
  "user_template_id": 2
}

استفاده داده کاربر به 0 بازنشانی می‌شود.

مشکل: می‌خواهید به طور موقت از استفاده قالب جلوگیری کنید.

راه‌حل:

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]
}

مشکل: می‌خواهید نام‌های کاربری مانند "premium_john_vip".

راه‌حل:

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

هنگام ایجاد کاربر "john"، نام کاربری نهایی "premium_john_vip" است.


خلاصه

  • قالب‌ها الگوها هستند - آن‌ها مقادیر پیش‌فرض برای ایجاد کاربر ارائه می‌دهند
  • تمام فیلدها اعمال می‌شوند - تنظیمات قالب هنگام ایجاد کاربر مقادیر پیش‌فرض را بازنویسی می‌کنند
  • پیشوند/پسوند نام کاربری - به طور خودکار به نام‌های کاربری اضافه می‌شوند
  • تنظیمات اضافی - اعمال تنظیمات خاص پروتکل (flow, method)
  • اختصاص گروه - کاربران به طور خودکار به گروه‌های قالب می‌پیوندند
  • مدیریت وضعیت - از active و on_hold با تایم‌اوت پشتیبانی می‌کند
  • محاسبه انقضا - به طور خودکار از expire_duration محاسبه می‌شود
  • بازنشانی محدودیت داده - استراتژی‌های بازنشانی قابل پیکربندی
  • ایجاد دسته‌ای - ایجاد تا 500 کاربر با تولید خودکار نام کاربری
  • قالب‌های غیرفعال - تا زمانی که دوباره فعال نشوند نمی‌توانند استفاده شوند
  • تغییر کاربر - اعمال قالب‌ها به کاربران موجود
  • بازنشانی استفاده - گزینه بازنشانی استفاده داده هنگام تغییر کاربران

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

  • گروه‌ها: groups.mdx را ببینید
  • Hostها: hosts.mdx را ببینید
  • پیکربندی XRay: xray.mdx را ببینید

On this page

فهرست مطالبنمای کلیجریان قالبمبانی پیکربندی قالبفیلدهای الزامیفیلدهای اختیاریفیلدهای پاسخ قالبتوضیح فیلدهای قالبفیلدهای پایه`name` (String, الزامی)`group_ids` (List\[Integer], الزامی در ایجاد)`data_limit` (Integer, اختیاری)`expire_duration` (Integer, اختیاری)فیلدهای نام کاربری`username_prefix` (String, اختیاری)`username_suffix` (String, اختیاری)فیلدهای وضعیت`status` (UserStatusCreate, اختیاری)`on_hold_timeout` (Integer, اختیاری)فیلدهای مدیریت داده`data_limit_reset_strategy` (DataLimitResetStrategy, اختیاری)`reset_usages` (Boolean, اختیاری)فیلدهای پیشرفته`extra_settings` (ExtraSettings, اختیاری)`is_disabled` (Boolean, اختیاری)نحوه کار قالب‌هافرآیند اعمال قالبترتیب اعمال فیلدهامدیریت نام کاربریساخت نام کاربریاعتبارسنجی نام کاربریتنظیمات اضافیFlow (VLESS)Method (Shadowsocks)تنظیمات اضافی ترکیبیوضعیت و انقضاوضعیت فعالوضعیت On Holdمحدودیت داده و استراتژی بازنشانیمحدودیت دادهاستراتژی بازنشانیایجاد کاربران از قالب‌هاایجاد کاربر واحدآنچه اعمال می‌شودتغییر کاربران با قالب‌هااعمال قالب به کاربر موجودآنچه اعمال می‌شودپرچم Reset Usagesایجاد دسته‌ای کاربراننمای کلیاستراتژی‌های تولید نام کاربریپیشوند/پسوند نام کاربری در ایجاد دسته‌ایفرآیند ایجاد دسته‌ایResponseمحدودیت‌هاقوانین اعتبارسنجی و محدودیت‌هااعتبارسنجی ناماعتبارسنجی Group IDsاعتبارسنجی پیشوند/پسوند نام کاربریاعتبارسنجی وضعیتاعتبارسنجی محدودیت دادهاعتبارسنجی مدت انقضااعتبارسنجی قالب غیرفعالنقاط پایانی APIایجاد قالبدریافت تمام قالب‌هادریافت قالب بر اساس IDتغییر قالبحذف قالبایجاد کاربر از قالبتغییر کاربر با قالبایجاد دسته‌ای کاربران از قالبسناریوهای رایجخلاصه