پنل مدیریت

پنل مدیریت یک رابط مبتنی بر وب برای مدیریت کاربران، چت‌ها، تنظیمات زمان اجرا و عملیات سیستم فراهم می‌کند. برای کاربران با نقش مالک (owner) یا مدیر (admin) قابل دسترسی است.

نقش‌های کاربر

• Owner (مالک): دسترسی کامل به پنل مدیریت و همه قابلیت‌ها
• Admin (مدیر): دسترسی محدود به پنل مدیریت
• User (کاربر): کاربر عادی بدون دسترسی مدیریتی

WARNING

فقط یک کاربر با نقش مالک می‌تواند وجود داشته باشد.

دسترسی به پنل مدیریت

دو روش اصلی برای اعطای نقش مالک (owner) یا مدیر (admin) به یک حساب کاربری وجود دارد:

روش ۱: از طریق CLI / اسکریپت نصب (سرورهای VPS و محیط های دارای دسترسی به ترمینال)

1. یک کاربر ایجاد یا ویرایش کنید و نقش مالک یا مدیر به آن‌ها بدهید (در نصب جدید درخواست می‌شود، یا بعداً از طریق اسکریپت نصب):

songbird-deploy
# به زیرمنوی "Manage Database" بروید
# "Create user" یا "Edit user" را انتخاب کنید
# دستورات را دنبال کرده و نقش "owner" یا "admin" را انتخاب کنید

اگر ترجیح می‌دهید می‌توانید از دستورات دیتابیس نیز استفاده کنید:

cd /opt/songbird/server
# اگر می‌خواهید کاربر جدید ایجاد کنید
npm run db:user:create
# یا اگر می‌خواهید کاربری را ارتقا دهید
npm run db:user:edit
# دستورات را دنبال کرده و نقش "owner" یا "admin" را انتخاب کنید

2. با حساب ارتقا‌یافته به برنامه Songbird خود وارد شوید

3. روی دکمه Admin Panel در نوار کناری کلیک کنید (فقط برای مالک و مدیران قابل دسترسی است).

روش ۲: ارتقای مدیریت اضطراری و مالکان (PaaS و رابط کاربری وب)

برای استقرار روی سرویس دهنده های PaaS (مانند Render، Railway یا Fly.io) یا پلتفرم های کانتینری که دسترسی به ترمینال در آنها در دسترس نیست، کاربران احراز هویت شده میتوانند مستقیماً از طریق رابط کاربری وب دسترسی مدیریت را دریافت کنند:

۱. متغیر محیطی ADMIN_API_TOKEN را در تنظیمات سرویس خود (مثلاً داشبورد PaaS) پیکربندی کنید. در صورت عدم تنظیم، Songbird در اولین اجرا توکنی به صورت خودکار تولید کرده و در .env ذخیره میکند.

۲. با حساب کاربری ثبت نام شده خود وارد شوید.

۳. مرورگر خود را باز کرده و مستقیماً به آدرس /admin بروید.

۴. توکن ADMIN_API_TOKEN را در فرم Emergency Admin Access وارد کنید.

۵. روی دکمه Claim Privileges کلیک کنید.

قوانین ارتقای نقش ها

• اولین درخواست (Owner): اگر هیچ کاربری در حال حاضر نقش owner را نداشته باشد، کاربر درخواست کننده به نقش owner ارتقا می یابد.
• درخواست های بعدی (Admin): اگر کاربر owner قبلاً وجود داشته باشد، درخواست های بعدی کاربر را به نقش admin ارتقا میدهند.

الزام HTTPS

ارتقای مدیریت اضطراری نیازمند اتصال امن (HTTPS) یا شبکه محلی (localhost یا 127.0.0.1 یا ::1) است. اتصالات ناامن HTTP روی سرورهای ریموت این قابلیت را مسدود میکنند.

هشدار امنیتی

به هیچ وجه ADMIN_API_TOKEN خود را منتشر نکنید و مخفی نگه دارید. هرکس با استفاده از این توکن میتواند به پنل ادمین دسترسی پیدا کند.

تب داشبورد

داشبورد یک نمای کلی از برنامه Songbird شما ارائه می‌دهد:

• آمار: کل کاربران، چت‌ها، پیام‌ها و فایل‌های آپلودشده
• اطلاعات سیستم: زمان فعالیت و محیط
• فضای ذخیره‌سازی: اندازه دیتابیس و دایرکتوری آپلود

تب کاربران

همه کاربران در برنامه Songbird خود را مدیریت کنید:

قابلیت‌ها

• مشاهده همه کاربران: لیست صفحه بندی شده با اندازه صفحه قابل تنظیم
• ایجاد کاربران: ایجاد حساب های جدید با نام کاربری، نام مستعار، رمز عبور
• ویرایش کاربران:
  • به‌روزرسانی نام کاربری، نام مستعار، آواتار
  • بازنشانی رمز عبور به‌صورت درون‌خطی
  • تغییر نقش کاربر (admin/user)
  • مسدود/رفع مسدودیت کاربران
