Skip to content

عیب یابی ​

این صفحه مشکلات رایج و نحوه تشخیص آنها را گردآوری میکند. ابتدا لاگ های مرتبط را بررسی کنید، سپس به بخشی بروید که با نشانه شما مطابقت دارد.

ابتدا کجا را بررسی کنیم ​

منبعدستوربرای چه چیزی
لاگ های سرویس (systemd)sudo journalctl -u songbird -fکرش اپلیکیشن، خطاهای راه اندازی، استثناهای زمان اجرا.
لاگ های Dockerdocker compose -f docker-compose.yaml logs -fهمانند بالا، برای نصب های Docker.
لاگ خطای Nginxsudo tail -f /var/log/nginx/error.logخطاهای 502/504، مشکلات پراکسی و TLS.
لاگ دسترسی Nginxsudo tail -f /var/log/nginx/access.logتأیید رسیدن درخواست ها به سرور و کدهای وضعیت آنها.
لاگ اسکریپت نصبcat /opt/songbird/logs/install.logشکست ها در حین نصب/به روزرسانی از طریق songbird-deploy.

TIP

اسکریپت نصب یک منوی داخلی View Logs دارد که همه اینها را بدون تایپ مسیرها باز میکند.

مرجع سریع نشانه ها ​

نشانهحوزه محتملپرش به
نصب هنگام دانلود بسته ها متوقف میشودمحدودیت های شبکهتوقف نصب هنگام دانلود بسته ها
دامنه resolve نمیشود / گواهینامه شکست میخوردتفکیک DNSمشکلات تفکیک DNS
502 Bad Gatewayاپلیکیشن در حال اجرا نیست یا پورت پراکسی نادرست استاپلیکیشن راه اندازی نمیشود / 502
سایت بارگذاری میشود اما به روزرسانی های زنده متوقف میشوندبافرینگ SSE/پراکسیبه روزرسانی های بیدرنگ نمیرسند
Push notifications هرگز نمیرسندHTTPS یا شبکه/پراکسیPush notifications
آپلودها رد میشوند یا شکست میخورندمحدودیت های اندازه یا دیسکشکست در آپلود فایل ها
ویدیوها پخش نمیشوندFFmpeg / ترنسکد / Workerمشکلات ترنسکد ویدیو
بیلد Docker متوقف به نظر میرسددانلود وابستگی هامشکلات بیلد Docker
خطاهای TLS/گواهینامهمسیرهای گواهینامه یا تمدیدمشکلات TLS / گواهینامه
خطای SSL / گواهی CA پایگاه داده PostgreSQLگواهی SSL / CA دیتابیس ابریخطاهای SSL و گواهی CA در PostgreSQL
کانال ریموت بازتاب نمیدهداعتبارنامه های Telegram / صفکانال ریموت
کنترل سرویس در پنل مدیریت شکست میخوردمجوزهامشکلات پنل مدیریت

توقف نصب هنگام دانلود بسته ها ​

در حین نصب، Songbird نیاز به دانلود بسته های سیستمی و وابستگی ها دارد: بسته های apt، پکیج Node.js (از طریق NodeSource)، بسته های npm و برای نصب های Docker، ایمیج ها و بسته های Docker. در سرورهایی با شبکه های دارای محدودیت شدید یا فیلترشده، این دانلودها ممکن است متوقف شوند، با timeout مواجه گردند یا کاملاً شکست بخورند.

نشانه های معمول:

  • نصب کننده یا docker compose build در مرحله دانلود/npm ci/apt-get install فریز به نظر میرسد.
  • خطاهایی که به خطای مهلت زمانی اتصال (timeout)، خطای TLS handshake یا غیرقابل دسترس بودن هاست ها اشاره میکنند.

برای دور زدن محدودیت، ابزارهای مدیریت بسته را به سمت میرورهای دردسترس هدایت کنید یا ترافیک را از طریق یک پراکسی عبور دهید.

