Automatyczne wdrażanie 3CX na Proxmox

Informacje ogólne

Ten przewodnik opisuje zautomatyzowane wdrażanie maszyny wirtualnej 3CX PBX na platformie Proxmox VE. Wykorzystując ogólne obrazy chmurowe Debiana oraz narzędzie Cloud-Init, skrypt ten przydziela zasoby obliczeniowe, obsługuje konfigurację sieci przez DHCP, wstrzykuje wymagane skrypty instalacyjne i opcjonalnie może przeprowadzić cichą operację przywracania kopii zapasowej 3CX.

Wymagania wstępne

Przed uruchomieniem skryptu wdrażania upewnij się, że spełnione są poniższe wymagania:

  • Przejdź do „Datacenter” -> „Storage”.
  • Wybierz „local” i kliknij „Edit”.
  • W liście rozwijanej „Content” upewnij się, że wybrano opcje „Snippets” oraz „Disk Image”.

  • Dostęp Root: Musisz być zalogowany do węzła Proxmox jako użytkownik root.
  • Klucze SSH: Na hoście Proxmox musi istnieć para kluczy SSH (np. /root/.ssh/id_rsa).
  • Dostęp do Internetu: Węzeł Proxmox musi mieć możliwość połączenia z cloud.debian.org w celu pobrania obrazu bazowego.
  • Rezerwacja DHCP: Sieć docelowa musi posiadać serwer DHCP z zarezerwowanym adresem IP przypisanym do adresu MAC zdefiniowanego w Twojej konfiguracji.

Uwaga: Powyższy przykład przedstawia rezerwację DHCP w środowisku WatchGuard. Dokładny interfejs i kroki konfiguracji statycznego przypisania adresu MAC do IP będą się różnić w zależności od posiadanego sprzętu sieciowego (np. pfSense, UniFi, FortiGate lub Windows Server). Podstawowy wymóg pozostaje taki sam: ten unikalny, statyczny adres MAC musi być na stałe powiązany z zarezerwowanym adresem IP w Twojej sieci i zostanie użyty w pliku .env, jak opisano poniżej w sekcji „Wdrażanie systemu telefonicznego 3CX”.

Pobieranie narzędzi wdrażania 3CX dla Proxmox

  • Zaloguj się przez SSH (lub funkcję powłoki w panelu WWW) jako użytkownik root na hoście Proxmox.
  • Przejdź do katalogu domowego i pobierz narzędzia wdrażania 3CX:

cd ~

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

tar -zxvf 3cx-proxmox.tar.gz

Wdrażanie systemu telefonicznego 3CX

Przygotowanie folderu wdrożeniowego

  • Utwórz dedykowany folder dla swojej nowej centrali PBX (w tym przykładzie ~/3cx-proxmox/deployments/pbx01) i skopiuj do niego szablon środowiska:

cd ~/3cx-proxmox

cp -r deployment-template/ deployments/pbx01

Uwaga: Jeśli przeprowadzasz ciche przywracanie systemu, musisz również skopiować pliki setupconfig.xml oraz 3cx-backup.zip do tego folderu.

Konfiguracja pliku .ENV

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

Zwróć uwagę na następujące parametry:

  • Ustaw PBX_INSTALLATION_MODE na "manual" (domyślnie):
  • Opcja 1: utwórz prawidłowy plik ~/3cx-proxmox/deployments/pbx01/setupconfig.xml.
  • Opcja 2: alternatywnie możesz pobrać już przygotowany plik setupconfig.xml z minimalną prawidłową konfiguracją z Portalu 3CX.
  • Jeśli wykonujesz przywracanie systemu, ustaw BACKUP_FILE na nazwę pliku swojej kopii zapasowej (znajdującego się w ~/3cx-proxmox/deployments/pbx01).
  • Ustaw PBX_INSTALLATION_MODE na "wizard", aby uruchomić konfigurację przez interfejs WWW.
  • Ustaw VMID na wolny, unikalny identyfikator maszyny wirtualnej w Proxmox.
  • Możesz sprawdzić aktualnie używane identyfikatory VM w konsoli Proxmox poleceniem qm list.
  • Ustaw odpowiednie wartości dla swojej instancji 3CX (wskazówki znajdziesz w przewodniku Wymagania sprzętowe):
  • DISK_GB (domyślnie 40)
  • CORES (domyślnie 2)
  • SOCKETS (domyślnie 1)
  • MEMORY_MB (domyślnie 2048)
  • Ustaw MAC_ADDRESS na wartość ustaloną w sekcji wymagań wstępnych powyżej.
  • (Opcjonalnie) ustaw VLAN_TAG (domyślnie puste).
  • Ustaw zmienne dla żądanej wersji 3CX; dla najnowszej wersji 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
  • (Opcjonalnie) ustaw ścieżki SSH_PUBLIC_KEY_FILE i SSH_PRIVATE_KEY_FILE, jeśli utworzyłeś niestandardowe klucze w celu zabezpieczenia komunikacji między hostem Proxmox a maszynami gośćmi.

