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