Files
cti/p-line/docs/markdown/ASTERISK-DOCKER-NAS-MEMORY.md
2026-10-14 23:05:02 +03:30

138 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# حافظهٔ پروژه: یکپارچه‌سازی 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` استفاده می‌کند.