ابزارراهحل
aptاز یک میرور در دسترس apt استفاده کنید.
Node.js (NodeSource)از یک میرور NodeSource استفاده کنید.
npmاز یک رجیستری میرور جایگزین npm استفاده کنید.
Docker / خروجی عمومییک پراکسی HTTP/HTTPS برای شل یا daemon داکر پیکربندی کنید.

اگر با اسکریپت نصب نصب میکنید، از منوی Configure mirrors آن برای تنظیم میرورهای NodeSource، apt و npm قبل از نصب استفاده کنید. آن صفحه همچنین نمونه های میرورهای فعال (از جمله نمونه های قابل استفاده در شبکه محدود ایران) و نحوه راه اندازی پراکسی را فهرست میکند.

مشکلات تفکیک DNS ​

بررسیجزئیات
رکورد A اشاره میکند به IPمطمئن شوید yourdomain.com به IP عمومی سرور اشاره میکند (dig +short yourdomain.com یا nslookup yourdomain.com).
انتشار DNSرکوردهای جدید DNS ممکن است تا چند دقیقه (گاهی بیشتر بسته به TTL) زمان ببرند.
پورت های 80 و 443 باز هستندفایروال ها (ufw، فایروال ابری، گروه های امنیتی) باید ترافیک ورودی روی پورت های 80 و 443 را مجاز کنند.
نام دامنه با .env مطابقت دارداگر از متغیرهای دامنه استفاده میکنید، مطمئن شوید بدون فاصله یا خطای تایپی هستند.

اپلیکیشن راه اندازی نمیشود / 502 Bad Gateway ​

خطای 502 Bad Gateway از Nginx یعنی Nginx در حال اجراست اما نمیتواند به بکاند Songbird متصل شود.

bash
# 1. وضعیت بکاند را بررسی کنید
# استقرار Systemd:
sudo systemctl status songbird
sudo journalctl -u songbird -n 50 --no-pager

# استقرار Docker:
docker compose -f docker-compose.yaml ps
docker compose -f docker-compose.yaml logs --tail=50 songbird

# 2. بررسی کنید بکاند روی پورت مورد انتظار گوش میدهد (پیشفرض: 5174)
ss -tulpn | grep 5174

# 3. خطاهای Nginx را بررسی کنید
sudo tail -n 50 /var/log/nginx/error.log

علل رایج:

  • تداخل پورت: سرویس دیگری از قبل روی پورت 5174 گوش میدهد. SERVER_PORT را در .env تغییر دهید و بلوک proxy_pass در Nginx را همسو کنید.
  • Node.js پشتیبانی نشده: نسخه Node را تأیید کنید (node -v — به Node.js 24+ نیاز دارد).
  • مجوزهای دایرکتوری data: مطمئن شوید کاربر سرویس مالک data/ است (sudo chown -R songbird:songbird /opt/songbird/data).
  • فایل .env نامعتبر: خطاهای نحوی، کاراکترهای نقل قول نامعتبر یا متغیرهای گمشده در .env.
  • کانفیگ Nginx به پورت اشتباه اشاره میکند: پورت proxy_pass در کانفیگ Nginx را با SERVER_PORT مقایسه کنید.

برطرف کردن خطای 502 در محیط های ابری (Render, Railway, Fly.io) ​

اگر هنگام استفاده از استقرار ابری خطای ۵۰۲ دریافت میکنید:

  1. بررسی پورت: مطمئن شوید پورت سرویس شما در پنل به درستی روی ۵۱۷۴ (یا مقدار SERVER_PORT) تنظیم شده است.
  2. بررسی Mount مسیر دیتا: پلتفرم هایی مثل Render نیاز دارند متغیر DATA_DIR به مسیر Volume متصل شده اشاره کند (مانند DATA_DIR=/data). اگر دیتا دایرکتوری به اشتباه کانفیگ شده باشد، سرور بالا نمی آید.
  3. لاگ های Build و Deploy: مطمئن شوید بیلد بدون خطا پایان یافته و وابستگی های دیتابیس مهیا هستند.

تداخل پورت با Nginx ​

اگر وب سرور دیگری (مانند Apache یا نمونه Nginx دیگر) از قبل روی پورت 80 یا 443 اجرا میشود، Nginx شروع به کار نخواهد کرد:

