Guia de Implantação Automatizada do 3CX no Promox

Visão Geral

Este guia aborda a implantação automatizada de uma Máquina Virtual com PABX 3CX no Proxmox VE. Utilizando imagens genéricas do Debian para nuvem e o Cloud-Init, este script provisiona os recursos de computação, gerencia a configuração de rede via DHCP, executa os scripts de instalação necessários e, opcionalmente, pode restaurar um backup do 3CX de forma silenciosa.

Pré-requisitos

Antes de executar o script de implantação, verifique se os pré-requisitos a seguir estão atendidos:

  • Vá para Datacenter -> Armazenamento.
  • Selecione local e clique em Editar
  • No menu suspenso Conteúdo, certifique-se de que as opções Snippets e Imagem de Disco estejam selecionadas.

Tela de edição de diretório no Proxmox com opções de conteúdo

  • Acesso como Root: Você deve estar conectado ao node (nó) Proxmox como root.
  • SSH Keys: Chaves SSH: Deve existir um par de chaves SSH no host Proxmox (por exemplo, /root/.ssh/id_rsa).
  • Internet Access: Acesso à Internet: O node Proxmox deve conseguir acessar o site cloud.debian.org para baixar a imagem base.
  • Reserva DHCP: A rede de destino deve ter um servidor DHCP com um endereço IP reservado mapeado para o endereço MAC definido na sua configuração.

Tela de configuração de reserva DHCP no ambiente WatchGuard

Observação: O exemplo acima ilustra uma reserva DHCP em um ambiente WatchGuard. A interface específica e as etapas para configurar uma associação estática entre MAC e IP variam de acordo com o seu equipamento de rede específico (por exemplo, pfSense, UniFi, FortiGate ou Windows Server). O requisito principal permanece o mesmo: esse endereço MAC estático e exclusivo será vinculado permanentemente a esse endereço IP reservado na sua rede e será usado no seu arquivo .env, conforme descrito abaixo na seção Implantando o seu Sistema Telefônico 3CX.

Baixe as Ferramentas de Implantação do 3CX para Proxmox

  • Faça login via SSH (ou pela função de gerenciamento web) como usuário root no Host Proxmox
  • Acesse a pasta inicial e baixe as ferramentas de implantação do 3CX:

cd ~

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

tar -zxvf 3cx-proxmox.tar.gz

Implantação do Seu Sistema Telefônico 3CX

Prepare sua pasta de implantação

  • Crie uma pasta exclusiva para o seu novo PABX (neste exemplo, ~/3cx-proxmox/deployments/pbx01) e copie o modelo de ambiente para dentro dela:

cd ~/3cx-proxmox

cp -r deployment-template/ deployments/pbx01

Observação: Se você estiver realizando uma restauração silenciosa, também deverá copiar os arquivos setupconfig.xml e 3cx-backup.zip para esta pasta.

Configure Seu Arquivo .ENV

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

Preste atenção ao seguinte:

  • Defina PABX_INSTALLATION_MODE como "manual" (o padrão):
  • Opção 1: criar um arquivo ~/3cx-proxmox/deployments/pbx01/setupconfig.xml válido
  • Opção 2: como alternativa, você pode obter do Portal 3CX um arquivo setupconfig.xml já preparado com uma configuração mínima válida
  • Se você estiver realizando uma restauração, defina BACKUP_FILE com o nome do arquivo de backup (localizado em ~/3cx-proxmox/deployments/pbx01)
  • Defina PABX_INSTALLATION_MODE como "wizard" para inicializar na configuração da interface do usuário da web
  • Defina VMID para um ID de VM Proxmox único e disponível
  • Você pode verificar os IDs das VMs atualmente em uso no shell do Proxmox com qm list
  • DISK_GB (padrão 40)
  • CORES (padrão 2)
  • SOCKETS (padrão 1)
  • MEMORY_MB (padrão 2048)
  • Defina seu MAC_ADDRESS para o valor que você configurou na etapa de pré-requisitos acima
  • (opcional) defina sua VLAN_TAG (padrão vazio)
  • defina as variáveis da Versão 3CX desejada; para a Versão mais recente, a 20 Update 8:
  • PABX_VERSION="20.0.8.1121"
  • PABX_REPO="bookworm"
  • PABX_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
  • (opcional) defina os caminhos para SSH_PUBLIC_KEY_FILE e SSH_PRIVATE_KEY_FILE caso tenha criado chaves personalizadas para proteger as comunicações entre o host Proxmox e os guests