Więcej informacji znajdziesz w dokumencie: Wdrażanie 3CX i ustawienia autokonfiguracji przez setupconfig.xml.

Struktura katalogów projektu

Twoja struktura katalogów powinna wyglądać następująco:

Uruchomienie skryptu wdrażania

Wykonaj główny skrypt, podając ścieżkę do konkretnego pliku środowiskowego za pomocą flagi --config (lub -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%)

Monitorowanie procesu wdrażania

Skrypt dostarcza bieżące informacje w terminalu. Systematycznie wykona następujące czynności:

  • Pobierze obraz chmurowy Debiana (jeśli nie jest w pamięci podręcznej).
  • Dynamicznie wstrzyknie Twoje skrypty i zmienne do unikalnego snippetu Cloud-Init.
  • Przydzieli zasoby obliczeniowe VM oraz interfejs sieciowy.
  • Uruchomi maszynę wirtualną i poczeka, aż QEMU Guest Agent zgłosi przypisany adres IP z 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...

Automatyczna konfiguracja i przekazanie systemu

Po wykryciu adresu IP skrypt automatycznie czyści plik known_hosts w Proxmox, aby zapobiec konfliktom SSH. Następnie bezpiecznie kopiuje plik kopii zapasowej (jeśli został podany) i zdalnie wykonuje skrypt instalacyjny 3cx-setup.sh.

Po zakończeniu zostanie wyświetlony baner sukcesu z podsumowaniem maszyny wirtualnej.

Uwagi po wdrożeniu

W zależności od wybranego trybu PBX_INSTALLATION_MODE, końcowe kroki będą się różnić:

  • Tryb Wizard: Skrypt będzie odpytywać nowo utworzoną maszynę wirtualną, aż kreator WWW 3CX stanie się dostępny. Po zakończeniu przejdź pod adres http://<VM_IP>:5015 w swojej przeglądarce, aby sfinalizować konfigurację.
  • Tryb Manual: Centrala PBX zainstaluje się cicho, korzystając z wstrzykniętego pliku setupconfig.xml i opcjonalnie przywróci dane z dostarczonego pliku kopii zapasowej. Dalsza interakcja z kreatorem nie jest wymagana.

Uwaga: Logi wdrażania można znaleźć w katalogu konfiguracyjnym. Na przykład: ~/3cx-proxmox/deployments/pbx01/vm-300-deployment-notes.txt

Pobieranie pliku setupconfig.xml z Portalu 3CX

Aby pobrać wstępnie skonfigurowany, minimalny plik setupconfig.xml bezpośrednio z Portalu 3CX:

  • Zaloguj się na swoje konto w Portalu 3CX.

  • Zidentyfikuj system docelowy i kliknij link „Install” (Zainstaluj).

  • Wybierz opcje „On Premise” i kliknij przycisk „Next” (Dalej).

  • Wybierz liczbę cyfr dla numerów wewnętrznych systemu i kliknij „Next”.

  • Wybierz preferencje regionalne dla swojego systemu i kliknij „Next”.

  • Na ostatniej stronie wybierz platformę „Linux”.
  • Kliknij link „Download”, aby pobrać plik SetupConfig.xml.
  • Zmień nazwę pobranego pliku SetupConfig.xml na setupconfig.xml – skrypty instalacyjne rozróżniają wielkość liter.
  • Skopiuj plik setupconfig.xml do swojej maszyny Proxmox do katalogu ~/3cx-proxmox/deployments/pbx01/setupconfig.xml


Ostatnia aktualizacja
Ten dokument został ostatnio zaktualizowany 26 maja 2026 r.
https://www.3cx.pl/docs/proxmox-autodeployment/