# حافظهٔ پروژه: یکپارچه‌سازی Asterisk در Docker و Native تاریخ ثبت: ۳ اکتبر ۲۰۲۶ ## تنظیمات اصلی ```properties 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 ```text ${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` تبدیل نمی‌شوند: ```text /voices-box/sounds /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=` ## 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 /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`: ```properties asterisk.docker-mode=true asterisk.auto-start-docker=true ``` برای بازگشت به نصب محلی، هر دو مقدار را `false` کنید. برای اسکریپت حذف اعضای پویا، متغیرهای `ASTERISK_DOCKER_MODE=true` و `ASTERISK_CONTAINER_NAME` را در حالت Docker تنظیم کنید؛ در حالت محلی اسکریپت مستقیماً از `/usr/sbin/asterisk` استفاده می‌کند.