Você pode ler mais sobre a Implantação do 3CX e as Configurações de Provisionamento via setupconfig.xml

Estrutura do Diretório do Projeto

É assim que sua estrutura de diretórios deve ficar:

Estrutura de diretórios do projeto 3CX-Proxmox

Execute o Script de Implantação

Execute o script principal, passando o caminho para o arquivo de ambiente específico usando a flag --config (ou -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%)

Monitorar a Implantação

O script fornece feedback em tempo real no terminal. Ele irá, sistematicamente:

  • Baixar a imagem do Debian para nuvem (se não estiver em cache).
  • Inserir dinamicamente seus scripts e variáveis em um único trecho de código do Cloud-Init.
  • Providencie os recursos de computação da VM e a interface de rede.
  • Inicie a VM e aguarde até que o QEMU Guest Agent informe o endereço IP atribuído pelo 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...

Configuração Automatizada e Transferência

Assim que o endereço IP for detectado, o script limpa automaticamente o arquivo `known_hosts` do Proxmox para evitar conflitos de SSH. Em seguida, ele copia com segurança o arquivo de backup (se fornecido) e executa remotamente o script de instalação `3cx-setup.sh`.

Após a conclusão, será exibida uma mensagem de sucesso com o resumo da VM.

Tela de resumo da implantação da VM 3cx com detalhes de configuração

Observações Pós-implantação

Dependendo do PBX_INSTALLATION_MODE selecionado, as etapas finais variam:

  • Modo Assistente: O script irá consultar a VM recém-criada até que o Assistente Web do 3CX volte a responder. Quando concluído, acesse http://<VM_IP>:5015 no seu navegador para finalizar a configuração.
  • Modo manual: O PABX será instalado automaticamente utilizando o arquivo setupconfig.xml inserido e, opcionalmente, restaurará a partir do arquivo de backup fornecido. Não é necessária nenhuma interação adicional com o assistente.

Observação: os registros de implantação podem ser encontrados no diretório de configuração. Por exemplo, ~/3cx-proxmox/deployments/pbx01/vm-300-deployment-notes.txt

Baixe o Arquivo Setupconfig.xml do Portal 3CX

Para obter um arquivo setupconfig.xml pré-configurado e minimalista diretamente do Portal 3CX:

  • Faça login na sua conta do 3CX Portal

Tela de gerenciamento de sistemas 3CX com opção de instalar

  • Identifique o seu sistema de destino e clique no link “Instalar”

Opções de instalação do 3CX: Nuvem Privada, No local, Hospedado

  • Selecione a opção “No local” e clique no botão “Avançar”

Tela de configuração do número de dígitos dos ramais no sistema 3CX

  • Selecione o número de dígitos para os ramais do seu sistema e clique no botão “Avançar”

Tela de configuração de preferências regionais do sistema

  • Selecione as preferências regionais do seu sistema e clique no botão “Avançar”

Passos para instalar o 3CX após download

  • Na página final, selecione a plataforma Linux
  • Clique no link “Download” para baixar o arquivo SetupConfig.xml
  • Renomeie o arquivo SetupConfig.xml baixado para setupconfig.xml — os scripts de instalação diferenciam maiúsculas de minúsculas
  • Copie o arquivo setupconfig.xml para sua máquina Proxmox, no diretório ~/3cx-proxmox/deployments/pbx01/setupconfig.xml

Última Atualização

Este documento foi atualizado pela última vez em 26 de maio de 2026

https://www.3cx.com.br/docs/proxmox-autodeployment/