محدودیت دستگاه (HWID)
HWID — شناسه دستگاه است که اپلیکیشن کلاینت همراه با درخواست اشتراک می‌فرستد. پنل با آن می‌فهمد که همان دستگاه درخواست اشتراک می‌کند، نه دستگاه جدید، و می‌تواند تعدادشان را محدود کند.
این قابلیت کاملاً اختیاری و به‌صورت پیش‌فرض خاموش است. فقط با کلاینت‌هایی
کار می‌کند که بتوانند هدر x-hwid را بفرستند.
چگونه فعال کنیم
محدودیت در پنل در بخش Subscription → Settings → HWID Device Limit تنظیم
می‌شود، نه در .env. سه پارامتر در دسترس است: خود کلید، محدودیت پیش‌فرض
دستگاه و متن اعلان برای کلاینت. برای یک گروه خارجی مشخص می‌توان تنظیمات را
بازنویسی کرد و برای هر کاربر محدودیت خودش را تعیین کرد.
| محل | چه چیزی تعیین می‌کند |
|---|---|
| تنظیمات جهانی اشتراک | محدودیت را فعال می‌کند، محدودیت پیش‌فرض، متن اعلان |
| گروه خارجی | تنظیمات جهانی را برای کاربرانش بازنویسی می‌کند |
| کارت کاربر | محدودیت دستگاه شخصی برای یک کاربر |
اگر برای کاربر محدودیتی تعیین نشده باشد، محدودیت پیش‌فرض اعمال می‌شود. مقدار
0 در کارت کاربر محدودیت را برای او غیرفعال می‌کند: دستگاه‌ها همچنان ثبت
می‌شوند، اما اشتراک همیشه ارائه می‌شود.
اگر محدودیت فعال باشد و کلاینت هدر x-hwid را نفرستاده باشد، اشتراک ارائه
نمی‌شود. پیش از فعال‌سازی مطمئن شوید کاربرانتان از کلاینت‌های پشتیبان استفاده
می‌کنند، در غیر این صورت دسترسی را از دست می‌دهند.
کلاینت چه هدرهایی می‌فرستد
| هدر | الزامی | توضیح |
|---|---|---|
x-hwid | بله | شناسه دستگاه |
x-device-os | خیر | پلتفرم، برای مثال iOS |
x-ver-os | خیر | نسخه سیستم |
x-device-model | خیر | مدل دستگاه |
user-agent | خیر | اپلیکیشن و نسخه آن |
مقدار x-hwid باید از 10–64 کاراکتر تشکیل شده باشد: حروف لاتین، ارقام،
نشانه‌های = و -. اگر فرمت مناسب نباشد، پنل هدر را کاملاً دور می‌ریزد و HWID
را نافرساده‌شده می‌شمارد.
curl -H 'x-hwid: UE42LJXu4DbiCaBv' \
-H 'x-device-os: iOS' \
-H 'x-ver-os: 18.3' \
-H 'x-device-model: iPhone 14 Pro Max' \
https://sub.example.com/XXXXXXXXXXXX
در پاسخ، پنل هدرهای سرویس را می‌افزاید که کلاینت با آن‌ها پیام قابل‌فهم به کاربر نشان می‌دهد:
| هدر پاسخ | چه زمانی پدید می‌آید |
|---|---|
x-hwid-active | محدودیت در سمت پنل فعال است |
x-hwid-not-supported | محدودیت فعال است، اما کلاینت x-hwid را نفرستاده |
x-hwid-max-devices-reached | بیشینه دستگاه‌ها رسیده است |
x-hwid-limit | همان، برای سازگاری با کلاینت‌های قدیمی |
چه چیزی ذخیره می‌شود
هر دستگاه در جدول hwid_user_devices قرار می‌گیرد. کلید — جفت «HWID + کاربر»
است، بنابراین همان دستگاه برای دو کاربر دو رکورد شمرده می‌شود.
| ستون | محتوا |
|---|---|
hwid | شناسه دستگاه، تا 64 کاراکتر |
user_id | دارنده اشتراک |
platform | پلتفرم از x-device-os |
os_version | نسخه سیستم از x-ver-os |
device_model | مدل از x-device-model |
user_agent | اپلیکیشن از user-agent |
request_ip | IP آدرس درخواست اشتراک |
created_at, updated_at | زمان نخستین و آخرین مشاهده دستگاه |
در پنل چه دیده می‌شود
در کارت کاربر فهرست دستگاه‌هایش نمایش داده می‌شود: پلتفرم، نسخه سیستم، مدل، IP و تاریخ‌ها. دستگاه را می‌توان یکی‌یکی حذف کرد یا کل فهرست را پاک کرد — پس از آن دوباره می‌تواند متصل شود. جست‌وجو بر اساس HWID وجود دارد.
در صفحه جداگانه HWID خلاصه‌ای گرد آمده است: توزیع بر اساس پلتفرم‌ها و
اپلیکیشن‌ها، تعداد کل دستگاه‌ها و رکوردهای یکتا، میانگین تعداد دستگاه به ازای
کاربر، و همچنین فهرست کاربران با بیشترین تعداد دستگاه. همین داده‌ها از طریق
API در دسترس‌اند — دستورهای GET /api/hwid/devices، GET /api/hwid/stats و
GET /api/hwid/devices/top-users.
رویدادهای افزودن و حذف دستگاه (user_hwid_devices.added و
user_hwid_devices.deleted) به Webhookها می‌آیند. جزئیات بیشتر — در بخش
Webhookها.
مدت نگه‌داری و حریم خصوصی
جدول hwid_user_devices حساس‌ترین جدول در پایگاه داده است: در آن شناسه دستگاه،
مدل، نسخه سیستم، user-agent و IP آدرس قرار دارند. تا وقتی پاک‌سازی خودکار را
فعال نکنید، به‌صورت خودکار پاک نمی‌شود.
| متغیر | پیش‌فرض | چه می‌کند |
|---|---|---|
SERVICE_CLEAN_OLD_LOGS | false | پاک‌سازی هفتگی جدول‌های حساس را فعال می‌کند |
HWID_DEVICES_RETENTION_DAYS | 90 | چند روز دستگاه نگه‌داری شود |
شمارش از updated_at انجام می‌شود، یعنی از آخرین ظهور دستگاه: دستگاه‌های
فعالانه استفاده‌شده می‌مانند و آن‌هایی که بیش از این مدت برنگشته‌اند حذف
می‌شوند. کار هفته‌ای یک بار، بامداد دوشنبه اجرا می‌شود.
اگر تاریخ دستگاه‌ها را لازم ندارید، مدت نگه‌داری را کوتاه کنید یا جدول را دستی پاک کنید — از بخش Logs در پنل یا CLI اضطراری.
حذف دستگاه محافظت از اشتراک در برابر انتقال را برمی‌دارد: کاربر می‌تواند آن را روی دستگاه جدید وصل کند، اگر جای خالی باشد. پیش از پاک‌سازی گروهی، فهرست دستگاه‌ها را مقایسه کنید.
گام‌های بعدی
- Webhookها — رویدادهای دستگاه و امضای payload.
- اعلان‌ها — هشدارهای آستانه‌ها و انقضا.
- CLI اضطراری — پاک‌سازی گروهی دستگاه‌ها.
- متغیرهای محیطی — مدت‌های نگه‌داری.