Автоматизированное развертывание 3CX на Proxmox

Обзор

В данном руководстве рассматривается автоматическое развертывание виртуальной машины АТС 3CX на платформе Proxmox VE. Используя универсальные облачные образы Debian и Cloud-Init, данный скрипт выделяет вычислительные ресурсы, настраивает сеть через DHCP, интегрирует необходимые установочные скрипты, и при необходимости может в автоматическом режиме восстановить резервную копию 3CX.

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

Перед запуском скрипта развертывания перепроверьте выполнение следующих предварительных требований:

  • Перейдите в Datacenter -> Storage.
  • Выберите local и нажмите Edit
  • В выпадающем меню Content перепроверьте, что выбраны опции Snippets и Disk Image.

  • Доступ Root: необходимо войти на узел Proxmox под учетной записью root.
  • Ключи SSH: на хосте Proxmox должна присутствовать пара ключей SSH (например, /root/.ssh/id_rsa).
  • Доступ в интернет: узел Proxmox должен иметь доступ к сайту cloud.debian.org для загрузки базового образа..
  • Резервирование DHCP: в целевой сети должен быть развернут сервер DHCP с зарезервированным IP-адресом, привязанным к MAC-адресу, указанному в конфигурации.

Примечание: В приведенном выше примере показано резервирование DHCP в среде WatchGuard.Конкретный интерфейс и шаги для настройки статической привязки MAC-адреса к IP-адресу будут отличаться в зависимости от используемого сетевого оборудования (например, pfSense, UniFi, FortiGate или Windows Server). Тем не менее, основное требование остается неизменным: статический уникальный MAC-адрес должен быть постоянно привязан к зарезервированному IP-адресу в сети и использоваться в файле .env, как описано ниже в разделе Развертывание АТС 3CX.

Загрузка инструментов развертывания 3CX на Proxmox

  • Войдите по SSH (или через функцию веб-консоли shell) под пользователем root на хост Proxmox
  • Перейдите в домашний каталог и загрузите инструменты развертывания 3CX:

cd ~

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

tar -zxvf 3cx-proxmox.tar.gz

Развертывание АТС 3CX

Подготовка папки развертывания

  • Создайте отдельную папку для новой АТС (в данном примере ~/3cx-proxmox/deployments/pbx01) и скопируйте в нее шаблон окружения:

cd ~/3cx-proxmox

cp -r deployment-template/ deployments/pbx01

Note: If you are performing a silent restore, you must also copy your setupconfig.xml and 3cx-backup.zip files into this folder.

Примечание:если вы выполняете автоматическое (тихое) восстановление, необходимо также скопировать файлы setupconfig.xml и 3cx-backup.zip в эту папку.

Настройка файла .ENV

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

Обратите внимание на следующие параметры:

  • установите для переменной PBX_INSTALLATION_MODE значение "manual" (по умолчанию):
  • Опция 1: создайте корректный файл ~/3cx-proxmox/deployments/pbx01/setupconfig.xml
  • Опция 2: также можно получить файл setupconfig.xml с готовой корректной минимальной конфигурацией на портале 3CX
  • если выполняется восстановление, установите для переменной BACKUP_FILE имя файла резервной копии (внутри каталога ~/3cx-proxmox/deployments/pbx01)
  • установите для переменной PBX_INSTALLATION_MODE значение "wizard" для загрузки веб-интерфейса настройки
  • установите для переменной VMID свободный уникальный ID виртуальной машины Proxmox
  • проверить текущие используемые ID виртуальных машин можно из консоли Proxmox с помощью команды qm list
  • установите подходящие значения (руководство доступно здесь: Hardware Requirements) для экземпляра 3CX для:
  • DISK_GB (по умолчанию 40)
  • CORES (по умолчанию 2)
  • SOCKETS (по умолчанию 1)
  • MEMORY_MB (по умолчанию 2048)
  • установите для переменной MAC_ADDRESS значение, заданное на этапе предварительных требований выше
  • (опционально) установите переменную VLAN_TAG (по умолчанию пусто)
  • установите требуемые переменные версии 3CX; для актуальной Version 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
  • (опционально) установите пути к файлам SSH_PUBLIC_KEY_FILE и SSH_PRIVATE_KEY_FILE, если были созданы пользовательские ключи для защиты связи между хостом Proxmox и гостевыми машинами

Дополнительную информацию можно найти здесь  Deploying 3CX и Provisioning Settings via setupconfig.xml

Структура каталогов проекта

Структура каталогов должна выглядеть следующим образом:

Запуск скрипта развертывания

Execute the main script, passing the path to the specific environment file using the --config (or -c) flag:

Запустите основной скрипт, передав путь к конкретному файлу окружения с помощью флага  --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.
  • Выделение вычислительных ресурсов виртуальной машины и настройка сетевого интерфейса.
  • Запуск виртуальной машины и ожидание ответа от QEMU Guest Agent с назначенным IP-адресом DHCP.

[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-адрес будет обнаружен, скрипт автоматически очистит файл known_hosts на Proxmox во избежание конфликтов SSH. Затем будет выполнено безопасное копирование файла резервной копии (при наличии) и удаленный запуск установочного скрипта 3cx-setup.sh.

По завершении операции отобразится баннер успешного выполнения со сводной информацией о виртуальной машине.

Заметки после развертывания

В зависимости от выбранного значения переменной PBX_INSTALLATION_MODE, финальные шаги будут отличаться:

  • Режим Wizard: скрипт будет опрашивать вновь созданную виртуальную машину, пока 3CX Web Wizard не станет доступен. После завершения перейдите по адресуhttp://<VM_IP>:5015 в браузере для завершения настройки.
  • Режим Manual: АТС 3CX установится в автоматическом режиме с использованием интегрированного файла setupconfig.xml и, при наличии, восстановит данные из файла резервной копии. Дальнейшее взаимодействие с мастером настройки не требуется.

Примечание: логи развертывания находятся в каталоге конфигурации. Например, ~/3cx-proxmox/deployments/pbx01/vm-300-deployment-notes.txt

Получение файла setupconfig.xml на портале 3CX

Чтобы получить предварительно настроенный минимальный файл setupconfig.xml напрямую с портала 3CX:

  • Войдите в учетную запись на портале 3CX

  • Выберите целевую систему и нажмите на ссылку Install

  • Выберите опции локального размещения (On Premise) и нажмите кнопку Next

  • Выберите количество знаков для добавочных номеров АТС и нажмите кнопку Next

  • Выберите региональные параметры для системы и нажмите кнопку Next

  • На финальной странице выберите платформу Linux
  • Нажмите на ссылку Download для загрузки файла SetupConfig.xml
  • переименуйте загруженный файл SetupConfig.xml в setupconfig.xml — скрипты установки чувствительны к регистру символов
  • Скопируйте файл setupconfig.xml на машину Proxmox в каталог ~/3cx-proxmox/deployments/pbx01/setupconfig.xml

Версия документа

Последнее обновление документа 26 мая 2026

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