14 KiB
حافظهٔ پروژه: یکپارچهسازی 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
- host:
MixMonitor، Queue dialplan و RingGroup dialplan از مسیر runtime استفاده میکنند.- گزارشها، دانلود فایل و پاکسازی از مسیر host استفاده میکنند.
NAS
مدل TblNasStorage امکان انتخاب مستقل برای این سه مورد را دارد:
callRecordfaxbackup
اتصال 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 استفاده میکند.