bash
# بررسی کنید چه چیزی روی پورت های 80 و 443 گوش میدهد
sudo ss -tulpn | grep -E ':(80|443)\b'

سرویس متداخل را متوقف یا بازپیکربندی کنید، سپس Nginx را راه اندازی مجدد کنید:

bash
sudo nginx -t
sudo systemctl reload nginx

به روزرسانی های بیدرنگ نمیرسند ​

پلتفرم Songbird از یک اتصال دائمی WebSocket برای پیام های زنده، وضعیت آنلاین بودن و وضعیت در حال تایپ استفاده میکند و جریان Server-Sent Events (SSE) را به عنوان پشتیبان در نظر میگیرد. کاربر تا زمانی که هرگونه اتصال زنده برقرار باشد آنلاین نشان داده میشود و با بسته شدن آخرین اتصال آفلاین خواهد شد. اگر پیام ها فقط پس از رفرش صفحه ظاهر میشوند، احتمالاً جریان SSE توسط Nginx بافر میشود.

  • مطمئن شوید بلوک location مربوط به /api/events وجود دارد و بافرینگ را غیرفعال میکند (proxy_buffering off;، add_header X-Accel-Buffering no;). به کانفیگ Nginx مراجعه کنید.
  • تأیید کنید هر پراکسی بالادستی یا CDN اتصال را بافر یا timeout نمیکند.
  • بررسی کنید proxy_read_timeout / proxy_send_timeout به اندازه کافی طولانی هستند (کانفیگ نمونه از 1h استفاده میکند).

Push notifications نمیرسند ​

نیازمندیجزئیات
HTTPSسرویس Push به HTTPS نیاز دارد، مگر در localhost. نصب های HTTP ساده نمیتوانند push ارسال کنند.
کلیدهای VAPIDمقادیر VAPID_PUBLIC_KEY، VAPID_PRIVATE_KEY و VAPID_SUBJECT باید تنظیم شوند (در اولین اجرا به طور خودکار تولید میشوند).
iOSدر iOS 16.4+ به یک PWA نصب شده نیاز دارد.
دسترسی به شبکهسرور باید به اندپوینت های push (مانند FCM، Mozilla، Apple) دسترسی داشته باشد.

اگر لاگ ها [push] delivery failed ... status=0 ... AggregateError را نشان میدهند، سرور نمیتواند به سرویس های push دسترسی پیدا کند. دلایل رایج: مسدودکردن HTTPS خروجی توسط فایروال، شکست های DNS، یا شبکه ای که به پراکسی نیاز دارد. یک پراکسی را از طریق پراکسی Push notification پیکربندی کنید و اتصال را آزمایش کنید:

bash
curl -x http://your-proxy:3128 https://fcm.googleapis.com

شکست در آپلود فایل ها ​

