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