izdock/izpbx-asterisk

izPBX Cloud Native VoIP Telephony System

镜像概述和主要用途

izPBX是一个开箱即用的云原生VoIP电话系统，基于Asterisk引擎和FreePBX管理界面构建，旨在提供云和本地环境下快速、自动化、可重复部署的VoIP PBX解决方案。该系统集成了电话引擎、Web管理界面、安全监控工具及多种实用功能，适用于企业级VoIP通信需求。

核心功能和特性

• 快速部署：60秒内完成从0到运行的完整PBX系统安装
• 引擎与界面集成：内置Asterisk®电话引擎（源码编译）和FreePBX® Web管理界面（预下载模块加速初始部署）
• 无供应商锁定：通过FreePBX备份导入/导出实现系统迁移
• 轻量级与高效：基于Rocky Linux 8 64位系统，镜像大小约450MB（相比官方FreePBX ISO的2300MB大幅缩减）
• 多租户支持：支持多租户PBX系统部署（详见「高级生产配置示例」）
• 安全防护：集成Fail2ban安全监控，阻止SIP和HTTP暴力***
• 实用工具：
  • tcpdump和sngrep用于VoIP呼叫调试
  • izsynth文本转语音（TTS）合成工具、背景音乐叠加器及音频转换器
  • izpbx-callstats等系统状态监控脚本
• 服务管理：通过supervisord实现服务监控和故障自动重启
• 附加服务：
  • Postfix MTA邮件服务（用于通知、语音邮件和传真发送）
  • 内置cron守护进程处理定时任务
  • DNSMasq提供TFTP和DHCP服务，支持VoIP话机自动配置
  • 集成NTP服务器、Apache 2.4（PHP 7.2）
• 证书管理：自动Let's Encrypt HTTPS证书管理，支持自定义商业SSL证书

支持的标签

生产分支

• 20.16, 20.16.X, 20.16.X-BUILD,20, latest（Asterisk 20 LTS + FreePBX 16）
• 18.16, 18.16.X, 18.16.X-BUILD,18（Asterisk 18 LTS + FreePBX 16）
• 18.15, 18.15.X, 18.15.X-BUILD（Asterisk 18 LTS + FreePBX 15）
• 16.15, 16.15.X, 16.15.X-BUILD（Asterisk 16 LTS + FreePBX 15）

开发分支

• Asterisk 20 LTS：dev-20, dev-20.X, dev-20.X.X-BUILD
• Asterisk 18 LTS：dev-18, dev-18.X, dev-18.X.X-BUILD

版本说明

标签格式：Z.Y.X-[BUILD]
其中：

• Z = Asterisk版本（PBX引擎）
• Y = FreePBX版本（PBX界面）
• X = izPBX版本（本项目）
• BUILD = 构建编号

最新版本可在https://hub.docker.com/r/izdock/izpbx-asterisk/tags%E6%9F%A5%E7%9C%8B%E3%80%82

使用场景和适用范围

• 企业通信系统：部署企业级VoIP电话系统，支持分机、语音邮件、呼叫转移等功能
• 多租户环境：服务提供商为多个客户部署独立PBX实例
• 快速原型验证：60秒内搭建测试环境，验证VoIP配置和功能
• 混合云部署：同时支持私有云、公有云和本地服务器部署

详细使用方法和配置说明

前置要求

• 安装Docker及Docker Compose（推荐版本：docker-ce ≥ 20.0，docker compose-plugin ≥ 2.0）
• 支持的操作系统：RHEL 6/7/8/9、Fedora >30、Debian 10、Ubuntu 20.04等

使用Docker Compose部署（推荐）

1. 准备环境

bash
# 安装Docker（以RHEL8为例）
sudo dnf config-manager --add-repo=https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf install docker-ce docker compose-plugin -y
sudo systemctl enable --now docker

# 克隆项目仓库
git clone https://github.com/ugoviti/izpbx.git /opt/izpbx
cd /opt/izpbx

# 检出最新官方版本
git checkout tags/$(git tag | sort --version-sort | tail -1)

2. 配置环境变量

bash
# 复制默认配置文件并自定义
cp default.env .env
vim .env  # 修改安全相关密码及网络配置

3. 启动服务

bash
docker compose up -d

等待镜像拉取完成（约60秒，取决于网络速度），通过浏览器访问Docker主机IP，按照初始设置向导完成配置。

注意：默认使用network_mode: host以处理SIP NAT和UDP流量，容器直接暴露到主机网络。如需在同一主机运行多个实例，需修改compose.yml并注释该配置，或使用macvlan网络模式。

自定义Compose配置

如需覆盖默认配置，创建docker-compose.override.yml文件，例如：

yaml
version: '3'
services:
  db:
    image: docker.io/mariadb:10.11.4  # 自定义数据库版本
  izpbx:
    image: docker.io/izdock/izpbx-asterisk:20.16.7  # 指定izPBX版本

使用docker compose up -d应用配置。

替代部署方法：Docker Run（不推荐用于生产）

1. 启动数据库

bash
docker run --rm -ti -v ./data/db:/var/lib/mysql \
  -e MYSQL_ROOT_PASSWORD=CHANGEM3 -e MYSQL_PASSWORD=CHANGEM3 \
  --name izpbx-db mariadb:10.4

2. 启动izPBX

