Asterisk ARI в Docker

Обзор

Эта инструкция разворачивает Asterisk 23.4.1 из официального исходного кода в Docker. Такая сборка содержит chan_websocket, res_websocket_client и параметр transport_data, которые Агентика использует для двусторонней передачи аудио и аутентификации медиапотока. Контейнер работает в host network. Это убирает дополнительный NAT для SIP и RTP: Asterisk напрямую слушает порты сервера, а RTP использует исходный адрес сервера.

Не используйте Asterisk 20.6 из Ubuntu 24.04. В этой версии нет необходимых WebSocket-модулей.

Предварительные требования

Перед началом подготовьте:

сервер Ubuntu 24.04 с root или sudo;
публичное DNS-имя сервера Asterisk;
SIP-транк или PJSIP endpoint;
пароль для ARI-пользователя;
URL вашей Агентики.

Разрешите в сетевом экране:

Направление	Порт	Назначение
Входящий	TCP 8088	ARI HTTP и ARI WebSocket от Агентики
Входящий	UDP/TCP 5060	SIP, если эти протокол и порт использует оператор
Входящий	UDP 10000–20000	RTP
Исходящий	TCP 443	Media WebSocket к Агентике Cloud

Ограничьте TCP 8088 известными адресами Агентики или приватной сетью. Не публикуйте ARI в интернет без сетевого ограничения и сильного пароля.

Удалите пакетный Asterisk

Если Asterisk ещё не установлен, пропустите этот раздел. Сначала убедитесь, что активных звонков нет:

asterisk -rx "core show channels"

Сохраните конфигурацию и рабочие данные:

mkdir -p /root/asterisk-backup
tar -C / -czf /root/asterisk-backup/files.tar.gz \
  etc/asterisk var/lib/asterisk var/spool/asterisk var/log/asterisk

Остановите службу и удалите пакетную установку:

systemctl disable --now asterisk
apt-get purge -y asterisk asterisk-config asterisk-modules

Установите Docker

apt-get update
apt-get install -y docker.io docker-compose-v2
systemctl enable --now docker

Проверьте установку:

docker version
docker compose version

Создайте каталог развертывания

mkdir -p /opt/asterisk-docker/{config,data,spool,logs}
cd /opt/asterisk-docker

Dockerfile

Создайте /opt/asterisk-docker/Dockerfile:

FROM debian:bookworm-slim

