Files
cti/p-line/docs/markdown/ASTERISK-DOCKER-NAS-MEMORY.md
2026-10-20 11:49:12 +03:30

14 KiB
Raw Permalink 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 چهار اتصال دارد؛ اتصال‌های بیکار پس از ۳۰ ثانیه (قابل تنظیم با pline.ami-command-idle-timeout-ms) بسته می‌شوند و هر ۱۰ ثانیه بررسی می‌شوند. اجرای fallback محلی حداکثر دو پردازهٔ هم‌زمان می‌پذیرد و درخواست اضافی را بدون صف‌کردن رد می‌کند.
  • اجرای File_Generator.GenerateFiles() همگام‌سازی شده تا تولید فایل‌ها و reloadهای ناشی از چند درخواست هم‌زمان روی هم نیفتند.
  • 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 کاربران دیگر برنامه مستقل باقی می‌ماند.

عیب‌یابی reload در Asterisk 22

  • در لاگ Asterisk 22.11.0، The previous reload command didn't finish yet همراه با loader.c دیده شد و AMI رویداد Reload با Module: All و Status: 4 برگرداند؛ در مستندات AMI نسخهٔ 22، status 4 یعنی reload از قبل در حال اجرا است. این پیام نشانهٔ اتصال بیکار AMI نیست.
  • reloadConfigurations() باید فقط یک‌بار module reload بفرستد؛ این فرمان خودش Manager را هم reload می‌کند. برای reload مهلت طولانی‌تر از فرمان‌های CLI معمولی در نظر گرفته شود و timeout یا پاسخ «reload already in progress» باید به Apply به‌عنوان خطا برگردد، نه موفقیت.
  • مسیر Apply باید نتیجهٔ reload را بررسی کند؛ اگر Asterisk پاسخ نداد یا گفت reload دیگری در حال اجرا است، hasError فعال بماند و logها/تأیید تغییرات فقط پس از Apply موفق ثبت شوند. مقدار ناموفق باید به‌صورت نتیجهٔ false برگردد، نه exception؛ در startup، timeout reload نباید بالا آمدن برنامه را متوقف کند.
  • Backtrace زندهٔ Asterisk 22.11.0 در reload گیرکرده، thread مربوط به res_pjsip_config_wizard.so را داخل ast_sorcery_reload و __ast_taskpool_push_wait نشان داد؛ چند thread دریافت PJSIP نیز در ast_sip_get_transport_states منتظر mutex بودند. این الگو با deadlock شناخته‌شدهٔ reload در PJSIP Config Wizard هم‌خوان است؛ بازکردن اتصال idle AMI آن را رفع نمی‌کند. اجرای GDB از میزبان Docker به‌خاطر PID namespace ممکن است هشدار بدهد و نام بعضی frameها را نشان ندهد، ولی مسیرهای نماددار برای تشخیص کافی بودند.
  • SipFileGenerator در CTI objectهای معمول transport, aor, auth, endpoint, registration, و identify می‌نویسد و type = wizard تولید نمی‌کند. برای دورزدن deadlock، PlineSettingsGenerator باید res_pjsip_config_wizard.so را در modules.conf با noload خارج کند. این workaround فقط پس از بازتولید modules.conf و restart کانتینر Asterisk اعمال می‌شود؛ بعد از بالا آمدن، module show like res_pjsip_config_wizard باید نشان دهد ماژول load نیست.
  • در Asterisk 22 گزینهٔ automon در [featuremap] پشتیبانی نمی‌شود؛ پیش‌فرض p-line/features.json برای آن نسخه به automixmon تغییر کرده است. پس از انتشار این فایل، همگام‌سازی FeatureCodeGenerator مقدار پایه را در دیتابیس و features.conf به‌روز می‌کند. خطای features.conf باید رفع شود، اما از روی لاگ موجود نمی‌توان آن را علت گیرکردن کل reload دانست.
  • اگر /var/log/asterisk/full وجود ندارد، logger show channels را بررسی کنید. در نمونهٔ بررسی‌شده فقط messages.log و Console فعال بودند؛ کانال موقت با logger add channel /tmp/reload-debug.log notice,warning,error,debug,verbose لاگ تشخیصی را فراهم کرد.

ارتباط‌های دیگر 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 استفاده می‌کند.