• حذف کاربران: حذف دائمی حساب های کاربری
• جستجو و فیلتر: جستجو و فیلتر کردن روی کل مجموعه داده کاربران
• مرتب سازی: مرتب سازی بر اساس نام کاربری، نام مستعار، تاریخ ایجاد یا آخرین بازدید

تب چت‌ها

مدیریت پیام‌های مستقیم، گروه‌ها و کانال‌ها:

قابلیت‌ها

• مشاهده همه چت ها: لیست صفحه بندی شده همراه با نوع، تعداد اعضا، تعداد پیام ها و تاریخ ایجاد
• ایجاد چت ها: ایجاد گروه یا کانال جدید
• ویرایش چت ها: به روزرسانی متادیتا و مالکیت چت
• حذف چت ها: حذف دائمی چت ها و همه پیام های مرتبط
• جستجو و فیلتر: جستجو و فیلتر کردن روی کل گروه ها و کانال ها
• مرتب سازی: مرتب سازی بر اساس نام، نوع، حریم خصوصی، تاریخ ایجاد، تعداد اعضا یا تعداد پیام ها
• مدیریت اعضا: مشاهده و تغییر عضویت چت
• افزودن خودکار کاربران جدید: عضویت خودکار حساب های کاربری تازه ثبت نام شده در چت های عمومی

تب سرویس‌ها

کارت‌های سلامت برای سرویس‌های بک‌اند (ورکر مدیا، اتصال Telegram، درایور فضای ذخیره سازی):

• Media worker: وضعیت دسترسی به ورکر و وضعیت صف.
• Telegram connection: وضعیت اتصال اکانت Telegram برای کانال های ریموت همراه با قابلیت برقرار کردن اتصال.
• Storage: وضعیت درایور فعال ذخیره سازی.

تب تنظیمات

پیکربندی تنظیمات زمان اجرا از طریق رابط کاربری (جایگزین اکثر متغیرهای .env):

دسته‌ها

عمومی

• لاگ اشکال‌زدایی
• ثبت‌نام (سرور عمومی)

آپلود فایل

• قابلیت آپلود فایل فعال شده
• حداکثر اندازه فایل در هر آپلود
• حداکثر اندازه کل در هر پیام
• حداکثر فایل در هر پیام
• ترنسکد ویدئو فعال شده

نگهداری پیام

• دوره نگهداری فایل (روز)
• دوره نگهداری پیام متنی (روز)

محدودیت‌ها

• حداکثر طول پیام (کاراکتر)
• حداکثر طول نام کاربری
• حداکثر طول نام مستعار

رفتار کلاینت

• محدودیت‌های دریافت پیام
• اندازه صفحه پیام
• TTL کش
• بازه refresh لیست چت‌ها
• بازه health check اتصال
• تاخیر reconnect برای SSE
• حداکثر نتایج جستجو
• timeout پیام متنی pending
• timeout پیام فایلی pending
• بازه retry برای پیام‌های pending
• بازه بررسی وضعیت پیام‌های pending

ذخیره سازی (Object Storage و Worker)

• انقضای Presigned URL بر حسب ثانیه — نیازمند restart
• پیکربندی خودکار CORS برای bucket — نیازمند restart
• نشانی Worker خارجی برای مدیا (قابل خالی بودن، live)
• timeout fallback برای Worker بر حسب ms

Realtime (نیازمند restart)

• بازه heartbeat برای WebSocket بر حسب ms
• timeout برای heartbeat در WebSocket بر حسب ms

کانال ریموت

• قابلیت کانال ریموت فعال شده
• اجازه تغییر در رابط کاربری برای مالکان کانال
• اجازه گزینه استریم رسانه
• حالت tick
• پیکربندی polling و صف

پراکسی‌ها

• نشانی پراکسی برای تحویل push (قابل خالی بودن) — نیازمند restart
• نشانی Proxy برای Object Storage (قابل خالی بودن) — نیازمند restart
• نشانی پراکسی Telegram (قابل خالی بودن) — نیازمند restart
• نشانی پراکسی Songbird برای ارتباط سرور به سرور (قابل خالی بودن، live)

Secrets (فقط مالک)

• secretهای سیستمی فقط‌خواندنی: secret مربوط به tick کانال ریموت، secret مربوط به webhook ورکر، توکن API ادمین. فقط برای مالک سرور قابل مشاهده است، نه ادمین‌ها.

لغو توسط متغیرهای محیطی

متغیرهای محیطی در .env بر تنظیمات دیتابیس اولویت دارند. فیلدهای قفل‌شده نشان‌دهنده لغو فعال توسط env هستند.

تب لاگ‌ها

مشاهده لاگ‌های ممیزی و لاگ‌های سیستم:

لاگ‌های ممیزی

لاگ‌های ذخیره‌شده در دیتابیس از اقدامات مدیریتی:

• عملیات CRUD کاربر
• عملیات CRUD چت
• تغییرات تنظیمات
• اقدامات سیستم

هر ورودی شامل:

• برچسب زمانی
• Actor (چه کسی اقدام را انجام داده)
• نوع اقدام و توضیحات
• موجودیت‌های تحت‌تأثیر

لاگ‌های سیستم

