عیب یابی
این صفحه مشکلات رایج و نحوه تشخیص آنها را گردآوری میکند. ابتدا لاگ های مرتبط را بررسی کنید، سپس به بخشی بروید که با نشانه شما مطابقت دارد.
ابتدا کجا را بررسی کنیم
| منبع | دستور | برای چه چیزی |
|---|---|---|
| لاگ های سرویس (systemd) | sudo journalctl -u songbird -f | کرش اپلیکیشن، خطاهای راه اندازی، استثناهای زمان اجرا. |
| لاگ های Docker | docker compose -f docker-compose.yaml logs -f | همانند بالا، برای نصب های Docker. |
| لاگ خطای Nginx | sudo tail -f /var/log/nginx/error.log | خطاهای 502/504، مشکلات پراکسی و TLS. |
| لاگ دسترسی Nginx | sudo 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 متصل شود.
# 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)
اگر هنگام استفاده از استقرار ابری خطای ۵۰۲ دریافت میکنید:
- بررسی پورت: مطمئن شوید پورت سرویس شما در پنل به درستی روی ۵۱۷۴ (یا مقدار
SERVER_PORT) تنظیم شده است. - بررسی Mount مسیر دیتا: پلتفرم هایی مثل Render نیاز دارند متغیر
DATA_DIRبه مسیر Volume متصل شده اشاره کند (مانندDATA_DIR=/data). اگر دیتا دایرکتوری به اشتباه کانفیگ شده باشد، سرور بالا نمی آید. - لاگ های Build و Deploy: مطمئن شوید بیلد بدون خطا پایان یافته و وابستگی های دیتابیس مهیا هستند.
تداخل پورت با Nginx
اگر وب سرور دیگری (مانند Apache یا نمونه Nginx دیگر) از قبل روی پورت 80 یا 443 اجرا میشود، Nginx شروع به کار نخواهد کرد:
# بررسی کنید چه چیزی روی پورت های 80 و 443 گوش میدهد
sudo ss -tulpn | grep -E ':(80|443)\b'سرویس متداخل را متوقف یا بازپیکربندی کنید، سپس Nginx را راه اندازی مجدد کنید:
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 پیکربندی کنید و اتصال را آزمایش کنید:
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 ساده اجرا کنید تا ببینید چه اتفاقی میافتد:
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
نشانه:
[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 معرفی کنید:
گواهی CA Certificate (
ca.pem) را از داشبورد دیتابیس ابری خود (مثلاً پنل Aiven) دانلود یا کپی کنید.در Render یا پلتفرم های PaaS:
در داشبورد Render به تب Environment سرویس خود بروید.
در بخش Secret Files، فایلی با نام
aiven-ca.pem(یا/etc/secrets/aiven-ca.pem) ایجاد کرده و متن گواهی PEM را در آن قرار دهید.متغیر محیطی زیر را اضافه کنید:
txtNODE_EXTRA_CA_CERTS=/etc/secrets/aiven-ca.pem
در Docker یا VPS:
فایل گواهی CA را روی دیسک ذخیره کنید (مثلاً
/opt/songbird/certs/ca.pemیا آن را درون کانتینر mount کنید).در فایل
.envیا متغیرهای کانتینر مقدار زیر را تنظیم کنید:txtNODE_EXTRA_CA_CERTS=/opt/songbird/certs/ca.pem
کانال ریموت بازتاب نمیدهد
| بررسی | جزئیات |
|---|---|
| فعال بودن قابلیت | REMOTE_CHANNEL=true باید روی این سرور تنظیم شده باشد. |
| اعتبارنامه های Telegram | API 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 ایجاد کنید:
bashsudo visudo -f /etc/sudoers.d/songbirdاین خطوط را اضافه کنید (اگر از کاربر سرویس متفاوتی استفاده میکنید
songbirdرا جایگزین کنید):txtsongbird 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ذخیره کنید و مطمئن شوید مجوزها صحیح هستند:
bashsudo chmod 0440 /etc/sudoers.d/songbird
استقرارهای PM2:
- پروسه باید به runtime PM2 دسترسی داشته باشد
- اطمینان حاصل کنید PM2 با همان کاربری که Songbird را اجرا میکند، در حال اجراست
- کاربر باید مجوز اجرای
pm2 restartوpm2 stopرا داشته باشد
لاگ های سیستم نمایش داده نمیشوند
Systemd:
کاربر سرویس به مجوز خواندن لاگ های journal و لاگ های nginx نیاز دارد
کاربر را به گروه
systemd-journalاضافه کنید:bashsudo usermod -a -G systemd-journal songbirdکاربر را به گروه
admاضافه کنید:bashsudo usermod -a -G adm songbirdسرویس را راه اندازی مجدد کنید:
bashsudo systemctl restart songbird
Docker:
- اطمینان حاصل کنید که سوکت Docker mount شده است (همانند کنترل سرویس بالا)
- کانتینر باید برای خواندن لاگ ها از طریق API Docker دسترسی داشته باشد
هنوز گیر کرده اید؟
اگر هیچ یک از موارد بالا مشکل را حل نکرد، خروجی لاگ مرتبط را جمع آوری کرده و یک issue در مخزن پروژه باز کنید.