bash
docker run --rm -ti --network=host --privileged --cap-add=NET_ADMIN \
  -v ./data/izpbx:/data \
  -e MYSQL_ROOT_PASSWORD=CHANGEM3 -e MYSQL_PASSWORD=CHANGEM3 \
  -e MYSQL_SERVER=127.0.0.1 -e MYSQL_DATABASE=asterisk \
  -e MYSQL_USER=asterisk -e APP_DATA=/data \
  --name izpbx izpbx-asterisk:latest

升级方法

常规版本升级

bash
# 更新项目代码
cd /opt/izpbx
git checkout main
git pull
git fetch --tags --all -f
git checkout tags/$(git tag | sort --version-sort | tail -1)

# 拉取最新镜像并重启服务
docker compose pull
docker compose up -d

# 若数据库版本更新，升级表结构
source .env ; docker exec -it izpbx-db mysql_upgrade -u root -p$MYSQL_ROOT_PASSWORD

# FreePBX模块升级（通过Web界面）
# 登录FreePBX → 管理员 → 模块管理 → 在线检查 → 升级所有 → 处理

跨FreePBX主版本升级

FreePBX仅在首次部署时安装到持久化目录。如需升级FreePBX主版本（如从15到16），需：

1. 备份数据目录（/opt/izpbx/data）
2. 在.env中设置FREEPBX_AUTOUPGRADE_CORE=true
3. 部署对应版本镜像（如18.16.x）
4. 系统将自动检测旧版本并启动升级流程

高级生产配置示例

多租户VoIP PBX（专用数据库）

目标

• 在单台Docker主机部署多个izPBX实例（每个实例需独立静态IP）
• 每个实例使用专用数据库

配置示例

创建部署目录及配置文件：

bash
mkdir /opt/yourgreatpbx && cd /opt/yourgreatpbx
vim compose.yml  # 编辑以下内容
vim .env         # 配置环境变量

compose.yml内容：

yaml
version: '3'
networks:
  izpbx-0-ext:  # 外部网络（macvlan）
    driver: macvlan
    driver_opts:
      parent: eth0  # 主机物理网卡
    ipam:
      config:
      - subnet: 10.1.1.0/24  # 与内网网段匹配
  izpbx-1:  # 内部桥接网络
    driver: bridge

services:
  db:  # 专用数据库服务
    image: mariadb:10.5.9
    restart: unless-stopped
    env_file: .env
    volumes:
    - ./data/db:/var/lib/mysql
    networks:
      izpbx-1:

  izpbx:  # PBX服务
    image: izdock/izpbx-asterisk:18.15.11
    restart: unless-stopped
    depends_on: [db]
    env_file: .env
    volumes:
    - ./data/izpbx:/data
    cap_add: [NET_ADMIN]
    privileged: true
    networks:
      izpbx-0-ext:
        ipv4_address: 10.1.1.221  # 分配独立IP
      izpbx-1:

启动服务：docker compose up -d，重复上述步骤部署其他实例（需修改IP和目录）。

服务管理命令

基础操作

bash
# 重启整个部署
docker compose restart

# 重启izpbx容器
docker restart izpbx

# 重启数据库容器
docker restart izpbx-db

容器内服务管理

bash
# 进入容器
docker exec -it izpbx bash

# 重启Asterisk服务
supervisorctl restart asterisk

# 查看所有服务状态
supervisorctl status

支持的服务：asterisk、cron、fail2ban、fop2、httpd、izpbx、tftpd等。

环境变量参考

默认环境变量定义在https://github.com/ugoviti/izpbx/blob/main/default.env%EF%BC%8C%E5%8C%85%E6%8B%AC%E6%95%B0%E6%8D%AE%E5%BA%93%E9%85%8D%E7%BD%AE%E3%80%81%E7%BD%91%E7%BB%9C%E7%AB%AF%E5%8F%A3%E3%80%81%E5%AE%89%E5%85%A8%E7%AD%96%E7%95%A5%E7%AD%89%E5%8F%82%E6%95%B0%E3%80%82

Zabbix监控配置

集成Asterisk Zabbix代理，监控服务健康状态。配置方法参考https://github.com/ugoviti/zabbix-templates/tree/main/asterisk%E3%80%82

FAQ / 故障排除

FOP2许可证激活

bash
# 进入容器
docker exec -it izpbx bash

# 注册许可证（替换LICENSECODE和Company Name）
/usr/local/fop2/fop2_server --rp=http --register --iface eth0 --name "Company Name" --code "LICENSECODE"

重置系统（数据将丢失）

bash
docker compose down
rm -rf /opt/izpbx/data
docker compose up -d

限制与待办事项

当前限制

• 容器设计采用“反模式”（因FreePBX生态依赖多服务）
• 默认network_mode: host限制单主机多实例部署（需手动配置macvlan）
• FreePBX模块更新需通过Web界面手动操作

未来计划

• 支持ARM架构（适配树莓派）
• Kubernetes部署（需解决RTP UDP端口范围问题）
• 集成Hylafax+服务器（支持传真发送）

快速参考

• 开发维护者：Ugo Viti (https://github.com/ugoviti/izpbx)
• 问题反馈：https://github.com/ugoviti/izpbx/issues
• 支持架构：amd64
• Docker版本：推荐最新版（最低支持1.6）
• 许可证：https://github.com/ugoviti/izpbx/blob/main/LICENSE

Dockerfile地址：https://github.com/ugoviti/izpbx/blob/main/izpbx-asterisk/Dockerfile