علتراهحل
آپلود بزرگتر از سقف هر فایلFILE_UPLOAD_MAX_SIZE_MB را افزایش دهید.
مجموع پیام از سقف فراتر میرودFILE_UPLOAD_MAX_TOTAL_SIZE_MB را افزایش دهید و client_max_body_size در Nginx را همسو کنید.
فایل های بیش از حد در یک پیامFILE_UPLOAD_MAX_FILES را افزایش دهید.
آپلودها غیرفعال هستندFILE_UPLOAD=true را تنظیم کنید.
Nginx بدنه های بزرگ را رد میکند (413)برای STORAGE_DRIVER=local مقدار client_max_body_size را برابر با FILE_UPLOAD_MAX_TOTAL_SIZE_MB تنظیم کنید.
خطای CORS در مرورگر هنگام آپلود به R2/S3قانون CORS باکت خود را طوری تنظیم کنید که متدهای PUT، GET، HEAD، POST، دامنه مبدا و هدر ETag مجاز باشند. مستندات الزامات CORS ذخیره سازی ابری را ببینید.
خطای CORS در مرورگر هنگام آپلود به باکت Railwayبا STORAGE_AUTO_CORS=true (تنظیم شده در .railway/railway.ts) سرور خودش این کار را میکند — لاگ سرور را برای عبارت Bucket CORS policy applied / already configured بررسی کنید. اگر هشدار پیکربندی خودکار دیدید، دستی اعمال کنید: npm --prefix server run storage:cors -- --origin https://your-app.up.railway.app.
خطای Failed to notify callback در لاگ ورکر با پورت خالی (...internal:/api/...)متغیر PORT را در WEBHOOK_URL قالب بندی نکنید — مقدار آن هنگام اجرای کانتینر تزریق میشود و هیچ ارجاع IaC نمیتواند آن را بگیرد. WEBHOOK_URL را خالی بگذارید تا سرور آن را از RAILWAY_PRIVATE_DOMAIN و PORT بسازد (server/lib/webhookUrl.js).
خطای Failed to notify callback در لاگ ورکر (رد اتصال)برنامه باید ترافیک IPv6 شبکه خصوصی را بپذیرد: مقدار BIND_ADDRESS=:: (دوگانه، dual-stack) را در Railway تنظیم کنید. همچنین مطمئن شوید هر دو سرویس دیپلوی مجدد را کامل کرده اند و برنامه روی هاست و پورت WORKER_URL/WEBHOOK_URL در دسترس است.
خطای 403 Forbidden روی URLهای Presignedمقادیر STORAGE_ACCESS_KEY_ID، STORAGE_SECRET_ACCESS_KEY، دسترسی های باکت و همگام بودن ساعت سیستم را بررسی کنید.
خطای ۵۰۰ در ساخت Presigned URLمتغیرهای STORAGE_ENDPOINT و STORAGE_BUCKET و لاگ های سرور را بررسی کنید.
عدم دسترسی مرورگر به اندپوینت ذخیره سازیاطمینان حاصل کنید STORAGE_ENDPOINT یک آدرس عمومی HTTPS قابل دسترس از شبکه کاربران است.
دیسک پر است (ذخیره سازی محلی)فضای آزاد را با npm run db:inspect (استفاده از دیسک را گزارش میکند) یا df -h بررسی کنید.

پس از تغییر .env، تغییرات را اعمال کنید (به متغیرهای محیطی مراجعه کنید).

مشکلات ترنسکد ویدیو ​

پلتفرم Songbird هنگام فعال بودن FILE_UPLOAD_TRANSCODE_VIDEOS=true، ویدیوهای آپلودشده را به فرمت سازگار وب H.264/AAC MP4 بهینه سازی و ترنسکد میکند.

  • بررسی سلامت Media Worker: در صورت استفاده از Media Worker مستقل، وضعیت آن را با curl http://localhost:8080/health (یا استفاده از پورت تنظیم شده WORKER_PORT / نشانی WORKER_URL/health) بررسی کنید. پاسخ باید حاوی {"status": "ok", ...} باشد. برای راهنمای جامع به ورکر مدیا مراجعه کنید.
  • همگام بودن Webhook Secret: مطمئن شوید مقدار WEBHOOK_SECRET در سرور Songbird با مقدار تنظیم شده در Media Worker یکسان است. در صورت عدم تطابق، درخواست ها با خطای 401 Unauthorized رد میشوند.
  • دسترسی به Callback سرور: ورکر باید بتواند به اندپوینت کالبک سرور Songbird (POST /api/uploads/webhook/processed) متصل شود. در صورتی که سرور پشت ریورس پروکسی قرار دارد، متغیر WEBHOOK_URL (یا نام جایگزین WEBHOOK_CALLBACK_URL) را تنظیم کنید یا از صحت ارتباط شبکه ای میان ورکر و سرور اطمینان حاصل نمایید.
  • بررسی نصب FFmpeg: در صورت استفاده از حالت پردازش محلی (local) یا اجرای مستقیم ورکر از سورس، از نصب بودن ffmpeg و ffprobe روی سیستم اطمینان حاصل کنید (ffmpeg -version).
  • فضای دیسک موقت: اطمینان حاصل کنید که گره ورکر یا سرور فضای دیسک موقت کافی (در دایرکتوری موقت سیستم) برای دانلود، پردازش، ترنسکد و تولید تصویر thumbnail در اختیار دارد.
  • بررسی لاگ های سرویس و ورکر: لاگ های سرور و ورکر را برای پیام های [worker] یا [app-debug] بررسی کنید.
  • فعال سازی لاگ دیباگ: مقدار APP_DEBUG=true را در فایل .env سرور Songbird فعال کنید تا جزئیات کامل فرآیند آپلود، ارسال به ورکر و به روزرسانی زنده رویدادها را در کنسول مشاهده نمایید.