ARG ASTERISK_VERSION=23.4.1
ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update \
 && apt-get install -y --no-install-recommends \
      autoconf autoconf-archive automake bison build-essential ca-certificates \
      curl flex libasound2-dev libcap-dev libcurl4-openssl-dev libedit-dev \
      libgsm1-dev libjansson-dev libncurses-dev libnewt-dev libogg-dev \
      libspeex-dev libspeexdsp-dev libsrtp2-dev libsqlite3-dev libssl-dev \
      libtool liburiparser-dev libvorbis-dev libxml2-dev libxslt1-dev patch \
      pkg-config python3-dev subversion uuid-dev wget xz-utils \
 && curl -fsSLO "https://downloads.asterisk.org/pub/telephony/asterisk/asterisk-${ASTERISK_VERSION}.tar.gz" \
 && curl -fsSLO "https://downloads.asterisk.org/pub/telephony/asterisk/asterisk-${ASTERISK_VERSION}.sha256" \
 && sha256sum -c "asterisk-${ASTERISK_VERSION}.sha256" \
 && tar -xzf "asterisk-${ASTERISK_VERSION}.tar.gz" \
 && cd "asterisk-${ASTERISK_VERSION}" \
 && ./configure \
      --prefix=/usr \
      --sysconfdir=/etc \
      --localstatedir=/var \
      --with-jansson-bundled \
      --with-pjproject-bundled \
 && make menuselect.makeopts \
 && menuselect/menuselect \
      --enable chan_websocket \
      --enable res_websocket_client \
      menuselect.makeopts \
 && make -j"$(nproc)" \
 && test -f channels/chan_websocket.so \
 && test -f res/res_websocket_client.so \
 && make install \
 && make samples \
 && cd / \
 && rm -rf \
      "asterisk-${ASTERISK_VERSION}" \
      "asterisk-${ASTERISK_VERSION}.tar.gz" \
      "asterisk-${ASTERISK_VERSION}.sha256" \
      /var/lib/apt/lists/* \
 && groupadd --gid 1000 asterisk \
 && useradd \
      --uid 1000 \
      --gid 1000 \
      --home-dir /var/lib/asterisk \
      --shell /usr/sbin/nologin \
      asterisk \
 && chown -R asterisk:asterisk \
      /etc/asterisk \
      /var/lib/asterisk \
      /var/spool/asterisk \
      /var/log/asterisk \
 && install -d -o asterisk -g asterisk /run/asterisk

CMD ["asterisk", "-f", "-vvv", "-U", "asterisk", "-G", "asterisk"]

Сборка завершается ошибкой, если один из обязательных WebSocket-модулей не был создан.

Compose

Создайте /opt/asterisk-docker/compose.yaml:

services:
  asterisk:
    build:
      context: .
      network: host
      args:
        ASTERISK_VERSION: 23.4.1
    image: local/asterisk:23.4.1
    container_name: asterisk
    network_mode: host
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
    volumes:
      - ./config:/etc/asterisk
      - ./data:/var/lib/asterisk
      - ./spool:/var/spool/asterisk
      - ./logs:/var/log/asterisk
    tmpfs:
      - /run/asterisk:uid=1000,gid=1000,mode=0755
    ulimits:
      nofile:
        soft: 65536
        hard: 65536
    healthcheck:
      test: ["CMD", "asterisk", "-rx", "core show uptime"]
      interval: 30s
      timeout: 5s
      retries: 3

NET_ADMIN нужен Asterisk, чтобы сохранить требуемую capability после перехода с root на пользователя asterisk.

Соберите образ и подготовьте тома

cd /opt/asterisk-docker
docker compose build --pull

Скопируйте исходные конфигурационные и служебные файлы из образа в bind mounts:

docker run --rm local/asterisk:23.4.1 \
  tar -C /etc/asterisk -cf - . | tar -C config -xf -

docker run --rm local/asterisk:23.4.1 \
  tar -C /var/lib/asterisk -cf - . | tar -C data -xf -

chown -R 1000:1000 config data spool logs
chmod 750 config data spool logs

Второй шаг обязателен: Asterisk 23 читает XML-документацию из /var/lib/asterisk. Пустой bind mount перекроет файлы внутри образа, и запуск завершится ошибкой Stasis initialization failed.

Настройте Asterisk

Все конфигурационные файлы находятся в /opt/asterisk-docker/config.

ARI

Замените содержимое config/ari.conf:

[general]
enabled = yes
pretty = no

[agentika]
type = user
read_only = no
password = REPLACE_WITH_A_STRONG_PASSWORD

Имя секции agentika и пароль потребуются при создании конфигурации телефонии в Агентике.

HTTP-сервер

Замените содержимое config/http.conf:

[general]
enabled = yes
bindaddr = 0.0.0.0
bindport = 8088

Media WebSocket

Для Агентики Cloud замените содержимое config/websocket_client.conf:

[agentika]
type = websocket_client
uri = wss://api.agentika.ai/api/v1/telephony/ws/ari
protocols = media
connection_type = per_call_config
tls_enabled = yes
ca_list_file = /etc/ssl/certs/ca-certificates.crt

Для self-hosted установки замените uri адресом вашего API:

[agentika]
type = websocket_client
uri = wss://agentika.example.com/api/v1/telephony/ws/ari
protocols = media
connection_type = per_call_config
tls_enabled = yes
ca_list_file = /etc/ssl/certs/ca-certificates.crt

Если Asterisk и Агентика находятся в одной доверенной сети без TLS, используйте ws:// и tls_enabled = no. Создайте config/chan_websocket.conf:

[global]
control_message_format = plain-text

Имя секции agentika в websocket_client.conf — это WebSocket Client Name в настройках телефонии Агентики.

SIP и RTP

Добавьте UDP-транспорт в config/pjsip.conf:

[transport-udp]
type = transport
protocol = udp
bind = 0.0.0.0:5060

Настройте endpoint, authentication и registration по данным вашего SIP-оператора. На endpoint и транке разрешите G.711 μ-law:

disallow = all
allow = ulaw

Проверьте диапазон в config/rtp.conf:

[general]
rtpstart = 10000
rtpend = 20000

Входящий dialplan

Добавьте в config/extensions.conf контекст, из которого оператор направляет входящие звонки:

[from-external]
exten => _X.,1,NoOp(Incoming call to ${EXTEN})
 same => n,Stasis(agentika)
 same => n,Hangup()

Имя в Stasis(agentika) должно совпадать с секцией ARI-пользователя.

Запустите Asterisk

cd /opt/asterisk-docker
docker compose up -d
docker compose ps

Статус контейнера должен измениться на healthy. Проверьте версию и обязательные модули:

docker exec asterisk asterisk -V
docker exec asterisk asterisk -rx "module show like chan_websocket"
docker exec asterisk asterisk -rx "module show like res_websocket_client"

Оба модуля должны иметь статус Running. Проверьте ARI, SIP и активные каналы:

docker exec asterisk asterisk -rx "http show status"
docker exec asterisk asterisk -rx "pjsip show transports"
docker exec asterisk asterisk -rx "core show channels"

Подключите Агентику

Откройте Telephony configurations и нажмите Add configuration.
Выберите Asterisk ARI.
Заполните поля:

Поле	Значение
ARI Endpoint URL	`http://asterisk.example.com:8088`
Stasis App Name	`agentika`
App Password	пароль из `ari.conf`
WebSocket Client Name	`agentika`
From Extensions	номера или SIP-расширения для исходящих звонков
Outbound Dialplan Context	контекст исходящего dialplan, если он нужен оператору

Сохраните конфигурацию.
Добавьте входящее расширение как номер телефона и назначьте ему workflow.
Выполните исходящий и входящий тестовые звонки.

Для входящего звонка dialplan Asterisk должен направить набранное расширение в Stasis(agentika), а это же расширение должно существовать среди номеров телефонии Агентики.

Управление контейнером

cd /opt/asterisk-docker

docker compose ps
docker compose logs -f --tail=200
docker compose restart
docker compose down
docker compose up -d

После изменения конфигурации примените её без пересборки образа:

docker exec asterisk asterisk -rx "core reload"

Для диагностики откройте CLI:

docker exec -it asterisk asterisk -rvvv

Обновление Asterisk

Измените ASTERISK_VERSION одновременно в Dockerfile и compose.yaml, затем пересоберите образ:

cd /opt/asterisk-docker
docker compose build --pull
docker compose up -d

Перед обновлением сохраните каталоги config, data и spool. Не удаляйте старый образ, пока не завершили тестовые звонки.

Устранение неполадок

Контейнер постоянно перезапускается

Выполните docker compose logs --tail=200. Для ошибки Stasis initialization failed повторно скопируйте /var/lib/asterisk из образа в каталог data и восстановите владельца командой chown -R 1000:1000 data.

ARI недоступен

Проверьте docker exec asterisk asterisk -rx "http show status", порт 8088, enabled = yes в http.conf и сетевые правила между Агентикой и Asterisk.

Media WebSocket не подключается

Проверьте websocket_client.conf, совпадение WebSocket Client Name и статус res_websocket_client. Для wss:// нужны tls_enabled = yes и доверенный CA.

Во время звонка нет звука

Проверьте статус chan_websocket, разрешение ulaw на SIP endpoint и транке, а также доступность UDP 10000–20000.

Входящий звонок сразу завершается

Проверьте, что dialplan вызывает Stasis(agentika), набранное расширение добавлено как номер телефона в Агентике и этому номеру назначен входящий workflow.

Начало работы

Основные понятия

Конфигурации

Конструктор голосовых агентов

Телефония

Интеграции

Asterisk ARI в Docker

Обзор

Предварительные требования

Удалите пакетный Asterisk

Установите Docker

Создайте каталог развертывания

Dockerfile

Compose

Соберите образ и подготовьте тома

Настройте Asterisk

ARI

HTTP-сервер

Media WebSocket

SIP и RTP

Входящий dialplan

Запустите Asterisk

Подключите Агентику

Управление контейнером

Обновление Asterisk

Устранение неполадок

Дополнительные материалы

​Обзор

​Предварительные требования

​Удалите пакетный Asterisk

​Установите Docker

​Создайте каталог развертывания

​Dockerfile

​Compose

​Соберите образ и подготовьте тома

​Настройте Asterisk

​ARI

​HTTP-сервер

​Media WebSocket

​SIP и RTP

​Входящий dialplan

​Запустите Asterisk

​Подключите Агентику

​Управление контейнером

​Обновление Asterisk

​Устранение неполадок

​Дополнительные материалы

Обзор

Предварительные требования

Удалите пакетный Asterisk

Установите Docker

Создайте каталог развертывания

Dockerfile

Compose

Соберите образ и подготовьте тома

Настройте Asterisk

ARI

HTTP-сервер

Media WebSocket

SIP и RTP

Входящий dialplan

Запустите Asterisk

Подключите Агентику

Управление контейнером

Обновление Asterisk

Устранение неполадок

Дополнительные материалы