Files
cti/p-line/docs/markdown/ASTERISK-DOCKER-NAS-MEMORY.md
2026-10-14 23:05:02 +03:30

10 KiB
Raw Blame History

حافظهٔ پروژه: یکپارچه‌سازی Asterisk در Docker و Native

تاریخ ثبت: ۳ اکتبر ۲۰۲۶

تنظیمات اصلی

asterisk.docker-mode=false
asterisk.container-name=asterisk
asterisk.container-puid=1000
asterisk.container-pgid=1000
asterisk.base-path=/opt/cti
asterisk.auto-start-docker=false
  • asterisk.docker-mode=false: رفتار native و مسیرهای استاندارد فعلی حفظ می‌شود.
  • asterisk.docker-mode=true: مسیر فایل‌های Asterisk از ${asterisk.base-path}/base/... روی host استفاده می‌شود.
  • asterisk.auto-start-docker=true: هنگام startup، در صورت نبودن Compose، فایل ساخته و سرویس Asterisk اجرا می‌شود. این گزینه فقط در حالت Docker کاربرد دارد.

حالت پیش‌فرض در application.properties محلی است تا نصب‌های قبلی پس از به‌روزرسانی به Docker وابسته نشوند. برای استفاده از کانتینر، دو گزینهٔ asterisk.docker-mode و asterisk.auto-start-docker را هم‌زمان true کنید. برای ساخت Compose به Docker Engine و Docker Compose در میزبان، دسترسی کاربر اجرای برنامه به Docker و فضای ذخیره‌سازی قابل‌نوشتن زیر asterisk.base-path نیاز است.

شناسه‌های asterisk.container-puid و asterisk.container-pgid برای هماهنگی مالکیت فایل‌های mountشده با کاربر اجرای برنامه هستند. نصب‌کننده آن‌ها را از حسابی که پروژه را اجرا می‌کند می‌گیرد و به کانتینر Asterisk می‌دهد.

Compose تولیدی از قالب 3.7 استفاده می‌کند تا روی Debian 11 و نسخهٔ قدیمی‌تر docker-compose آن هم قابل‌خواندن باشد.

Startup و Docker Compose

کلاس AsteriskDockerStartup:

  • مسیرهای mount را ایجاد می‌کند.
  • در صورت نبودن /opt/cti/docker-compose.yml، Compose را می‌سازد.
  • docker compose و docker-compose را پشتیبانی می‌کند.
  • اجرای up -d asterisk را در صورت آماده نبودن Docker تا چند بار retry می‌کند.
  • اتصال AMI پس از بالا آمدن Asterisk دوباره تلاش می‌شود.
  • Compose تولیدشده با marker زیر قابل تشخیص است: # Generated and managed by P-Line
  • Compose دستی overwrite نمی‌شود.
  • Compose تولیدشده از network_mode: host استفاده می‌کند؛ پورت‌های SIP/RTP و AMI مستقیماً از شبکهٔ میزبان در دسترس‌اند و نگاشت پورت جداگانه تعریف نشده است.
  • فایل‌های پیکربندی موجود روی میزبان در base/etc/asterisk حفظ می‌شوند. دایرکتوری‌های خالی به‌تنهایی جایگزین پیکربندی پایهٔ Asterisk نیستند؛ نصب اولیه باید فایل‌های لازم را در این مسیر داشته باشد.

Mountهای Asterisk

${base}/base/etc/asterisk       -> /etc/asterisk
${base}/base/var/lib/asterisk   -> /var/lib/asterisk
${base}/base/var/log/asterisk   -> /var/log/asterisk
${base}/base/var/spool/asterisk -> /var/spool/asterisk
${base}/base/fax                -> /var/spool/asterisk/fax
${base}/base/sounds             -> /var/lib/asterisk/sounds

soundهای استاندارد Asterisk با soundهای آپلودی برنامه یکی نیستند. مسیرهای زیر mount مستقل دارند و به /var/lib/asterisk/sounds تبدیل نمی‌شوند:

<application-dir>/voices-box/sounds
<application-dir>/voices-box/music-on-holds

فکس

  • مسیر فایل روی host با getFaxDir() تعیین می‌شود.
  • مسیر قابل مشاهده برای Asterisk با getFaxRuntimeDir() تعیین می‌شود.
  • فکس local در Docker از ${base}/base/fax به /var/spool/asterisk/fax متصل است.
  • SendFax و ReceiveFax برای عملیات Java از مسیر host و برای SendFAX/ReceiveFAX از مسیر runtime استفاده می‌کنند.

ضبط تماس

  • مسیر host/گزارش‌ها: getCallRecordPath().
  • مسیر قابل استفاده داخل Asterisk: getCallRecordRuntimePath().
  • مسیر local در Docker:
    • host: ${base}/base/var/spool/asterisk/monitor
    • container: /var/spool/asterisk/monitor
  • MixMonitor، Queue dialplan و RingGroup dialplan از مسیر runtime استفاده می‌کنند.
  • گزارش‌ها، دانلود فایل و پاک‌سازی از مسیر host استفاده می‌کنند.

NAS

مدل TblNasStorage امکان انتخاب مستقل برای این سه مورد را دارد:

  • callRecord
  • fax
  • backup