مشکلات بیلد Docker ​

اگر docker compose build در RUN npm ci متوقف به نظر میرسد، معمولاً در حال دانلود وابستگی هاست. آن را با حالت progress ساده اجرا کنید تا ببینید چه اتفاقی میافتد:

bash
docker compose -f docker-compose.yaml build --no-cache --progress=plain

بررسی های دیگر:

  • سلامت کانتینر را تأیید کنید: docker compose -f docker-compose.yaml ps.
  • لاگ های کانتینر را دنبال کنید: docker compose -f docker-compose.yaml logs -f.

مشکلات TLS / گواهینامه ​

نشانهبررسی
مرورگر درباره گواهینامه نامعتبر هشدار میدهدتأیید کنید که مسیرهای ssl_certificate / ssl_certificate_key در Nginx به فایل های معتبر اشاره میکنند.
تمدید Certbot شکست میخوردsudo certbot renew --dry-run را اجرا کنید و قابلیت دسترسی DNS/پورت 80 را بررسی کنید.
گواهینامه مبتنی بر IP منقضی شدهروند گواهینامه IP از گواهینامه های کوتاه مدت (۶ روزه) استفاده میکند که توسط یک تایمر به طور خودکار تمدید میشوند؛ فعال بودن تایمر songbird-lego-renew را تأیید کنید.
هشدار خودامضا (پیشفرض Docker)با گواهینامه خودامضای پیشفرض موردانتظار است. برای محیط تولید با گواهینامه های واقعی جایگزین کنید.

برای گزینه های کامل راه اندازی به گواهینامه های SSL مراجعه کنید.

خطاهای SSL و گواهی CA در PostgreSQL ​

هنگام اتصال Songbird به پایگاه های داده مدیریت شده ابری PostgreSQL (مانند Aiven، AWS RDS، DigitalOcean، Supabase یا Neon)، ممکن است اتصال هنگام شروع برنامه یا در حین مایگریشن های پایگاه داده با خطا مواجه شود.

خطای self-signed certificate in certificate chain / SELF_SIGNED_CERT_IN_CHAIN ​

نشانه:

txt
[db-migrations] Error initializing Postgres schema sets: Error: self-signed certificate in certificate chain
  code: 'SELF_SIGNED_CERT_IN_CHAIN'
Acquire connection error: Error: self-signed certificate in certificate chain

علت: ارائه دهندگان پایگاه داده ابری اتصالات را با استفاده از مرجع گواهی (CA) اختصاصی پروژه خود رمزنگاری میکنند. از آنجا که این CA سفارشی در مخزن پیشفرض گواهی های مورد اعتماد Node.js قرار ندارد، Node.js اتصال را رد میکند.

راه حل: گواهی CA ارائه دهنده دیتابیس را از طریق متغیر محیطی NODE_EXTRA_CA_CERTS به Node.js معرفی کنید:

  1. گواهی CA Certificate (ca.pem) را از داشبورد دیتابیس ابری خود (مثلاً پنل Aiven) دانلود یا کپی کنید.

  2. در Render یا پلتفرم های PaaS:

    • در داشبورد Render به تب Environment سرویس خود بروید.

    • در بخش Secret Files، فایلی با نام aiven-ca.pem (یا /etc/secrets/aiven-ca.pem) ایجاد کرده و متن گواهی PEM را در آن قرار دهید.

    • متغیر محیطی زیر را اضافه کنید:

      txt
      NODE_EXTRA_CA_CERTS=/etc/secrets/aiven-ca.pem
  3. در Docker یا VPS:

    • فایل گواهی CA را روی دیسک ذخیره کنید (مثلاً /opt/songbird/certs/ca.pem یا آن را درون کانتینر mount کنید).

    • در فایل .env یا متغیرهای کانتینر مقدار زیر را تنظیم کنید:

      txt
      NODE_EXTRA_CA_CERTS=/opt/songbird/certs/ca.pem

