پیکربندی قالبهای کاربری
مدیریت قالبها، اعمال فیلدها، ایجاد دستهای کاربران و مستندات API
مستندات قالبهای کاربری
این سند نحوه کار قالبهای کاربری در PasarGuard را توضیح میدهد. قالبها تنظیمات از پیش پیکربندی شده کاربری هستند که میتوانند برای ایجاد سریع کاربران با پیکربندیهای یکنواخت استفاده شوند. این سند برای کمک به مبتدیان در درک مدیریت قالبها، اعمال فیلدها و ایجاد دستهای کاربران طراحی شده است.
فهرست مطالب
- نمای کلی
- مبانی پیکربندی قالب
- توضیح فیلدهای قالب
- نحوه کار قالبها
- مدیریت نام کاربری
- تنظیمات اضافی
- وضعیت و انقضا
- محدودیت داده و استراتژی بازنشانی
- ایجاد کاربران از قالبها
- تغییر کاربران با قالبها
- ایجاد دستهای کاربران
- قوانین اعتبارسنجی و محدودیتها
- نقاط پایانی API
- سناریوهای رایج
نمای کلی
قالبهای کاربری در PasarGuard تنظیمات از پیش پیکربندی شده کاربری هستند که:
- استانداردسازی ایجاد کاربر - اعمال تنظیمات یکنواخت به چندین کاربر
- سرعت بخشیدن به مدیریت کاربر - ایجاد سریع کاربران بدون پیکربندی هر فیلد
- پشتیبانی از عملیات دستهای - ایجاد چندین کاربر به یکباره با تولید خودکار نام کاربری
- فعالسازی خودکارسازی - قالبها میتوانند در گردشهای کاری خودکار استفاده شوند
جریان قالب
Template → User Creation → Applied Settingsنحوه کار:
- ادمین یک قالب با تنظیمات کاربری مورد نظر ایجاد میکند
- هنگام ایجاد کاربر، ادمین یک قالب را انتخاب میکند
- فیلدهای قالب به طور خودکار به کاربر جدید اعمال میشوند
- ادمین فقط باید نام کاربری را ارائه دهد (و به صورت اختیاری یادداشت)
- کاربر با تمام تنظیمات قالب ایجاد میشود
قالبها الگوها برای ایجاد کاربر هستند. آنها خود کاربر ایجاد نمیکنند - آنها مقادیر پیشفرض را هنگام ایجاد کاربر ارائه میدهند.
مبانی پیکربندی قالب
فیلدهای الزامی
هر قالب باید داشته باشد:
| Field | Type | Constraints | Description |
|---|---|---|---|
name | string | نمیتواند خالی باشد، حداکثر 64 کاراکتر، باید منحصر به فرد باشد | شناسه/نام قالب |
group_ids | list[integer] | حداقل یک گروه الزامی است (در ایجاد) | گروههایی که به کاربران ایجاد شده از این قالب اختصاص داده میشوند |
فیلدهای اختیاری
| Field | Type | Default | Description |
|---|---|---|---|
data_limit | integer | 0 (نامحدود) | محدودیت داده به بایت (0 = نامحدود) |
expire_duration | integer | 0 (نامحدود) | مدت انقضا به ثانیه (0 = نامحدود) |
username_prefix | string | null | پیشوند اضافه شده به نامهای کاربری (حداکثر 20 کاراکتر) |
username_suffix | string | null | پسوند اضافه شده به نامهای کاربری (حداکثر 20 کاراکتر) |
extra_settings | ExtraSettings | null | تنظیمات خاص پروتکل (flow, method) |
status | UserStatusCreate | active | وضعیت اولیه کاربر (active یا on_hold) |
reset_usages | boolean | false | بازنشانی استفاده داده هنگام اعمال قالب به کاربر موجود |
on_hold_timeout | integer | null | تایماوت به ثانیه برای وضعیت on_hold |
data_limit_reset_strategy | DataLimitResetStrategy | no_reset | نحوه بازنشانی محدودیت داده |
is_disabled | boolean | false | غیرفعال کردن قالب (جلوگیری از استفاده) |
فیلدهای پاسخ قالب
هنگام دریافت قالبها، همچنین دریافت میکنید:
| Field | Type | Description |
|---|---|---|
id | integer | شناسه منحصر به فرد (خودکار تولید میشود) |
توضیح فیلدهای قالب
فیلدهای پایه
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 - رفتار: قالبهای غیرفعال نمیتوانند برای ایجاد یا تغییر کاربران استفاده شوند
- مورد استفاده: غیرفعال کردن موقت قالبها بدون حذف آنها
نحوه کار قالبها
فرآیند اعمال قالب
هنگام ایجاد کاربر از قالب:
- اعتبارسنجی قالب - قالب باید وجود داشته باشد و غیرفعال نباشد
- بارگذاری فیلدها - فیلدهای پایه از قالب بارگذاری میشوند
- ساخت نام کاربری - پیشوند + نام کاربری + پسوند
- اعمال تنظیمات - تنظیمات اضافی (flow, method) اعمال میشوند
- ایجاد کاربر - کاربر با تمام مقادیر قالب ایجاد میشود
ترتیب اعمال فیلدها
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-Poly1305aes-128-gcm- AES-128-GCMaes-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 GB5368709120= 5 GB0= نامحدود
استراتژی بازنشانی
کنترل نحوه بازنشانی محدودیت داده (فقط اگر data_limit > 0 اعمال میشود):
| Strategy | Description | Reset 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"
}فرآیند:
- قالب اعتبارسنجی میشود (وجود دارد، غیرفعال نیست)
- فیلدهای پایه از قالب بارگذاری میشوند
- نام کاربری ساخته میشود:
prefix + "john" + suffix - تنظیمات اضافی اعمال میشوند
- کاربر با تمام مقادیر قالب ایجاد میشود
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"
}فرآیند:
- قالب اعتبارسنجی میشود (وجود دارد، غیرفعال نیست)
- فیلدهای پایه از قالب بارگذاری میشوند
proxy_settingsموجود کاربر حفظ میشوند- فیلدهای قالب اعمال میشوند (مقادیر فعلی کاربر را بازنویسی میکنند)
- اگر
reset_usagesبرابرtrueباشد، استفاده داده کاربر بازنشانی میشود - کاربر بهروزرسانی میشود
آنچه اعمال میشود
هنگام تغییر کاربر با قالب:
- ✅ گروهها از
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"فرآیند ایجاد دستهای
- اعتبارسنجی قالب - قالب وجود دارد و غیرفعال نیست
- اعتبارسنجی استراتژی - قوانین استراتژی نام کاربری بررسی میشوند
- تولید نام کاربری - نامهای کاربری بر اساس استراتژی تولید میشوند
- فیلتر کردن تکراریها - نامهای کاربری موجود فیلتر میشوند
- ایجاد کاربر - تمام کاربران با تنظیمات قالب ایجاد میشوند
- URLهای اشتراک - URLها برای تمام کاربران ایجاد شده تولید میشوند
Response
{
"subscription_urls": [
"https://example.com/sub/user1?token=...",
"https://example.com/sub/user2?token=..."
],
"created": 10
}نکته: تعداد created ممکن است کمتر از count باشد اگر برخی نامهای کاربری از قبل وجود داشته باشند.
محدودیتها
- حداکثر تعداد: 500 کاربر در هر درخواست
- حداقل تعداد: 1 کاربر
- یکتایی نام کاربری: نامهای کاربری تکراری به طور خودکار رد میشوند
- اعتبارسنجی قالب: قالب باید وجود داشته باشد و غیرفعال نباشد
قوانین اعتبارسنجی و محدودیتها
اعتبارسنجی نام
| Rule | Constraint | Error Message |
|---|---|---|
| Required | نمیتواند خالی باشد | "name can't be empty" |
| Length | حداکثر 64 کاراکتر | Name too long |
| Uniqueness | باید منحصر به فرد باشد | "Template by this name already exists" |
اعتبارسنجی Group IDs
| Rule | Constraint | Error Message |
|---|---|---|
| Creation | حداقل یکی الزامی است | "you must select at least one group" |
| Existence | تمام IDها باید وجود داشته باشند | Group not found |
| Modification | میتواند خالی/null باشد | هنگام تغییر مجاز است |
اعتبارسنجی پیشوند/پسوند نام کاربری
| Rule | Constraint | Error Message |
|---|---|---|
| Length | حداکثر 20 کاراکتر | Prefix/suffix too long |
| Characters | همان قوانین نام کاربری | Invalid characters |
اعتبارسنجی وضعیت
| Rule | Constraint | Error 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" |
اعتبارسنجی محدودیت داده
| Rule | Constraint | Error Message |
|---|---|---|
| Minimum | باید >= 0 باشد | Data limit must be 0 or greater |
اعتبارسنجی مدت انقضا
| Rule | Constraint | Error 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 را ببینید