سوالات متداول و رفع مشکل
جواب رایج‌ترین سوال‌ها و راه‌حل مشکلات نصب، فروش، پرداخت، وب‌هوک و وب‌اپ
قبل از هر چیز، لاگ ربات را ببینید. بیشتر مشکلات همان‌جا توضیح داده شده‌اند:
pasarguardbot logs(لاگ زندهٔ همهٔ سرویس‌ها؛ با Ctrl+C خارج شوید.)
نصب و سرور
- صبر کنید. در اولین اجرا MariaDB دیتابیس را می‌سازد و ربات تا سالم شدن دیتابیس منتظر می‌ماند. این کار ممکن است چند دقیقه طول بکشد.
- لاگ را ببینید:
pasarguardbot logs. باید پیام اجرای مایگریشن (Running database migrations...) و بعد بالا آمدن ربات را ببینید. - وضعیت کانتینرها:
pasarguardbot status. هر چهار کانتینر بایدrunningباشند. BOT_TOKENرا در.envچک کنید (pasarguardbot edit-env).- اگر کانتینرها به اینترنت وصل نمی‌شوند (خطای اتصال به تلگرام یا timeout)، بخش «مشکل شبکهٔ Docker» را پایین‌تر ببینید.
- اگر ربات برای شما جواب می‌دهد ولی برای کاربران نه، احتمالاً وضعیت ربات خاموش است (پایین‌تر).
سشن تلگرام ربات قبلی در پوشهٔ sessions ذخیره شده و با آن دوباره وصل می‌شود. ربات را متوقف کنید، فایل سشن را پاک کنید و دوباره راه بیندازید:
cd /opt/pasarguardbot
docker compose stop bot
rm -f sessions/KenzoSession.session
pasarguardbot restart[!] Port 6160 appears to be in use.برنامه‌ای که پورت را گرفته پیدا کنید:
ss -ltnp | grep -E ':(6160|6161|6162|6163)\s'آن را متوقف کنید یا پورت ربات را با FASTAPI_PORT عوض کنید. جزئیات: پورت‌ها.
- ایمیج ربات فقط برای معماری‌های
amd64وarm64ساخته می‌شود. معماری سرور را باuname -mچک کنید (x86_64= amd64،aarch64= arm64). روی معماری‌های دیگر (مثل armv7) نصب ممکن نیست. - دسترسی سرور به
ghcr.ioو Docker Hub را چک کنید. بعضی دیتاسنترها این دامنه‌ها را محدود می‌کنند. - اگر شبکهٔ کانتینرها مشکل دارد، بخش بعدی را ببینید.
روی بعضی سرورهای Ubuntu یک فایل Netplan شبکهٔ bridge داکر را خراب می‌کند. از منو گزینهٔ 11) Fix Docker network را بزنید:
- اول
1) Check Docker Bridgeتا مشکل تأیید شود. - اگر تست شکست خورد،
2) Repair Docker Bridge. - اگر بعد از تعمیر مشکلی پیش آمد،
3) Rollback Netplan Repair.
ممکن است یک ریبوت لازم شود. جزئیات: منوی مدیریت → Fix Docker network.
همه در فایل /opt/pasarguardbot/.env هستند:
grep MARIADB_ /opt/pasarguardbot/.env- یوزر: مقدار
MARIADB_USER(معمولاًpasarguardbot) با رمزMARIADB_PASSWORD - یا یوزر
rootبا رمزMARIADB_ROOT_PASSWORD
آدرس phpMyAdmin: http://SERVER_IP:6163 (یا pasarguardbot urls).
- لاگ فایلی ربات:
/opt/pasarguardbot/logs/app.logو خطاها در/opt/pasarguardbot/logs/error.log - لاگ کانتینرها:
pasarguardbot logs(زنده) یا منو گزینهٔ4) View logs
سطح جزئیات با LOG_LEVEL در .env تنظیم می‌شود. پیکربندی
مدیریت و آپدیت
pasarguardbot updateبرنچ را بپرسد، Enter بزنید (main). اسکریپت خودش را به‌روز می‌کند، ایمیج جدید را می‌گیرد، کانتینرها را از نو می‌سازد و مایگریشن دیتابیس را خودکار اجرا می‌کند. .env و دیتا حفظ می‌شوند. جزئیات
همان pasarguardbot update را بزنید و در سؤال برنچ، 1 (main) یا 2 (dev) را انتخاب کنید. تگ ایمیج خودکار عوض می‌شود (latest یا dev).
dev برای تست است و ممکن است ناپایدار باشد. قبل از جابه‌جایی حتماً از 📦 بکاپ ربات بکاپ بگیرید.
آیدی عددی تلگرام ادمین جدید را با کاما به ADMIN_ID اضافه کنید:
pasarguardbot edit-env
# ADMIN_ID=111111111,222222222ذخیره کنید و به Restart the bot? (Y/n): با Enter جواب دهید. همهٔ آیدی‌های این لیست دسترسی کامل پنل مدیریت را دارند.
ربات را روی سرور جدید نصب کنید، فایل database.sql بکاپ را از طریق phpMyAdmin ایمپورت کنید و ربات را آپدیت/ری‌استارت کنید. راهنمای کامل قدم‌به‌قدم (و حالت ربات‌های نسخهٔ 2.1.4 و قدیمی‌تر): بکاپ و ریستور.
فروش و خرید
این موارد را به ترتیب چک کنید:
- ⚙️ تنظیمات ربات → وضعیت فروش روشن باشد. پیش‌فرض خاموش است. در حالت خاموش، کاربر پیام «⛔️ فروش توسط ادمین بسته است.» می‌گیرد.
- حداقل یک پنل فعال باشد و 🛒 خرید سرویس آن ✅ باشد (📚 منوی پنل ها → 📉 وضعیت پنل ها → پنل). اگر هیچ پنلی فروش نداشته باشد، دکمه‌های 🛍 خرید سرویس و 🔑 سرویس های من از منو حذف می‌شوند.
- برای پنل حداقل یک پلن ساخته باشید (🗞 ساخت پلن).
- اگر برای پنل 🧢 سقف خرید سرویس گذاشته‌اید و پر شده، آن پنل در لیست خرید نمی‌آید.
- اگر «فقط مینی‌اپ» روشن است، منوی معمولی نمایش داده نمی‌شود و همه‌چیز در وب‌اپ است.
دکمه فقط وقتی دیده می‌شود که هر سه شرط برقرار باشد:
- ⚙️ تنظیمات ربات → 🛍 خرید، تمدید و سرویس تست → دکمه دریافت تست روشن باشد (پیش‌فرض خاموش).
- حداقل یک پنل فعال، تست ارائه دهد: (پنل) → 🧪 تنظیمات تست → 🆓 ارائهٔ تست از این پنل.
- کاربر قبلاً تست نگرفته باشد. برای اجازهٔ دوباره از 🔄 ریست دریافت تست استفاده کنید.
⚙️ تنظیمات ربات → وضعیت ربات خاموش است. در این حالت فقط ادمین‌ها می‌توانند از ربات استفاده کنند. آن را روشن کنید. (دکمهٔ «📢 وضعیت بروزرسانی» این پیام به یوزرنیم ADMIN_ID_TAG در .env لینک می‌شود.)
هیچ روش پرداختی روشن نیست. در ⚙️ تنظیمات ربات → 💳 پرداخت‌ها و روش‌های شارژ حداقل یکی از «دکمه کارت دستی»، «دکمه درگاه ارزی»، «دکمه پرداخت استارز» یا «درگاه TonPays» را روشن کنید و تنظیمات همان روش را در 💳 تنظیمات درگاه کامل کنید. تنظیمات درگاه
پرداخت، لاگ و بکاپ
رسیدها به مقصد لاگ 💳 کارت به کارت دستی فرستاده می‌شوند. اگر نه این مقصد و نه LOG_CHANNEL تنظیم شده باشد، رسید ثبت نمی‌شود.
- پنل مدیریت → 📝 مدیریت لاگ‌ها → 💳 کارت به کارت دستی را روی یک کانال یا سوپرگروه ست کنید.
- ربات باید در آن کانال/گروه ادمین باشد (اجازهٔ ارسال پیام).
- آیدی عددی درست باشد (معمولاً با
-100شروع می‌شود). بعد از ست کردن باید پیام تست در کانال بیاید. - 📊 وضعیت لاگ‌ها را بزنید و مقصد را ببینید.
بکاپ فقط به مقصد 🗄 بکاپ ربات در 📝 مدیریت لاگ‌ها فرستاده می‌شود (نه به LOG_CHANNEL). اگر تنظیم نشده باشد، پیام «❌ کانال لاگ بکاپ تنظیم نشده است.» می‌آید.
- مقصد بکاپ را ست کنید و ربات را ادمین کانال کنید.
- در 📦 بکاپ ربات دکمهٔ 🚀 بکاپ همین الان را برای تست بزنید.
- فاصلهٔ خودکار پیش‌فرض ۲۴ ساعت است؛ اگر روی «⏸ خودکار خاموش» است، با ⚙️ تنظیم فاصله عدد بزرگ‌تر از صفر بدهید.
وب‌هوک و اطلاع‌رسانی
ربات درخواست وب‌هوک را بدون هدر درست رد می‌کند:
| پیام | علت |
|---|---|
Signature header missing | هدر x-webhook-secret در تنظیمات وب‌هوک پنل اضافه نشده |
Invalid shared secret | مقدار Secret اشتباه است |
Secret درست در دیتابیس است: phpMyAdmin ← دیتابیس pasarguardbot ← جدول secrets ← ردیف webhook_secret ← ستون value. گزینهٔ 9) Show webhook & URLs آدرس و محل آن را نشان می‌دهد. مقدار WEBHOOK_SECRET در .env (اگر از نسخه‌های قدیمی مانده) استفاده نمی‌شود.
هر پنل دو حالت اطلاع‌رسانی دارد (دکمهٔ 📡 اطلاع‌رسانی در تنظیمات پنل):
- 🤖 حالت ربات (پیش‌فرض): ربات خودش حدود هر دقیقه پنل را چک می‌کند. نیازی به وب‌هوک ندارد.
- 🔔 حالت وب‌هوک: پنل پاسارگارد رویدادها را به ربات می‌فرستد. باید وب‌هوک در پنل (Settings → Webhook) درست ست شده باشد.
اگر روی 🔔 هستید ولی پیامی نمی‌آید:
- در پنل، وب‌هوک روشن و ذخیره شده باشد و آدرس
http(s)://…:6160/api/webhookباشد. - هدر
x-webhook-secretدرست باشد (سؤال قبلی). - سرور پنل به پورت
6160سرور ربات دسترسی داشته باشد (فایروال). - اگر SSL روی ربات فعال است، آدرس باید
https://و با دامنه باشد.
پنل پاسارگارد
- آدرس بدون مسیر: فقط
https://panel.example.comیاhttps://panel.example.com:8000. چیزی مثل/dashboardیا/adminاضافه نکنید. - پروتکل و پورت درست: همان آدرسی که در مرورگر پنل را باز می‌کند (http یا https و پورت پنل).
- نوع ورود: اگر 👤 نام کاربری و رمز را انتخاب کرده‌اید، یوزر و رمز ادمین پنل را بدهید؛ اگر 🔑 API Key، کلید API ساخته‌شده در پنل را. این دو را با هم اشتباه نکنید.
پیام‌های خطا:
| پیام | معنی |
|---|---|
Error: Unauthorized. Check username/password or API Key. | یوزر/رمز یا API Key اشتباه است |
Error: Forbidden (403). Check admin permissions. | ادمین دسترسی کافی ندارد (از ادمین اصلی/sudo استفاده کنید) |
Error: Panel URL or API path not found (404). | آدرس اشتباه است یا مسیر اضافه دارد |
Error: Panel connection timed out… / Could not connect to panel… | سرور ربات به پنل دسترسی ندارد (فایروال، دامنه، پورت) |
از سرور ربات تست کنید: curl -I https://panel.example.com:8000
وب‌اپ و Mini App
WEBAPP_URLدر.envباید باhttps://شروع شود. باhttp://یا خالی، هیچ دکمهٔ وب‌اپی نمایش داده نمی‌شود.- بعد از تغییر
.envربات را ری‌استارت کرده باشید. - برای دکمهٔ کاربران: ⚙️ تنظیمات ربات → 🚀 مینی‌اپ باید روی «دکمه در منو» باشد (پیش‌فرض «خاموش»). در حالت «فقط مینی‌اپ» منوی ربات کامل با یک دکمهٔ وب‌اپ جایگزین می‌شود.
- اگر دکمهٔ منوی اصلی را از ⌨️ مدیریت دکمه‌های کیبورد مخفی کرده‌اید، دوباره نمایشش دهید.
تلگرام فقط این را قبول می‌کند:
https://(نهhttp://)- دامنه (نه آی‌پی خام مثل
https://1.2.3.4:6160) - گواهی معتبر (نه self-signed؛ Let's Encrypt مناسب است)
با pasarguardbot ssl گواهی بگیرید و WEBAPP_URL=https://دامنه:6160/api/webapp بگذارید. در مرورگر https://دامنه:6160/webapp را باز کنید؛ اگر مرورگر خطای گواهی داد، تلگرام هم قبول نمی‌کند. دامنه و SSL