Посібник адміністратора PearlPBX2

Версія: 2.7.2

Зміст

1. Вступ
2. Архітектура системи
3. Встановлення (огляд)
4. Конфігурація через змінні середовища
5. Користувачі та ролі
6. SIP-транспорти
7. SIP-користувачі
8. SIP-піри (транки)
9. Групи транків
10. Діалплан (Dialplan)
11. Маршрутизація дзвінків
12. Черги
13. Музика на утриманні (MOH)
14. Звукові файли
15. Apply Changes
16. Служби (Services)
17. Веб-хуки (CRM)
18. REST API
19. Провізіонінг телефонів
20. Обслуговування

1. Вступ

PearlPBX2 — це веб-інтерфейс для керування Asterisk PBX, побудований на Django. Система дозволяє керувати SIP-абонентами, транками, діалпланом, маршрутизацією, чергами та іншими об’єктами Asterisk через веб-інтерфейс, автоматично генеруючи конфігураційні файли Asterisk з бази даних.

Ключові можливості

• Управління PJSIP транспортами, абонентами та транками
• Редактор діалплану з підтримкою синтаксису AEL та валідацією
• Префіксна маршрутизація дзвінків
• Черги з підтримкою ескалації, анонсів, глобальних налаштувань
• Дашборд оператора в реальному часі (WebSocket)
• CDR, записи розмов, журнали черг
• Аналітика з графіками (Chart.js)
• Автоматичні зворотні дзвінки (callback)
• Провізіонінг телефонів (TFTP)
• REST API для зовнішньої інтеграції
• Apply Changes — генерація конфігів та перезавантаження Asterisk одним кліком

Хто є адміністратором

Адміністратор — це користувач із правами superuser (is_superuser=True). Тільки superuser може:

• застосовувати зміни конфігурації до Asterisk (/admin/apply);
• керувати всіма об’єктами PBX через адмін-панель;
• створювати та редагувати інших користувачів.

Користувачі з правами staff (is_staff=True) можуть переглядати адмін-панель, але без доступу до Apply Changes.

2. Архітектура системи

Загальна схема

