izerxyz/3cx

3cx-docker

风险自负。不提供任何保证。请始终进行备份。

反馈或问题：https://github.com/izer-xyz/3cx-docker/issues

镜像概述和主要用途

3CX PBX电话系统Docker镜像，旨在提供简单、可靠的IP电话系统部署方案。该镜像具有多架构支持（Arm + x86），无需特殊权限（CAP_*或--privileged），构建过程简化（一步完成），且首次启动时自动运行Web配置向导，便于快速设置3CX系统。

核心功能和特性

• 多架构支持：同时支持Arm和x86架构，适应不同硬件环境
• 权限优化：无需特殊权限即可运行，提高安全性
• 简化构建：采用一步式自动化构建流程
• 便捷配置：首次启动时自动运行Web配置向导
• 轻量级：镜像大小约300Mb，资源占用低

使用场景和适用范围

适用于需要快速部署IP电话系统的中小企业、办公室或个人用户，尤其适合希望通过Docker容器化方式管理3CX PBX系统的场景。支持从备份自动恢复配置，便于系统迁移和升级。

使用方法和配置说明

基本部署步骤

1. 启动容器

bash
$ docker run \
  -d  \
  -t \
  --tmpfs /tmp \
  --tmpfs /run \
  --tmpfs /run/lock \
  -v      /sys/fs/cgroup:/sys/fs/cgroup:ro \
  -p      5015:5015 \
  -p      5000:5000 \
  -p      5001:5001 \
  -p      5060:5060 \
  -p      5060:5060/udp \
  -p      5090:5090 \
  -p      5090:5090/udp \
          ghcr.io/izer-xyz/3cx:latest

2. 通过Web配置向导设置3CX（仅在容器首次启动时运行）

bash
  chrome http://[主机名]:5015/?v=2

升级流程

升级（和设置过程）仅在首次运行时生效。若失败，需清理容器后重新启动或使用3CXCleanup命令。

自动/简单升级

使用预设的恢复配置进行升级：

bash
$ docker run \
  -d  \
  -t \
  --tmpfs /tmp \
  --tmpfs /run \
  --tmpfs /run/lock \
  -v      /sys/fs/cgroup:/sys/fs/cgroup:ro \
  -p      5015:5015 \
  -p      5000:5000 \
  -p      5001:5001 \
  -p      5060:5060 \
  -p      5060:5060/udp \
  -p      5090:5090 \
  -p      5090:5090/udp \
  -v    /mnt/3cx:/mnt/3cx \
  --env CX_BACKUP_FILE=/mnt/voip/backups/3CXScheduledBackup.zip \
  --env CX_PUBLIC_IP=X.X.X.X \
  --env CX_INTERNAL_FQDN=3cx.example.com \
          ghcr.io/izer-xyz/3cx:latest

环境变量说明：

• CX_BACKUP_FILE: 要恢复的计划备份文件位置
• CX_PUBLIC_IP: 服务器的公网IPv4地址
• CX_INTERNAL_FQDN: 服务器的内部完全限定域名（非3CX提供的公网域名）

自动自定义升级（未测试）

使用自定义的setupconfig.xml配置文件。示例假设/mnt/3cx/config/setupconfig.xml已包含适当的实例配置：

bash
$ docker run \
  -d  \
  -t \
  --tmpfs /tmp \
  --tmpfs /run \
  --tmpfs /run/lock \
  -v      /sys/fs/cgroup:/sys/fs/cgroup:ro \
  -p      5015:5015 \
  -p      5000:5000 \
  -p      5001:5001 \
  -p      5060:5060 \
  -p      5060:5060/udp \
  -p      5090:5090 \
  -p      5090:5090/udp \
  -v    /mnt/3cx:/mnt/3cx \
  -v    /mnt/3cx/config:/etc/3cxpbx \
          ghcr.io/izer-xyz/3cx:latest

手动升级

1. 备份3CX实例（建议运行计划备份，因为容器可能不持久化数据）
2. 下载备份ZIP文件
3. 将容器升级到新版本
4. 通过Web配置从备份ZIP恢复
5. 若修改过备份位置，需重新设置（备份似乎不包含配置）
6. 检查E164处理设置（添加/删除前缀）

故障排除

• 检查日志：查看/var/lib/3cxpbx/Data/Logs/PbxConfigTool.log
• 设置失败处理（警告：这将删除所有用户数据！）：

bash
  $ docker exec -it [容器ID]  /usr/sbin/3CXCleanup

参考资料

• 3CX端口说明
• https://github.com/ekondayan/docker-3cx
• https://hub.docker.com/r/jrei/systemd-debian
• https://github.com/docker/build-push-action/blob/master/docs/advanced/push-multi-registries.md
• 自动配置PBX
• setupconfig.xml示例