لاگ‌های جمع‌آوری‌شده از چند منبع:

• ژورنال Systemd (اگر از طریق systemd اجرا شود)
• فایل‌های لاگ مستقیم

تب اقدامات

انجام وظایف مدیریت سیستم:

عملیات دیتابیس

پشتیبان‌گیری

• دانلود یک پشتیبان زمان‌دار و سازگار با موتور پایگاه داده
• SQLite یک فایل .db دانلود می‌کند؛ PostgreSQL یک آرشیو بومی .dump ساخته‌شده با pg_dump را دانلود می‌کند

بازیابی

• پشتیبان SQLite را می‌توان هنگام اجرای سرویس آپلود و بازیابی کرد
• بازیابی PostgreSQL عمداً فقط به‌صورت آفلاین است: Songbird را متوقف کنید، سپس npm run db:restore -- -y --file <backup.dump> را اجرا کنید

Vacuum

• SQLite فایل پایگاه داده را با VACUUM فشرده می‌کند
• PostgreSQL دستور بومی VACUUM ANALYZE را اجرا می‌کند
• فضای استفاده‌نشده را بازپس می‌گیرد و برای پایگاه‌های داده بزرگ به‌صورت دوره‌ای توصیه می‌شود

کنترل سیستم

بررسی نسخه

• بررسی نسخه نصب‌شده فعلی
• مقایسه با آخرین نسخه GitHub
• بررسی در دسترس بودن به‌روزرسانی

ریستارت سرویس

• ریستارت سرور Songbird
• اعمال تغییرات در انتظار
• اتصال مجدد همه کلاینت‌ها

توقف سرویس

• توقف نرم سرور Songbird
• نیاز به شروع دستی از طریق systemd/Docker

نیازمندی‌های مجوز

کنترل سرویس (ریستارت/توقف) بسته به نوع استقرار به راه‌اندازی مناسب نیاز دارد:

• Docker: کانتینر songbird باید سوکت Docker را mount کرده باشد (/var/run/docker.sock). این در docker-compose.yaml پیش‌فرض گنجانده شده است. متغیر محیطی SONGBIRD_CONTAINER_NAME به اپلیکیشن می‌گوید کدام کانتینر را هدف قرار دهد (پیش‌فرض: songbird). به نصب از طریق Docker مراجعه کنید.
• Systemd: کاربر سرویس باید مجوزهای sudo برای systemctl داشته باشد. به عیب‌یابی مراجعه کنید.

منطقه خطرناک

پاک‌کردن همه پیام‌ها

• حذف همه پیام‌ها از همه چت‌ها
• ساختار چت و عضویت حفظ می‌شود
• حساب‌های کاربری حفظ می‌شوند
• عملیات غیرقابل‌بازگشت

بازنشانی دیتابیس

• کاربران، چت‌ها، پیام‌ها، نشست‌ها و فایل‌های پیام ذخیره‌شده را پاک می‌کند، اما schema و تنظیمات زمان اجرا را نگه می‌دارد
• عملیات غیرقابل‌بازگشت

اقدامات غیرقابل‌بازگشت

اقدامات منطقه خطرناک قابل بازگشت نیستند. همیشه قبل از ادامه یک پشتیبان ایجاد کنید.

غیرفعال سازی پنل مدیریت

برای غیرفعال سازی کامل پنل مدیریت:

# در فایل .env
ADMIN_PANEL=false

هنگام غیرفعال بودن:

• دکمه Admin از رابط کاربری مخفی میشود
• نقاط پایانی API مدیریت کد 403 بازمیگردانند
• حساب های موجود owner و admin باقی میمانند اما نمیتوانند به پنل دسترسی داشته باشند

نکات امنیتی

• API مدیریت از یک توکن احراز هویت جداگانه استفاده می کند (ADMIN_API_TOKEN)
• در اولین اجرا به صورت خودکار تولید و در .env ذخیره میشود (یا از طریق متغیرهای محیطی در سرویس های PaaS مانند Render تنظیم میشود)
• نقطه پایانی ارتقای مدیریت اضطراری (/api/admin/claim) توکن ها را با استفاده از مقایسه های ایمن زمانی (timing-safe) بررسی کرده و امنیت HTTPS/localhost را الزامی میکند
• نقاط پایانی مدیریت به طور پیشفرض محدود به localhost یا کاربران مدیریت احراز هویت شده هستند
• همه اقدامات مدیریتی و ارتقاهای اضطراری برای ردیابی ممیزی ثبت میشوند
• محدودیت نرخ اعمال میشود (1000 req/15min از نسخه v0.11.1)

جایگزین CLI

اکثر عملیات مدیریتی هنوز می‌توانند از طریق CLI انجام شوند:

cd /opt/songbird/server

# مدیریت کاربر
npm run db:user:create
npm run db:user:edit
npm run db:user:delete
npm run db:user:ban

# مدیریت چت
npm run db:chat:create
npm run db:chat:edit
npm run db:chat:delete

# عملیات دیتابیس
npm run db:backup
npm run db:restore
npm run db:vacuum
npm run db:inspect

برای مرجع کامل CLI، دستورات دیتابیس را ببینید.