Guía de Instalación Automatizada de 3CX en Proxmox

Resumen

Esta guía describe la instalación automatizada de una Máquina Virtual con el PBX 3CX en Proxmox VE. Mediante el uso de imágenes genéricas de Debian para la nube y Cloud-Init, este script aprovisiona los recursos de computación, maneja la configuración de red a través de DHCP, ejecuta los scripts de instalación necesarios y, opcionalmente, puede restaurar una copia de seguridad de 3CX de forma silenciosa.

Requisitos Previos

Antes de ejecutar el script de instalación, asegúrese de que se cumplan los siguientes requisitos previos:

  • Vaya a Datacenter -> Almacenamiento.
  • Seleccione local y haga clic en Editar.
  • En el menú desplegable Contenido, asegúrese de que las opciones Snippets e Imagen de Disco estén seleccionadas.

  • Acceso Root: Debe haber iniciado sesión en el nodo Proxmox como usuario root.
  • Claves SSH: Debe existir un par de claves SSH en el host Proxmox (por ejemplo, /root/.ssh/id_rsa).
  • Acceso a Internet: El nodo Proxmox debe poder conectarse a cloud.debian.org para descargar la imagen base.
  • Reserva DHCP: La red de destino debe contar con un servidor DHCP que tenga una dirección IP reservada asignada a la dirección MAC definida en su configuración.

Reservación de DHCP

Nota: El ejemplo anterior muestra una reservación DHCP en un entorno WatchGuard. La interfaz concreta y los pasos para configurar una vinculación estática de MAC a IP variarán en función de su equipo de red específico (por ejemplo, pfSense, UniFi, FortiGate o Windows Server). El requisito principal sigue siendo el mismo: esta dirección MAC única y estática quedará vinculada de forma permanente a esta dirección IP reservada en su red, y se utilizará en su archivo .env tal como se describe a continuación en la sección Instalación de Sistema Telefónico 3CX.

Descargar las Herramientas de Instalación de 3CX para Proxmox

  • Inicie sesión a través de SSH (o mediante la función de administración web) como usuario root en el host Proxmox
  • Vaya a la carpeta de inicio y descargue las herramientas de instalación de 3CX:

cd ~

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

tar -zxvf 3cx-proxmox.tar.gz

Instalación de su Sistema Telefónico 3CX

Prepare su Carpeta de Instalación

  • Genere una carpeta específica para su nuevo PBX (en este ejemplo, ~/3cx-proxmox/deployments/pbx01) y copie la plantilla de entorno en ella:

cd ~/3cx-proxmox

cp -r deployment-template/ deployments/pbx01

Nota: Si está realizando una restauración silenciosa, también debe copiar los archivos setupconfig.xml y 3cx-backup.zip en esta carpeta.

Configure su Archivo .ENV

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

Tenga en cuenta lo siguiente:

  • Establezca PBX_INSTALLATION_MODE en "manual" (valor predeterminado):
  • Opción 1: genere un archivo válido en ~/3cx-proxmox/deployments/pbx01/setupconfig.xml.
  • Opción 2: como alternativa, puede obtener un archivo setupconfig.xml ya preparado con una configuración mínima válida desde el Portal 3CX.
  • si está realizando una restauración, configure BACKUP_FILE con el nombre del archivo de su copia de seguridad (dentro de ~/3cx-proxmox/deployments/pbx01).
  • establezca PBX_INSTALLATION_MODE en "asistente" para iniciar el sistema y acceder a la configuración de la interfaz de usuario web.
  • establezca el VMID en un identificador único disponible de máquina virtual de Proxmox.
  • puede consultar los ID de las máquinas virtuales actualmente en uso desde el shell de Proxmox con el comando qm list.
  • establezca los valores adecuados (aquí tiene algunas indicaciones: Requisitos de Hardware) para su instancia de 3CX en lo siguiente:
  • DISK_GB (predeterminado 40).
  • CORES (predeterminado 2).
  • SOCKETS (predeterminado 1).
  • MEMORY_MB (predeterminado 2048).
  • establezca su MAC_ADDRESS al valor que haya establecido en la etapa de requisitos previos anterior.
  • (opcional) establezca su VLAN_TAG (por defecto, vacío).
  • establezca las variables de la Versión 3CX que desee; para la última Versión 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.
  • (opcional) establezca las rutas de acceso a SSH_PUBLIC_KEY_FILE y SSH_PRIVATE_KEY_FILE si ha creado claves personalizadas para proteger las comunicaciones entre su host Proxmox y los sistemas invitados.

