خطاهای رایج
در ادامه مشکلاتی آمده است که بیشتر از همه با آن‌ها روبه‌رو می‌شوید. قالب یکی است: نشانه → علت → راه‌حل. از لاگ‌ها شروع کنید — تقریباً همیشه علت در آن‌ها دیده می‌شود:
docker compose logs --tail=100 xpanel
docker compose ps
مجموعه کامل دستورهای عیب‌یابی — در بخش دستورهای مفید.
یک برگه تقلب کوتاه: چه می‌بینید — به چه چیزی نگاه کنید.
| نشانه در لاگ یا رابط کاربری | علت احتمالی |
|---|---|
Reverse proxy and HTTPS are required | هدرهای X-Forwarded-* از پروکسی وجود ندارد |
❌ METRICS_USER / ❌ METRICS_PASS | متغیرهای متریک تنظیم نشده‌اند |
| نود متصل نمی‌شود | NODE_PORT بسته است یا SECRET_KEY ناقص است |
address already in use | پورت توسط فرایند دیگری اشغال شده است |
certbot با خطا پایان می‌یابد | DNS، پورت 80 یا server_name متعلق به دیگری |
xpanel-db در وضعیت unhealthy | .env، والیوم یا نسخه PostgreSQL |
| 502 Bad Gateway از nginx | پنل به 127.0.0.1:3000 گوش نمی‌دهد |
| ورود از کار افتاده است | APP_SECRET تغییر کرده است |
«Reverse proxy and HTTPS are required»
نشانه. پنل باز نمی‌شود، در لاگ xpanel خط
Reverse proxy and HTTPS are required وجود دارد.
علت. درخواست بدون هدرهای X-Forwarded-For و
X-Forwarded-Proto: https به پنل رسیده است. در کد پنل میان‌افزاری وجود دارد که در این حالت
اتصال را قطع می‌کند.
راه‌حل. مطمئن شوید که در پیکربندی nginx جلوی پنل هر دو خط وجود دارد:
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
پنل را با https:// باز کنید، نه با http://. اگر TLS زودتر
(روی CDN یا لودبالانسر) ترمینیت می‌شود، مقدار X-Forwarded-Proto را به http تغییر ندهید.
پیکربندی‌های آماده — در بخش پروکسی معکوس.
METRICS_USER و METRICS_PASS تنظیم نشده‌اند
نشانه. کانتینر xpanel دوباره راه‌اندازی می‌شود، در لاگ ❌ METRICS_USER
یا ❌ METRICS_PASS دیده می‌شود.
علت. متغیرهای متریک الزامی هستند: بدون آن‌ها پنل بالا نمی‌آید.
راه‌حل. در /opt/xlada/.env اضافه کنید و استک را دوباره راه‌اندازی کنید:
METRICS_USER=xpanel
METRICS_PASS=<رمز عبور مطمئن>
docker compose up -d
نود در پنل ظاهر نمی‌شود
نشانه. نود ساخته شده است، اما در پنل همچنان متصل‌نشده می‌ماند.
علت. معمولاً یکی از این سه مورد: NODE_PORT از سرور پنل در دسترس نیست،
SECRET_KEY کامل کپی نشده است یا کانتینر نود بالا نیامده است.
راه‌حل. به ترتیب بررسی کنید:
docker logs -f xpanel-node— در صورت نادرست بودن کلید، نود خودش علت را چاپ می‌کند.- از سرور پنل:
nc -vz <IP نود> 2222. - مطمئن شوید که کلید کامل و بدون خط جدید وارد شده است.
- پورت
2222را در firewall فقط برای IP پنل باز کنید.
جزئیات بیشتر — در بخش نصب نود.
هر نود SECRET_KEY و گواهی اختصاصی خود را دارد. کلید مشترک برای چند سرور
پیش‌بینی نشده است — انتقال آن از یک نود به نود دیگر
مجاز نیست.
تعارض پورت‌ها
نشانه. کانتینر با address already in use بالا نمی‌آید، یا Xray روی
نود به پورت تعیین‌شده گوش نمی‌دهد.
علت. پورت توسط فرایند دیگری اشغال شده است: 3000، 3001، 3010 روی سرور
پنل یا پورت inbound روی نود.
راه‌حل. صاحب پورت را پیدا کنید و آن را آزاد کنید:
ss -tlnp | grep -E ':(3000|3001|3010|2222)\b'
اگر تغییر پورت آسان‌تر از آزاد کردن آن است، APP_PORT یا
METRICS_PORT را در .env اصلاح کنید و فراموش نکنید proxy_pass را در nginx به‌روز کنید. روی نود
بررسی کنید که کانتینر با --network host اجرا شده است: عبور دادن پورت‌ها
تعیین IP واقعی کاربر را خراب می‌کند.
گواهی صادر نمی‌شود
نشانه. certbot --nginx -d panel.example.com با خطا پایان می‌یابد.
علت. دامنه به این سرور اشاره نمی‌کند، پورت 80 بسته است یا دامنه
هم‌اکنون توسط یک هاست مجازی دیگر سرو می‌شود.
راه‌حل.
dig +short panel.example.com # باید IP سرور پنل را برگرداند
ss -tlnp | grep ':80'
certbot certificates # چه چیزی قبلاً صادر شده است
certbot renew --dry-run # بررسی تمدید خودکار
مقدار server_name را در پیکربندی nginx بررسی کنید، سپس nginx -t && systemctl reload nginx.
مطمئن شوید که تایمر تمدید خودکار فعال است: systemctl list-timers | grep certbot.
پایگاه داده بالا نمی‌آید
نشانه. xpanel منتظر پایگاه داده می‌ماند و از کار می‌افتد، xpanel-db در وضعیت unhealthy
است یا مدام دوباره راه‌اندازی می‌شود.
علت. بیشتر اوقات DATABASE_URL نادرست، ناسازگاری
POSTGRES_PASSWORD با والیوم موجود یا نسخه اصلی (major) ناسازگار
PostgreSQL روی دایرکتوری داده قدیمی.
راه‌حل.
docker compose ps
docker compose logs --tail=100 xpanel-db
docker exec xpanel-db pg_isready -U xpanel -d xpanel
مقادیر POSTGRES_USER، POSTGRES_PASSWORD، POSTGRES_DB و DATABASE_URL را بررسی کنید.
والیوم‌ها و سرویس‌ها را تغییر نام ندهید: در اجرای بعدی compose نمونه‌های
خالی جدیدی می‌سازد. دایرکتوری داده PostgreSQL بین نسخه‌های اصلی ناسازگار است، بنابراین
مهاجرت به نسخه جدید فقط از طریق دامپ و بازیابی انجام می‌شود — ببینید
مهاجرت از Remnawave.
502 Bad Gateway از nginx
نشانه. nginx روی https://panel.example.com کد 502 برمی‌گرداند.
علت. پشت proxy_pass هیچ‌کس نیست: کانتینر پنل اجرا نشده است، مهاجرت‌ها را
نگذرانده است یا به پورت دیگری گوش می‌دهد.
راه‌حل.
docker compose ps
curl -sI http://127.0.0.1:3000
docker compose logs --tail=100 xpanel
منتظر بمانید تا در لاگ خطوط XLADA Backend v1.1.7 و
Nest application successfully started ظاهر شوند. اگر APP_PORT تغییر کرده است،
proxy_pass http://127.0.0.1:<پورت> را اصلاح کنید و nginx را دوباره بارگذاری کنید.
ورود پس از تغییر APP_SECRET کار نمی‌کند
نشانه. رمز عبور مدیر دیگر پذیرفته نمی‌شود، کدهای TOTP پذیرفته نمی‌شوند، نشست‌های فعال بازنشانی شده‌اند.
علت. APP_SECRET پس از اولین اجرا تغییر کرده است. هش‌های رمز عبور،
JWT و رمزنگاری راز TOTP به آن وابسته‌اند. مقدار
change_me که در .env باقی مانده است هم همین اثر را دارد.
راه‌حل. مقدار قبلی APP_SECRET را از نسخه پشتیبان .env برگردانید و
دستور docker compose up -d را اجرا کنید. اگر مقدار اصلی از دست رفته است، ورود تنها
با بازنشانی از طریق پایگاه داده ممکن است. راز را از قبل تولید می‌کنند (openssl rand -hex 32) و
در مدیر رازها نگه می‌دارند — ببینید امنیت پنل.