Browser ──WebSocket──► Django Channels ◄── Redis ◄── Dashboard Listener ◄── Asterisk AMI
Browser ──HTTP──────► Django (ASGI) ◄──── PostgreSQL
                            │
                            └──► /etc/asterisk/*.conf  (генерація конфігів)

Asterisk FastAGI ◄──────────► FastAGI Service (port 4573)
Callback daemon ─────────────► Asterisk AMI (вихідні дзвінки)

Компоненти

Потік даних

1. Конфігурація: Admin UI → Django Models → core/conf.py → файли /etc/asterisk/*.conf → перезавантаження Asterisk
2. Дашборд: Події Asterisk AMI → Dashboard Listener → Redis Pub/Sub → Django Channels → WebSocket → Браузер
3. Callback: Запит у БД → Callback Daemon (SELECT FOR UPDATE) → AMI Originate → вихідний дзвінок
4. FastAGI: Asterisk діалплан → AGI(agi://localhost:4573/handler) → FastAGI сервер → змінні каналу

Компоненти Django

3. Встановлення (огляд)

Вимоги до системи

• Python 3.10+
• Django 5.2
• PostgreSQL 14+
• Redis 7+
• Asterisk 22+ (з модулями res_pjsip, res_agi, cdr_pgsql)

Швидкий старт (розробка)

# Створення віртуального середовища
python3 -m venv .python-venv
source .python-venv/bin/activate

# Встановлення залежностей
pip install -r requirements.txt

# Налаштування змінних середовища
cp env.sample .env
# Відредагуйте .env — DB, AMI, DEVMODE тощо

# Ініціалізація бази даних
python manage.py migrate
python manage.py createsuperuser

# Запуск сервера розробки
python manage.py runserver

Продуктивне середовище

# Через uvicorn (ASGI + WebSocket)
uvicorn pbx.asgi:application --host 0.0.0.0 --port 8000 --workers 3

Важливо: Django має працювати від користувача asterisk для доступу до /etc/asterisk.

Докладна інструкція

• Docker-розгортання: docker-compose.yml (django, asterisk, postgres, redis, fastagi, dashboard-listener, callback)
• Ansible-розгортання (рекомендовано для bare-metal production): ansible/install.yml (9 ролей: system, postgres, redis, asterisk, pearlpbx2, services, nginx, tftp, firewall)

Режими роботи (DEVMODE)

4. Конфігурація через змінні середовища

Всі налаштування задаються через змінні середовища. Приклад: env.sample.

Обов’язкові змінні

Опціональні змінні

5. Користувачі та ролі

Групи користувачів

Система використовує стандартну модель користувачів Django.

Група “Report Viewer”

Користувачі в цій групі мають доступ до:

• Dashboard (/dashboard/)
• Parking (моніторинг ULINE, /dashboard/ulines/)
• Reports (/reports/)
• Lists (/lists/)

Створення групи:

1. Адмін-панель → Authentication and Authorization → Groups → Add Group.
2. Назва: Report Viewer.
3. Призначте необхідні права (або жодних — доступ контролюється через код у HEADER_MENU_PAGES).

Рівні доступу в Django

Створення користувача

1. Перейдіть до /admin/auth/user/add/.
2. Заповніть Username, Password.
3. Натисніть Save and continue editing.
4. На вкладці Permissions:
   • Superuser status — поставте галочку для повного доступу.
   • Staff status — поставте для доступу до адмін-панелі.
5. На вкладці Groups додайте користувача до групи “Report Viewer” (якщо потрібно).

Навігаційне меню (HEADER_MENU_PAGES)

У settings.py визначено пункти меню з прив’язкою до ролей:

6. SIP-транспорти

SIP-транспорти визначають, як Asterisk слухає та передає SIP-трафік. Відповідає моделі SIPTransport.

Створення транспорту

1. Адмін-панель → PBX Setup → SIP Transports → Add SIP Transport.
2. Поля:

TLS-налаштування (тільки для протоколу TLS)

Рекомендації

• Для звичайного використання створіть UDP-транспорт на порту 5060.
• Для підтримки WebRTC створіть WSS-транспорт.
• При роботі через NAT заповніть External Media/Signaling Address.

7. SIP-користувачі

SIP-користувачі — це внутрішні абоненти телефонної мережі. Відповідає моделі SIPUser.

Створення абонента

1. Адмін-панель → PBX Setup → SIP Users → Add SIP User.
2. Поля:

Автоматична генерація extension

Якщо поле Extension залишити порожнім, система автоматично згенерує наступний вільний номер у форматі 2XX. Діапазон пошуку визначається налаштуваннями маршрутизації (PEARLPBX_DEFAULT_ROUTING_PREFIX).

Поля Custom Settings

Для налаштування параметрів PJSIP, яких немає в основній формі, використовуйте поля:

• Custom Endpoint Settings — додаткові параметри секції [endpoint].
• Custom Auth Settings — додаткові параметри секції [auth].
• Custom AOR Settings — додаткові параметри секції [aor].

Кожне поле приймає текст у форматі parameter = value, по одному на рядок. Ці значення дописуються у відповідні секції згенерованого pjsip.conf.

8. SIP-піри (транки)

SIP-піри — це зовнішні з’єднання з телефонними операторами або іншими АТС. Відповідає моделі SIPPeer.

Створення транку

1. Адмін-панель → PBX Setup → SIP Peers → Add SIP Peer.
2. Поля:

Generic

Authentication

Connection

Формування AOR contact: якщо Contact URI не заповнено, система підставляє Registration URI як контакт AOR (з попередженням у логах — це може бути некоректно, якщо реєстратор і медіа-хост відрізняються). Якщо не заповнено жодного з полів, AOR лишається без статичного контакту.

Коли Registration There увімкнено, AOR транку одразу отримує “bootstrap”-контакт (max_contacts=1, remove_existing=yes), навіть до першої вдалої реєстрації — інакше вихідні дзвінки не мають куди йти в проміжку до REGISTER. Після успішного REGISTER цей контакт замінюється на той, що реально прислав оператор.

Registration

Advanced (collapsed)

Групи транків

Див. розділ Групи транків.

9. Групи транків

Дозволяють об’єднати кілька транків у групу для failover — при недоступності першого транку дзвінок автоматично направляється на наступний. Відповідає моделі TrunkGroup.

Створення групи

1. Адмін-панель → PBX Setup → Trunk Groups → Add Trunk Group.
2. Поля:
   • Name — назва групи.
   • SIP Peers — виберіть транки зі списку. Порядок має значення: перший транк є пріоритетним.

Обробка групи здійснюється через FastAGI-сервер (handler dial-trunk-group).

10. Діалплан (Dialplan)

Система використовує синтаксис AEL (Asterisk Extension Language) для діалплану.

Контексти (DialplanContext)

Контекст — це логічна група розширень (extensions) у діалплані Asterisk.

Створення контексту:

1. Адмін-панель → PBX Setup → Dialplan Contexts → Add Dialplan Context.
2. Поля:
   • Name — унікальне ім’я контексту. Назви контекстів та таблиць маршрутизації є спільним простором імен.
   • Description — опис.

Примітка: Контексти та таблиці маршрутизації не можуть мати однакових імен.

Розширення (DialplanExtension)

Розширення — це окремі номери або шаблони в контексті з визначеним діалпланом на мові AEL.

Створення розширення:

1. З контексту (inline) або напряму: PBX Setup → Dialplan Extensions → Add.
2. Поля:

Валідація: Поле ext проходить валідацію через validate_asterisk_extension_prefix. Діалплан проходить валідацію через AsteriskDialplanValidator для перевірки синтаксису AEL.

Приклад діалплану:

{
    Answer();
    Wait(1);
    Playback(hello);
    Hangup();
}

Макроси (DialplanMacro)

Макроси AEL — це багаторазово використовувані блоки діалплану.

Створення макросу:

1. Адмін-панель → PBX Setup → Dialplan Macros → Add.
2. Поля: Name, Description, Macro (тіло макросу на AEL).

Глобальні змінні (DialplanGlobalVariable)

Дозволяють визначити іменовані записи, що потрапляють у блок globals { } на початку згенерованого extensions.ael.

1. Адмін-панель → PBX Setup → Dialplan Global Variables → Add.
2. Поля: Name, Value.
3. Ім’я перевіряється на коректний синтаксис ідентифікатора; значення не може містити ; або переноси рядків.

Примітка щодо імен

Оскільки DialplanContext і RoutingTable мають спільний простір імен, неможливо створити контекст і таблицю маршрутизації з однаковою назвою. Адмін-форма контексту перевіряє унікальність через DialplanContextAdminForm.

11. Маршрутизація дзвінків

Маршрутизація дзвінків визначає, як обробляються вихідні дзвінки на основі префікса номера.

Таблиці маршрутизації (RoutingTable)

Таблиця маршрутизації групує записи маршрутизації. Назви таблиць поділяють простір імен із Dialplan-контекстами.

Створення:

1. PBX Setup → Routing Tables → Add Routing Table.
2. Name — назва таблиці (унікальна, не може співпадати з контекстом).

Записи маршрутизації (RoutingRecord)

Кожен запис визначає, в який контекст направити дзвінок залежно від префікса номера.

Сортування: Записи обробляються в порядку, визначеному полем name. Система також підтримує AEL-синтаксис для префіксів (знак _ на початку означає шаблон).

Типові записи:

12. Черги

Створення черги

1. Адмін-панель → PBX Setup → Queues → Add Queue.
2. Основні поля:

Додавання членів черги

Масове додавання через форму:

1. У формі черги знайдіть секцію Add Members.
2. Виберіть SIP-користувачів зі списку Add SIP Users.
3. При збереженні для кожного вибраного користувача буде створено запис QueueMember з інтерфейсом PJSIP/{username}.
4. Існуючі члени черги не змінюються.

Індивідуальне додавання:

• Використовуйте inline-форму Queue members на сторінці черги.
• Або створіть запис напряму: PBX Setup → Queue Members → Add.

Поля члена черги:

Правила черг (Queue Rules)

Правила визначають зміну пріоритетів (penalty) агентів залежно від часу очікування дзвінка в черзі.

Створення правила:

1. Адмін-панель → PBX Setup → Queue Rules → Add Queue Rule.
2. Додайте кроки ескалації (Penalty Changes):
   • Seconds — через скільки секунд застосувати правило.
   • Max Penalty — максимальний штраф.
   • Min Penalty — мінімальний штраф.
   • Raise Penalty — збільшення штрафу.
   • Order — порядок застосування.

Прив’язка правила до черги:

У формі черги, секція Queue Rules, виберіть правило зі списку Default Rule. Посилання Edit Rule відкриває сторінку редагування правила в новій вкладці.

Анонси черг (Queue Announcements)

Налаштовуються в секції Announcements форми черги:

• Announce — звуковий файл для оголошення.
• Queue Announce — оголошення назви черги.
• Queue Announcement — вибір типу оголошення.
• Announce Frequency — частота оголошень (сек).
• Announce Holdtime — оголошення часу очікування.
• Announce Position — оголошення позиції в черзі.

Додаткові налаштування (секція Advanced)

У згорнутій секції Advanced доступні всі параметри черг Asterisk:

• timeout, retry, maxlen, wrapuptime
• autopause, autopausedelay
• context, service_level, weight, autofill, ringinuse
• joinempty, leavewhenempty
• monitor_format
• timeoutpriority, timeoutrestart
• periodic_announce, random_periodic_announce
• setqueuevar
• та інші.

Глобальні налаштування черг (CallQueueGlobalSettings)

Доступно через адмін-панель: PBX Setup → Call Queue Global Settings. Тут можна задати глобальні параметри, які застосовуються до всіх черг, зокрема shared_lastcall, setvar, persistent_members, autofill, monitor_type, negative_penalty_invalid, force_longest_waiting_caller.

13. Музика на утриманні (MOH)

Класи MOH (MusicOnHold)

1. Адмін-панель → PBX Setup → Music On Hold → Add Music On Hold.
2. Поля:

Плейлисти MOH (MusicOnHoldPlaylistEntry)

Додаються inline у формі класу MOH:

14. Звукові файли

Система дозволяє завантажувати звукові файли для використання в діалплані через модель SoundFile.

1. Адмін-панель → PBX Setup → Sound Files → Add Sound File.
2. Поля:

Файли зберігаються через кастомне сховище SoundsFileSystemStorage, яке копіює файли у відповідну директорію Asterisk.

15. Apply Changes

Apply Changes — це ключовий механізм системи, який генерує конфігураційні файли Asterisk з даних у базі даних, створює бекап та перезавантажує Asterisk.

Доступ

Apply Changes доступний тільки для superuser. Шлях: /admin/apply.

Процес

1. Перегляд змін: На сторінці /admin/apply показано всі конфігураційні файли, які будуть згенеровані, з їхнім вмістом.
2. Застосування: Позначте галочку “Apply Changes” та натисніть кнопку.
3. Бекап: Система створює архів tar.gz поточної конфігурації в ASTERISK_BACKUP_DIR.
4. Генерація файлів: Записує файли в ASTERISK_ROOT_DIR + ASTERISK_CONFIG_DIR.
5. TLS-сертифікати: Якщо є TLS-транспорти, сертифікати записуються в {CONFIG_DIR}/certificate/.
6. Версіонування: Кожен файл зберігається в БД (ConfigurationFile) з версією. Якщо вміст не змінився, версія не збільшується.
7. SystemConfiguration: Створюється знімок поточної конфігурації з посиланнями на всі ConfigurationFile.
8. Перезавантаження Asterisk: Виконується AMI-команда:
   • Soft reload — перезавантаження модулів (module reload).
   • Hard restart — повний перезапуск Asterisk (restart gracefully).

Які файли генеруються

Користувацькі конфігураційні файли (ConfigurationFile)

Модель ConfigurationFile дозволяє додавати довільні файли конфігурації Asterisk:

1. Адмін-панель → PBX Setup → Configuration Files → Add.
2. Поля: Name, Description, Path (шлях відносно ASTERISK_ROOT_DIR), Content.
3. При кожному Apply Changes файли з найновішою версією включаються в набір конфігурацій.

Це дозволяє керувати файлами, які не генеруються автоматично (наприклад, features.conf, cdr.conf, logger.conf).

Перегляд історії

Моделі ConfigurationFile та SystemConfiguration зберігають історію змін. Кожен SystemConfiguration — це знімок стану конфігурації на момент Apply, що дозволяє відстежити, які файли і в яких версіях були застосовані. Знімок також включає посилання на бінарні файли (модель BinaryFile, наприклад TLS-сертифікати), застосовані разом із текстовими конфігами.

16. Служби (Services)

Система включає кілька окремих служб, кожна з яких працює як окремий процес. Всі служби мають власне віртуальне середовище та systemd unit.

Загальна інформація

Всі служби запускаються від користувача asterisk.

Примітка: юніти встановлюються та керуються через Ansible (ansible/roles/services/); шаблони .service-файлів у services/ у корені репозиторію застаріли й не відповідають назвам, що реально розгортаються.

Dashboard Listener

Директорія: services/dashboard/

Служба підключається до Asterisk через AMI та слухає всі події, публікуючи їх у Redis Pub/Sub на каналі asterisk:events.

Дані в Redis:

Запуск:

cd services/dashboard
source .python-venv/bin/activate
python dashboard_listener.py

Перевірка роботи:

systemctl status pearlpbx2-dashboard.service
journalctl -u pearlpbx2-dashboard.service -f

Залежності: redis, asterisk-ami

Сповіщення в Slack про пропущені дзвінки (опціонально): служба може надсилати агреговане повідомлення в Slack, коли абоненти залишають чергу без відповіді. Всі пропущені дзвінки в межах вікна debounce групуються в одне повідомлення на чергу. Налаштовується через змінні в services/dashboard/env:

Callback Daemon

Директорія: services/callback/

Служба моніторить таблицю callback_number у базі даних. Коли з’являється запис зі статусом NEW, служба:

1. Блокує запис через SELECT FOR UPDATE SKIP LOCKED (запобігання race condition при multiprocessing).
2. Викликає AMI Originate для створення вихідного дзвінка.
3. Оновлює статус на PENDING, ANSWERED або BUSY.

Запуск:

cd services/callback
source .python-venv/bin/activate
python callback.py

Параметри:

python callback.py --db_host=localhost --ami_user=admin --ami_pass=secret
python callback.py --process_count=4   # багатопроцесорний режим
python callback.py --dump_config      # перегляд конфігурації

Залежності: psycopg2-binary, asterisk-ami, requests

FastAGI Server

Директорія: services/fastagi/

Сервер FastAGI на базі Twisted + StarPy. Слухає порт 4573 та обробляє AGI-запити від Asterisk.

Обробники (handlers):

ULINE Redis Manager — керує паркувальними слотами (1–199) через атомарний Lua-скрипт у Redis.

Запуск:

cd services/fastagi
source venv/bin/activate
python fastagi.py

Залежності: twisted, starpy, psycopg2-binary, redis

Класичні AGI-скрипти (Slack-сповіщення)

Директорія: services/agi/

На відміну від FastAGI Server (окрема служба на порту 4573), це класичні AGI-скрипти (missed_call.py, unmatched_call.py), які Asterisk запускає напряму з діалплану для точкових Slack-сповіщень про пропущені та невідповідні дзвінки. Спільний функціонал (зокрема notify_slack()) винесено в agi_common.py.

Конфігурація: /etc/PearlPBX/AGI/env.

Приклад використання FastAGI в діалплані

context check_blacklist {
    _X. => {
        AGI(agi://127.0.0.1:4573/blacklist);
        if ("${BLACKLISTED}" = "1") {
            Hangup();
        }
    }
}

17. Веб-хуки (CRM)

Веб-хуки дозволяють автоматично надсилати CRM-системі JSON POST-запити про події дзвінків: два незалежні ланцюги — вхідний (call.incoming → call.answered/call.missed → call.ended, дзвінки ззовні або через транк) і вихідний (call.outgoing → call.outgoing_answered → call.outgoing_ended, дзвінки, ініційовані SIP-користувачем, ніколи транком). Реалізовано в apps/webhooks/ — доставку обробляє Dashboard Listener на основі подій AMI.

Докладний опис форматів payload, перевірки підпису та прикладів обробника — в окремому гайді docs/ua/crm-integration.md (а також спрощена версія для розробників CRM: docs/ua/crm-integrator-guide.md). Цей розділ описує лише налаштування веб-хука в адмін-панелі.

Створення веб-хука

1. Адмін-панель → Webhooks → Add Webhook.
2. Поля:

Примітка: якщо для веб-хука не вибрано жодного контексту, routing table чи черги, форма адміна вимагає вказати принаймні одне з них (інакше незрозуміло, які дзвінки мають запускати доставку). Вхідні події (Send Incoming тощо) додатково вимагають Contexts або Queues; вихідні події (Send Outgoing тощо) — Routing tables.

18. REST API

Система надає REST API для зовнішньої інтеграції. Докладна документація: docs/en/API.md, а також живий Swagger UI на /api/v1/docs/ і OpenAPI-схема на /api/v1/schema/.

Для інтеграції з CRM-системами (веб-хуки про дзвінки, розділ 17 вище) та доступ до записів розмов через API див. окремий гайд: docs/ua/crm-integration.md.

Короткий огляд

API побудовано на Django REST Framework (DefaultRouter + ViewSet-и, apps/api/).

Базовий URL: /api/v1/

Автентифікація: token-based через DRF TokenAuthentication (заголовок Authorization: Token <key>). IP-адресних обмежень більше немає. Токен створюється командою:

python manage.py drf_create_token <username>

Без валідного токена запити повертають 401 Unauthorized.

Ендпоінти:

Коди статусу: 200, 201, 204, 400, 401, 404, 409.

Формат відповіді: JSON.

19. Провізіонінг телефонів

Система підтримує автоматичне налаштування SIP-телефонів через TFTP.

Модель PhoneDevice

Процес провізіонінгу

1. Зареєструйте телефон у системі (додайте PhoneDevice).
2. Прив’яжіть до існуючого SIP-користувача.
3. Конфігураційні файли генеруються в директорію TFTP_DIR.
4. Телефон отримує конфігурацію через TFTP при завантаженні.

20. Обслуговування

Резервне копіювання

Система автоматично створює бекап при кожному Apply Changes:

• Архів tar.gz зберігається в ASTERISK_BACKUP_DIR.
• Формат імені: asterisk-{timestamp}.tar.gz.
• Бекап включає всю поточну конфігурацію Asterisk.

Крім того, Ansible-інсталяція налаштовує два щоденні cron-завдання:

• Бекап PostgreSQL (bin/pg_backup_pearlpbx2.sh) — щодня о 01:30.
• Бекап /etc/asterisk (bin/backup_asterisk.sh) — щодня о 02:30. Архівує /etc/asterisk у tar.gz та зберігає в BACKUP_DIR (типово /var/backups/asterisk-etc) з ретенцією RETENTION_DAYS (типово 14 днів). Конфігурація — /etc/PearlPBX/backup_asterisk/env (шаблон backup_asterisk.env.j2); опційно можна вказати SLACK_WEBHOOK_URL для сповіщення про збій.

Міграція з PearlPBX1

Директорія migrate_from_PearlPBX1/ містить скрипти та інструкції для міграції з першої версії системи.

Оновлення системи

Для оновлення використовуйте update.sh або git pull з наступним застосуванням міграцій:

git pull
source .python-venv/bin/activate
pip install -r requirements.txt
python manage.py migrate
python manage.py collectstatic
systemctl restart PearlPBX2

Логування

Система логує події через стандартний механізм Django logging:

• core логгер — INFO рівень (навмисно знижено з DEBUG, щоб уникнути потрапляння payload’ів подій AMI, які містять caller ID/PII, у journald).
• django логгер — INFO рівень.
• apps логгер — INFO рівень, propagate=False.
• __main__ логгер — INFO рівень.

Логи виводяться в консоль (stdout). Для продакшну рекомендується налаштувати запис у файл або систему централізованого логування.

Моніторинг служб

# Перевірка статусу всіх служб
systemctl status PearlPBX2.service pearlpbx2-dashboard.service pearlpbx2-callback.service pearlpbx2-fastagi.service asterisk.service

# Перегляд логів
journalctl -u PearlPBX2.service -f
journalctl -u pearlpbx2-dashboard.service -f
journalctl -u pearlpbx2-callback.service -f
journalctl -u pearlpbx2-fastagi.service -f

Документ створено для PearlPBX2 v2.7.2. Інтерфейс системи та шляхи можуть відрізнятися залежно від конфігурації.