اطلاع‌رسانی حجم و زمان
حالت وب‌هوک یا ربات برای هشدار کم‌حجم و انقضای کانفیگ، و تنظیم Webhook در پنل پاسارگارد.
ربات می‌تواند وقتی حجم کاربر کم شد یا زمان سرویس رو به اتمام است، به کاربر پیام بدهد. برای هر پنل دو حالت دارید:
| حالت | برچسب دکمه | معنی |
|---|---|---|
| ربات (پیش‌فرض) | 📡 اطلاع‌رسانی (🤖) | خود ربات هر دقیقه لیست کاربران را از پنل می‌گیرد و بررسی می‌کند |
| وب‌هوک (پیشنهادی) | 📡 اطلاع‌رسانی (🔔) | خود پنل فقط برای همان کاربری که اتفاقی برایش افتاده، رویداد را به ربات می‌فرستد |
پیشنهاد
حالت وب‌هوک را فعال کنید. سبک‌تر و دقیق‌تر است و فشار اضافه‌ای روی پنل نمی‌آورد.
مرتبط با منوی پنل‌ها و مرجع تنظیمات پنل.
حالت ربات (پیش‌فرض)
در این حالت ربات هر ۶۰ ثانیه به API پنل درخواست می‌زند، کاربران را می‌خواند و حجم و زمانشان را بررسی می‌کند.
چرا پیشنهاد نمی‌شود:
- روی پنل‌های شلوغ، هر دقیقه تعداد زیادی درخواست به پنل فرستاده می‌شود
- بار CPU و API پنل بالا می‌رود
- این بررسی فقط برای پنل‌هایی اجرا می‌شود که وب‌هوکشان روشن نیست
اگر همهٔ پنل‌ها روی وب‌هوک باشند، این بررسی دوره‌ای برای آن‌ها کلاً انجام نمی‌شود.
حالت وب‌هوک (پیشنهادی)
پنل پاسارگارد وقتی رویدادی رخ دهد (مثلاً رسیدن به درصد مصرف یا تعداد روز باقی‌مانده)، همان کاربر را برای ربات می‌فرستد. دیگر لازم نیست ربات همهٔ کاربران را مرتب بررسی کند.
مزیت‌ها:
- بهینه‌تر و سبک‌تر
- فشار خیلی کمتر روی پنل
- هشدار نزدیک‌تر به لحظهٔ واقعی رویداد
رویدادهایی که ربات استفاده می‌کند
| رویداد پاسارگارد | کاری که ربات انجام می‌دهد |
|---|---|
reached_usage_percent | پیام کم‌حجم با درصد مصرف و حجم باقی‌مانده |
reached_days_left | پیام تعداد روز باقی‌مانده تا انقضا |
user_limited | پیام تمام شدن حجم. اگر سرویس تست باشد، از پنل و ربات حذف می‌شود |
user_expired | پیام انقضا (به همراه مهلت حذف، اگر حذف خودکار منقضی‌ها روشن باشد). اگر سرویس تست باشد، بلافاصله حذف می‌شود |
user_created، user_updated، user_deleted، user_enabled، user_disabled | فقط در لاگ سرور ثبت می‌شوند و پیامی به کاربر فرستاده نمی‌شود |
ربات فقط به رویدادهای پنلی پاسخ می‌دهد که اطلاع‌رسانی‌اش روی 🔔 باشد، و فقط برای سرویس‌هایی که در خود ربات ثبت شده‌اند.
فعال‌سازی در ربات
- وارد پنل مدیریت شوید.
- 📚 منوی پنل ها → 📉 وضعیت پنل ها را باز کنید و پنل را انتخاب کنید.
- دکمهٔ 📡 اطلاع‌رسانی را بزنید تا به حالت وب‌هوک برود:
📡 اطلاع‌رسانی (🤖)یعنی حالت ربات📡 اطلاع‌رسانی (🔔)یعنی حالت وب‌هوک
- پیام تایید این است:
✅ وضعیت اطلاع‌رسانی به وب‌هوک 🔔 تغییر یافت!
اگر پنل در ربات هنوز روی 🤖 باشد، رویدادهای وب‌هوک آن پنل نادیده گرفته می‌شوند و بررسی دوره‌ای ربات برای آن پنل ادامه پیدا می‌کند.
تنظیم در پنل پاسارگارد
مسیر داخل پنل: Settings → Webhook
برای دیدن تمام‌صفحه روی تصویر کلیک کنید:
۱. گرفتن URL و Secret
آدرس (URL): روی سرور ربات دستور زیر را بزنید (یا در منوی pasarguardbot گزینهٔ 9) Show webhook & URLs را انتخاب کنید):
pasarguardbot urls[*] Webhook (set in Pasarguard panel): URL: http://SERVER_IP:6160/api/webhook Header: x-webhook-secret: <from DB table secrets, name=webhook_secret> Note: crypto_key / webhook_secret are stored in DB (not .env) [*] phpMyAdmin: URL: http://SERVER_IP:6163
همان URL را در پنل می‌گذارید. اگر دامنه دارید، به‌جای IP دامنه را بنویسید.
سکرت (Secret): این دستور مقدار سکرت را چاپ نمی‌کند. سکرت هنگام نصب به‌صورت تصادفی ساخته می‌شود و در دیتابیس ذخیره است، نه در .env. برای خواندنش:
phpMyAdmin را باز کنید
آدرس phpMyAdmin همان است که در خروجی بالا آمده (پورت 6163). با کاربر root و رمز MARIADB_ROOT_PASSWORD از فایل .env وارد شوید.
جدول secrets
دیتابیس pasarguardbot را باز کنید، سپس جدول secrets را.
ردیف webhook_secret
مقدار ستون value در ردیفی که name آن برابر webhook_secret است را کپی کنید. یک رشتهٔ ۶۴ کاراکتری است.
روی سرور ربات:
docker exec pasarguardbot-mariadb sh -c 'mariadb -u root -p"$MARIADB_ROOT_PASSWORD" pasarguardbot -N -e "SELECT value FROM secrets WHERE name=\"webhook_secret\""'جزئیات بیشتر: نصب و منوی مدیریت سرور.
۲. General Settings
| گزینه | پیشنهاد | توضیح |
|---|---|---|
| Enable Webhooks | روشن (ON) | بدون این، هیچ رویدادی فرستاده نمی‌شود |
| Timeout (seconds) | مثلاً 180 | مهلت پاسخ ربات (۱ تا ۳۰۰) |
| Retry Attempts | مثلاً 3 | تعداد تلاش مجدد اگر ارسال شکست بخورد |
| Proxy URL | معمولاً خالی | فقط اگر پنل برای رسیدن به ربات پروکسی لازم دارد |
۳. Webhook Endpoints
- Add Webhook را بزنید.
- در فیلد URL آدرس ربات را بگذارید، مثلاً:
http://YOUR_SERVER_IP:6160/api/webhookیا با دامنه:
https://bot.example.com/api/webhook- در فیلد Secret دقیقاً مقدار
webhook_secretرا بگذارید که از جدولsecretsبرداشتید. پنل آن را در هدرx-webhook-secretمی‌فرستد و ربات درخواست با سکرت اشتباه را رد می‌کند. - برای یک ربات معمولاً یک Endpoint کافی است. Endpoint اشتباه را حذف کنید.
پورت و مسیر
پورت پیش‌فرض ربات 6160 است (متغیر FASTAPI_PORT) و مسیر باید دقیقاً /api/webhook باشد.
پورت‌هایی مثل 8001 یا 8180 مربوط به ربات‌های دیگرند. برای PasarguardBot از خروجی pasarguardbot urls استفاده کنید.
۴. Days Left Notifications
مشخص می‌کند چند روز مانده به انقضا، پنل رویداد بفرستد.
- روی + بزنید و عدد روز را وارد کنید.
- نمونهٔ رایج:
7،2و1. - مقادیر اضافه را می‌توانید حذف کنید.
بدون حداقل یک عدد، هشدار «روز باقی‌مانده» از وب‌هوک نمی‌آید.
۵. Usage Percentage Notifications
آستانهٔ درصد مصرف حجم را تعیین می‌کند.
- روی + بزنید و درصد را وارد کنید (مثلاً
90). - وقتی مصرف به آن درصد برسد، پنل رویداد می‌فرستد و ربات پیام کم‌حجم می‌دهد.
- در صورت نیاز چند آستانه بگذارید (مثلاً
80و90).
بدون حداقل یک درصد، هشدار کم‌حجم از وب‌هوک کار نمی‌کند.
تمدید حجم را هم تنظیم کنید
اگر از هشدار درصدی استفاده می‌کنید، 📊 تمدید حجم همان پنل را روی باقی+ریست بگذارید تا بعد از تمدید، درصد مصرف از صفر حساب شود.
۶. ذخیره
پایین صفحه Save را بزنید. بدون Save تنظیمات اعمال نمی‌شود.
ترتیب درست
- با
pasarguardbot urlsآدرس وب‌هوک را بگیرید وwebhook_secretرا از جدولsecretsبخوانید - در پنل: Settings → Webhook و Enable Webhooks = ON
- یک Endpoint با همان URL و Secret اضافه کنید
- Days Left (مثلاً ۱، ۲ و ۷) و Usage Percentage (مثلاً ۹۰) را تنظیم کنید
- Save
- در ربات، اطلاع‌رسانی همان پنل را روی
🔔بگذارید - پورت
6160سرور ربات باید از سرور پنل در دسترس باشد
عیب‌یابی
| مشکل | بررسی |
|---|---|
| هیچ پیامی نمی‌آید | Enable Webhooks روشن است؟ Save زده‌اید؟ |
| پنل به ربات نمی‌رسد | IP یا دامنه و پورت 6160 درست است؟ فایروال باز است؟ |
| سکرت اشتباه (خطای 403) | Secret باید دقیقاً مقدار ردیف webhook_secret در جدول secrets باشد، بدون فاصلهٔ اضافه |
| ربات رویداد را نادیده می‌گیرد | دکمهٔ اطلاع‌رسانی همان پنل روی 🔔 است؟ |
| فقط هشدار حجم یا فقط زمان می‌آید | آستانه‌های Usage Percentage یا Days Left خالی نمانده باشد |
بعد از ریستور بکاپ‌های قدیمی
اگر از بکاپ نسخه‌های قدیمی ربات (v2.1.4 یا قبل‌تر) ریستور کرده‌اید، این بخش را بخوانید. بعد از هر ریستور، مقدار webhook_secret را دوباره از جدول بخوانید و با Secret داخل پنل مقایسه کنید.
نکات
- پیش‌فرض ربات حالت
🤖است. برای هر پنل جداگانه باید به🔔عوضش کنید. - اگر چند پنل پاسارگارد دارید، وب‌هوک را در هر پنل جداگانه تنظیم کنید (همان Endpoint ربات را در همه بگذارید).
- تا وقتی حتی یک پنل در ربات روی
🤖باشد، بررسی دوره‌ای برای همان پنل‌ها هر دقیقه انجام می‌شود. - حذف سرویس‌های پولیِ منقضی‌شده (اگر روشن باشد) در هر دو حالت انجام می‌شود.
- متن پیام‌های اطلاع‌رسانی را در متن‌ها و دکمه‌ها می‌توانید عوض کنید.