کانال ریموت بازتاب نمیدهد ​

بررسیجزئیات
فعال بودن قابلیتREMOTE_CHANNEL=true باید روی این سرور تنظیم شده باشد.
اعتبارنامه های TelegramAPI ID، API hash و رشته session باید پیکربندی شوند. npm run remote:configure را اجرا کنید.
عمومی بودن کانالکانال ریموت برای کانال های خصوصی قفل است.
تاریخچه وارد نشدهدر اولین فعال سازی، تنها پست های منتشرشده پس از آن نقطه بازتاب داده میشوند، نه تاریخچه.
صف متوقف شدهبا npm run db:chat:edit -- <channel> --resume-queue از سر بگیرید.
نیاز به پراکسیاگر سرور نمیتواند به Telegram دسترسی پیدا کند، یک پراکسی تنظیم کنید (REMOTE_CHANNEL_TELEGRAM_PROXY_URL).

برای راهنمای کامل پیکربندی به راه اندازی کانال ریموت مراجعه کنید.

مشکلات پنل مدیریت ​

قابلیت های کنترل سرویس (ریستارت/توقف) و مشاهده لاگ های سیستم در پنل مدیریت بسته به نحوه استقرار Songbird به مجوزهای خاصی نیاز دارند.

TIP

اگر با هر یک از مشکلات ذکرشده در زیر مواجه شدید، نصب مجدد اپلیکیشن از طریق اسکریپت نصب باید مشکل را حل کند.

کنترل سرویس کار نمیکند ​

استقرارهای Systemd:

  • کاربر سرویس به مجوزهای sudo برای دستورات systemctl نیاز دارد

  • یک فایل sudoers برای کاربر songbird ایجاد کنید:

    bash
    sudo visudo -f /etc/sudoers.d/songbird
  • این خطوط را اضافه کنید (اگر از کاربر سرویس متفاوتی استفاده میکنید songbird را جایگزین کنید):

    txt
    songbird ALL=(ALL) NOPASSWD: /bin/systemctl restart songbird.service
    songbird ALL=(ALL) NOPASSWD: /bin/systemctl stop songbird.service
    songbird ALL=(ALL) NOPASSWD: /bin/systemctl status songbird.service
  • ذخیره کنید و مطمئن شوید مجوزها صحیح هستند:

    bash
    sudo chmod 0440 /etc/sudoers.d/songbird

استقرارهای PM2:

  • پروسه باید به runtime PM2 دسترسی داشته باشد
  • اطمینان حاصل کنید PM2 با همان کاربری که Songbird را اجرا میکند، در حال اجراست
  • کاربر باید مجوز اجرای pm2 restart و pm2 stop را داشته باشد

لاگ های سیستم نمایش داده نمیشوند ​

Systemd:

  • کاربر سرویس به مجوز خواندن لاگ های journal و لاگ های nginx نیاز دارد

  • کاربر را به گروه systemd-journal اضافه کنید:

    bash
    sudo usermod -a -G systemd-journal songbird
  • کاربر را به گروه adm اضافه کنید:

    bash
    sudo usermod -a -G adm songbird
  • سرویس را راه اندازی مجدد کنید:

    bash
    sudo systemctl restart songbird

Docker:

  • اطمینان حاصل کنید که سوکت Docker mount شده است (همانند کنترل سرویس بالا)
  • کانتینر باید برای خواندن لاگ ها از طریق API Docker دسترسی داشته باشد

هنوز گیر کرده اید؟ ​

اگر هیچ یک از موارد بالا مشکل را حل نکرد، خروجی لاگ مرتبط را جمع آوری کرده و یک issue در مخزن پروژه باز کنید.

تحت لایسنس MIT منتشر شده است.