3CX Proxmox 自动化部署指南

概述

本指南介绍如何在 Proxmox VE 上自动化部署 3CX PBX 虚拟机。利用 Debian 通用云镜像和 Cloud-Init，该脚本会配置计算资源、通过 DHCP 处理网络配置、注入所需的安装脚本，并可选择静默恢复 3CX 备份。

先决条件

运行部署脚本之前，请确保满足以下先决条件：

  • 进入“数据中心 (Datacenter)” -> “存储 (Storage)”。
  • 选择本地（ local） 并点击 编辑 (Edit)
  • 在“内容 (Content)”下拉菜单中，确保选中 代码段 (Snippets) 和 磁盘映像 (Disk Image) 选项。

  • Root 访问权限： 必须作为 root 用户登录 Proxmox 节点。
  • SSH 密钥： Proxmox 主机上必须已存在 SSH 密钥对（例如/root/.ssh/id_rsa）。
  • 互联网访问： Proxmox 节点必须能够访问 cloud.debian.org 以下载基础镜像。
  • DHCP 保留：目标网络中必须有一个 DHCP 服务器，其保留的 IP 地址映射到您在配置中定义的 MAC 地址。

注意：上例展示了在 WatchGuard 环境中的 DHCP 保留配置。确切的界面和配置静态 MAC 到 IP 绑定的步骤将因您的具体网络设备（例如 pfSense、UniFi、FortiGate 或 Windows Server）而异。核心要求不变：这个唯一的静态 MAC 地址将在您的网络上永久绑定到这个保留的 IP 地址，并将在下面的部署您的 3CX 电话系统部分中描述的.env 文件中使用。.

下载 3CX Proxmox 部署工具

  • 以 root 用户通过 SSH（或 Web 管理的 shell 功能）登录 Proxmox 主机
  • 进入 home 文件夹并下载 3CX 部署工具：

cd ~

wget https://downloads-global.3cx.com/downloads/misc/3cx-proxmox.tar.gz

tar -zxvf 3cx-proxmox.tar.gz

部署您的 3CX 电话系统

准备部署文件夹

  • 为您的新 PBX 创建一个专用文件夹（本例中为 ~/3cx-proxmox/deployments/pbx01），并将环境模板复制到其中：

cd ~/3cx-proxmox

cp -r deployment-template/ deployments/pbx01

注意：如果您要执行静默还原，则还必须复制您的setupconfig.xml 和 3cx-backup.zip文件放入此文件夹。

配置 .ENV 文件

nano ~/3cx-proxmox/deployments/pbx01/3cx-proxmox.env

请注意以下事项：

  • 设置 PBX_INSTALLATION_MODE 为 "manual"（默认值）：
  • 方案一：创建一个有效的~/3cx-proxmox/deployments/pbx01/setupconfig.xml 文件
  • 方案二：您可以从 3CX 门户获取一个已准备好有效最小配置的 setupconfig.xml 文件
  • 如果要执行恢复，请将 BACKUP_FILE 设置为您的备份文件名（位于 ~/3cx-proxmox/deployments/pbx01 内）
  • 设置 PBX_INSTALLATION_MODE 为 "wizard"，以启动进入 Web UI 设置向导
  • 将 VMID 设置为一个可用的唯一 Proxmox VM ID
  • 您可以通过在 proxmox shell 中运行 qm list 来检查当前已使用的 VM ID
  • 根据您的 3CX 实例设置适当的值（一些参考：硬件要求）：磁盘大小（默认值 40）
  • DISK_GB（默认 40）
  • CORES（默认 2）
  • SOCKETS（默认 1）
  • MEMORY_MB（默认 2048）
  • 将 MAC_ADDRESS 设置为您在上面前提条件阶段中设置的值
  • （可选）设置您的 VLAN_TAG（默认为空）
  • 设置所需的 3CX 版本变量；对于最新的版本 20 Update 8：：
  • PBX_VERSION="20.0.8.1121"
  • PBX_REPO="bookworm"
  • PBX_REPO_VERSION="2008"
  • CLOUD_IMAGE_URL=https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-amd64.qcow2
  • CLOUD_IMAGE_FILE=debian-12.qcow2
  • （可选）如果您创建了自定义密钥来保护 proxmox 主机与来宾之间的通信，请设置 SSH_PUBLIC_KEY_FILE 和 SSH_PRIVATE_KEY_FILE 的路径

您可以阅读更多关于通过 setupconfig.xml 部署 3CX 和配置设置

项目目录结构

你的目录结构应该如下所示：

运行部署脚本

执行主脚本，使用 --config（或 -c）标志传递特定环境文件的路径：

cd ~/3cx-proxmox

./create-3cx-vm.sh --config ./deployments/pbx01/3cx-proxmox.env

root@QA-pve:~# cd ~/3cx-proxmox

root@QA-pve:~/3cx-proxmox# ./create-3cx-vm.sh --config ./deployments/pbx01/3cx-proxmox.env

[INFO] Deployment configuration folder: /root/3cx-proxmox/deployments/pbx01

[INFO] Creating unique Cloud-Init profile at /var/lib/vz/snippets/3cx-profile-300.yaml...

[INFO] Injecting XML setupconfig.xml...

[INFO] Injecting script ./scripts/3cx-setup.sh...

[INFO] Injecting PBX version to install 20.0.8.1121.

[INFO] Injecting PBX repository distribution...

[INFO] Injecting PBX repository version channel...

[INFO] Injecting PBX installation mode...

[INFO] Creating VM 300

[INFO] Importing Disk...

importing disk '/var/lib/vz/template/qcow2/debian-12.qcow2' to VM 300 ...