Puede obtener más información sobre la Instalación de 3CX y la Configuración de Aprovisionamiento mediante el archivo setupconfig.xml.

Estructura del Directorio del Proyecto

Así es como debería verse su estructura de directorios:

Ejecute el Script de Instalación

Ejecute el script principal, indicando la ruta al archivo de configuración específico mediante el parámetro --config (o -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%)

Supervise la Instalación

El script ofrece información en tiempo real en la terminal. De manera sistemática:

  • Descarga la imagen de Debian para la nube (si no está en la caché).
  • Incorpora dinámicamente sus scripts y variables en un fragmento único de Cloud-Init.
  • Aprovisiona los recursos de computación y la interfaz de red de la máquina virtual.
  • Inicia la máquina virtual y espera a que el Agente Invitado de QEMU informe la dirección IP asignada por 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...

Configuración Automática y Transferencia

Una vez detectada la dirección IP, el script limpia automáticamente el archivo known_hosts de Proxmox para evitar conflictos de SSH. A continuación, copia de forma segura el archivo de respaldo (si se ha proporcionado) y ejecuta el script de instalación 3cx-setup.sh de forma remota.

Una vez completado el proceso, aparecerá un mensaje de confirmación con el resumen de la máquina virtual.

Notas Post Instalación

Dependiendo del modo de instalación PBX_INSTALLATION_MODE seleccionado, los pasos finales variarán:

  • Modo Asistente: El script consultará la máquina virtual recién creada hasta que el asistente Web de 3CX responda. Una vez completado el proceso, acceda a http://<VM_IP>:5015 en su navegador para finalizar la configuración.
  • Modo Manual: El PBX se instalará de forma silenciosa utilizando el archivo setupconfig.xml insertado y, si se desea, restaurará los datos a partir del archivo de copia de seguridad proporcionado. No se requiere ninguna otra interacción con el asistente.

Nota: Los registros de instalación se encuentran en el directorio de configuración. Por ejemplo, ~/3cx-proxmox/deployments/pbx01/vm-300-deployment-notes.txt.

Obtenga su Archivo setupconfig.xml desde el Portal 3CX

Para obtener un archivo setupconfig.xml preconfigurado y básico directamente desde el Portal 3CX:

  • Inicie sesión en su cuenta del Portal 3CX.

Descargar archivo setupconfig.xml desde el Portal 3CX

  • Identifique su sistema deseado y haga clic en el enlace Instalar.

Opción On-Premise

  • Seleccione la opción On-Premise y haga clic en el botón Siguiente.

Longitud de dígitos de extensiones

  • Seleccione el número de dígitos para las extensiones de su sistema y haga clic en el botón Siguiente.

Preferencias regionales

  • Seleccione las preferencias regionales para su sistema y haga clic en el botón Siguiente.

Plataforma Linux

  • En la última página, seleccione la plataforma Linux.
  • Haga clic en el enlace Descargar para descargar el archivo SetupConfig.xml.
  • cambie el nombre del archivo SetupConfig.xml descargado a setupconfig.xml; los scripts de instalación distinguen entre mayúsculas y minúsculas.
  •  copie el archivo setupconfig.xml en su máquina Proxmox, en la ruta ~/3cx-proxmox/deployments/pbx01/setupconfig.xml.

Última Actualización

Este documento se actualizó por última vez el 26 de Mayo de 2026

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