اتصال NAS در CheckInStartTasks و تغییرات پنل در StorageController مسیرهای فعال را بازسازی می‌کنند.

  • برای فکس و ضبط، فقط ریشهٔ NAS انتخاب‌شده (/mnt/nas-X) به‌صورت bind mount اختصاصی وارد Compose می‌شود.
  • کل /mnt هرگز mount نمی‌شود.
  • اگر Compose دستی و unmanaged باشد، برنامه آن را overwrite نمی‌کند و برای mountهای NAS هشدار log می‌کند.
  • backup به کانتینر Asterisk نیاز ندارد و مستقیماً روی host/NAS اجرا می‌شود.

Backup

  • getBackupPath() مسیر local یا NAS را تعیین می‌کند.
  • backup دستی و زمان‌بندی‌شده مقصد انتخاب‌شده را استفاده می‌کنند.
  • backup_restore.sh مقصد اختیاری backup را می‌پذیرد.
  • تاریخچه، حذف و دانلود backup مسیر NAS را نیز پشتیبانی می‌کنند.
  • endpoint دانلود اختصاصی: /download/backup?file=<name>

Timezone

  • Compose تولیدی: TZ=Asia/Tehran.
  • Native: timezone سیستم با timedatectl مدیریت می‌شود.
  • JVM/DB از timezone سیستم برنامه استفاده می‌کنند؛ مقدار اولیهٔ properties همچنان UTC است و در startup توسط PlineApplication با timezone سیستم override می‌شود.

اجرای متمرکز فرمان‌های Asterisk

  • همهٔ فرمان‌های متنی CLI باید از PlineTools.executeAsteriskCliCommand() (یا wrapperهای آن مانند execCoreCommandStringResult()) عبور کنند؛ مسیر fallback داخلی native از /usr/sbin/asterisk -x و Docker از docker exec <container> /usr/sbin/asterisk -x استفاده می‌کند.
  • مسیر اصلی ابتدا از pool محدود AMI با CommandAction استفاده می‌کند. فقط اگر AMI پیش از ارسال فرمان در دسترس نباشد، اجرای محلی CLI مجاز است. اگر ارسال AMI شروع شده و پاسخ نامشخص/timeout باشد، فرمان دوباره از CLI اجرا نمی‌شود تا اجرای تکراری رخ ندهد.
  • pool فرمان AMI چهار اتصال دارد؛ اجرای fallback محلی حداکثر دو پردازهٔ هم‌زمان می‌پذیرد و درخواست اضافی را بدون صف‌کردن رد می‌کند.
  • API محلی POST /local-asterisk/command در LocalAsteriskCommandController فقط اتصال مستقیم loopback و token برابر با pline.local-asterisk-api-token را می‌پذیرد. هدرهای forwarding باعث رد درخواست می‌شوند؛ برنامه‌های محلی باید مستقیم به پورت 8080 وصل شوند.
  • افزودن، حذف و pause/unpause اعضای صف در QueueLiveInfoController و افزودن اعضای داینامیک/پاک‌سازی آن‌ها در QueueGenerator از همان executor مرکزی CLI استفاده می‌کنند؛ برای این عملیات از QueueAddAction، QueueRemoveAction و QueuePauseAction مستقیم استفاده نشود.
  • رفتار صف باید حفظ شود: اعضای داینامیک زمان ساخت با حالت unpaused اضافه می‌شوند؛ endpoint ورود (/online/.../true) عضو را در حالت paused ثبت می‌کند؛ حذف و pause/unpause باید همان queue و Local interface قبلی را هدف بگیرند.
  • ManagerGenerator حساب اصلی [pline] را با allowmultiplelogin = yes می‌سازد تا اتصال رویدادها و pool فرمان هم‌زمان کار کنند؛ تنظیم AMI کاربران دیگر برنامه مستقل باقی می‌ماند.

ارتباط‌های دیگر Asterisk

  • AMI رویدادها، AGI و Live API همچنان ارتباط‌های مخصوص خود را دارند و در Docker برای آن‌ها docker exec لازم نیست.
  • API محلی اختیار اجرای CLI حساب pline را دارد؛ token را فقط در اختیار برنامه‌های trusted محلی قرار دهید.

اعتبارسنجی انجام‌شده

  • Maven compile با -DskipTests موفق است.
  • git diff --check بدون خطا است.
  • Compose تولیدی با docker compose config معتبر است.
  • برای انتقال عملیات صف به executor مرکزی، compile و آزمون‌های منتخب Maven اجرا شده‌اند؛ آزمون روی Asterisk زنده انجام نشده است.

نکتهٔ عملی

برای فعال‌سازی حالت Docker در application.properties:

asterisk.docker-mode=true
asterisk.auto-start-docker=true

برای بازگشت به نصب محلی، هر دو مقدار را false کنید. برای اسکریپت حذف اعضای پویا، متغیرهای ASTERISK_DOCKER_MODE=true و ASTERISK_CONTAINER_NAME را در حالت Docker تنظیم کنید؛ در حالت محلی اسکریپت مستقیماً از /usr/sbin/asterisk استفاده می‌کند.