Formatting '/var/lib/vz/images/300/vm-300-disk-0.raw', fmt=raw size=3221225472 preallocation=off

transferred 0.0 B of 3.0 GiB (0.00%)

transferred 30.7 MiB of 3.0 GiB (1.00%)

监控部署

脚本提供实时终端反馈。它将系统性地：

  • 下载 Debian 云镜像（如果未缓存）。
  • 将您的脚本和变量动态注入到唯一的 Cloud-Init 代码段中。
  • 配置 VM 计算资源和网络接口。
  • 启动 VM 并等待 QEMU 客户机代理报告分配的 DHCP IP 地址。

[INFO] Applying Cloud-Init settings...

update VM 300: -cicustom vendor=local:snippets/3cx-profile-300.yaml -ciuser root -ipconfig0 ip=dhcp -scsi1 local:cloudinit -serial0 socket -sshkeys ssh-rsa%20AAAAB3NzaC1yc2EAAAADAQABAAACAQCifHLUh%2FJ%2F2gK%2Fz1uYuipXtgLxgaf6Egj%2B%2BhTPKWb%2Ba5Uc%2FOfIaA1Km8YuZrXE3652DA7mhjMmAslyYSno2uARwRnGzpwVPLnFEwshylPiiHdaS%2FFgSAV6XpQyzLepbB01ek4QqrPhB35NDGxlrIeKYRycfFdgy%2Fcwj54EQtHTIMwDBpczjRQxf%2BMISqgL5rJRziWfuuXAh06ocP1J8m4yAb8EGygVgXZIcuyToXQXweFq6zEl%2FnhqEACtVdcNJedcjpXiJENk%2Fd%2BTqoYQFcA42vHk5DI2vJ7uY3qkgTkDzz4PjkKXPu2VwHFH9DIdBkVMxx1HVBxGuDIkFSnc5IUlqEW7oKnUQAycZyt%2BOLbZNpKQNhMZ9itgRPEx96w%2BJy%2BllYoFF2H5LavE7wmBiN6aT8YS209xLV9jGhikU0JM0EfEUiQfTDM836xpdJgUZWbxXHxpmMR2XfDdPgo6jbA7JGzzR3BjGYDie3SbjNVk%2B9PugBSu1wSVgq3sfR9I%2FWLHw%2FRJlsuE19yMcSsuhahIP9rrcxc38bSFJbHW4yj1adhoKSzGi1XBB0QzVbL34grztYZ1BTtWP76FWtr1zc1Gy28AwqfRLasUgWWbosaiPJ%2Fkkn0ErlmDLI0ra%2Bibu%2BRItyzBiH4UcEkay5GOVLkpg%2FWyvHjcihZfN6SC50tdhw%3D%3D%20root%40QA-pve%0A -vga serial0

Formatting '/var/lib/vz/images/300/vm-300-cloudinit.qcow2', fmt=qcow2 cluster_size=65536 extended_l2=off preallocation=metadata compression_type=zlib size=4194304 lazy_refcounts=off refcount_bits=16

scsi1: successfully created disk 'local:300/vm-300-cloudinit.qcow2,media=cdrom'

generating cloud-init ISO

[INFO] Virtual machine has been deployed successfully.

[INFO] Generating deployment notes file...

[INFO] Starting VM...

generating cloud-init ISO

[INFO] Waiting for QEMU Guest Agent to report IP address (this takes 1-2 minutes)...

[INFO] VM is online with IP: 10.28.5.177

[INFO] Waiting for SSH to be ready...

[INFO] Clear old IP address in known_hosts file that might interfere with the SSH connection...

# Host 10.28.5.177 found: line 1

/root/.ssh/known_hosts updated.

Original contents retained as /root/.ssh/known_hosts.old

[INFO] Executing 3CX Setup Script...

自动化设置与交接

一旦检测到 IP 地址，脚本会自动清理您的 Proxmox known_hosts 文件，以防止 SSH 冲突。然后，它会安全地复制备份文件（如果提供）并在远程执行 3cx-setup.sh 安装脚本。

完成后，将显示成功横幅以及虚拟机摘要。

部署后说明

根据所选的 PBX_INSTALLATION_MODE，最后步骤将有所不同：

  • 向导模式（Wizard Mode）:脚本将轮询新创建的 VM，直到 3CX Web 向导响应。完成后，在浏览器中导航到http://<VM_IP>:5015完成设置。
  • 手动模式（Manual Mode）：PBX 将使用注入的 setupconfig.xml 静默安装，并可选地从提供的备份文件恢复。无需进一步的向导交互。

注意： 部署日志可以在配置目录下找到。例如：~/3cx-proxmox/deployments/pbx01/vm-300-deployment-notes.txt

从 3CX 门户获取 setupconfig.xml 文件

要从 3CX 门户直接获取预配置的最小 setupconfig.xml 文件：

  • 登录您的 3CX 门户帐户

  • 确定您的目标系统，并点击 安装 (Install) 链接

  • 选择本地部署选项并点击下一个 按钮

  • 选择系统扩展号码的位数，然后单击下一步 按钮

  • 选择您系统的区域偏好设置，然后单击下一步 按钮

  • 在最后一页，选择Linux 平台
  • 点击下载链接下载SetupConfig.xml 文件
  • 将下载的 SetupConfig.xml 重命名为 setupconfig.xml - 安装脚本区分大小写
  • 复制setupconfig.xml将文件保存到您的 Proxmox 机器中~/3cx-proxmox/deployments/pbx01/setupconfig.xml

最后更新时间

本文件最后更新日期为2026年5月26日。

https://www.3cx.cn/docs/proxmox-autodeployment/