Instalar Apache Guacamole en un VPS (2026): Docker, puerta de enlace de escritorio remoto, HTTPS y configuración de seguridad

Apache Guacamole es una puerta de enlace de escritorio remoto sin cliente. El navegador se comunica con la aplicación web de Guacamole, que entrega la conexión al proceso proxy guacd, y guacd se conecta al destino real RDP, VNC, SSH, Telnet o Kubernetes.

La estructura de despliegue de este artículo es la siguiente:

浏览器
  -> HTTPS 443
  -> Caddy
  -> Guacamole Web / Tomcat 8080
  -> guacd 4822（仅 Docker 内网）
  -> RDP 3389 / SSH 22 / VNC 5900 等目标主机

Guacamole Web
  -> MariaDB 3306（仅 Docker 内网）

El límite de seguridad más importante aquí es: Internet solo ve el 80/443 de Caddy, el 8080 de Guacamole se enlaza solo a la dirección de loopback del VPS, y ni guacd:4822 ni la base de datos 3306 se mapean a la red pública del host.

Apache advierte oficialmente que guacd es un proxy pasivo y no realiza ninguna autenticación. Si 4822 se expone a una red no confiable, los atacantes podrían usarlo como trampolín hacia otros sistemas. Por eso este artículo no configura ports para guacd.

Si solo tienes dos o tres dispositivos propios, entrar primero en la red privada mediante una VPN WireGuard suele ser más sencillo. Guacamole encaja mejor en escenarios que necesitan acceso por navegador, asignación centralizada de conexiones, varias cuentas de usuario, historial de conexiones o gestión mixta de RDP/VNC/SSH.

Guacamole tampoco sustituye la seguridad del host de destino: Windows sigue necesitando parches, NLA y contraseñas fuertes; Linux debe seguir limitando los usuarios SSH y los privilegios de sudo; VNC sigue necesitando autenticación fiable. La puerta de enlace solo cambia la ruta de acceso; no corrige vulnerabilidades de los servicios de backend.

Guacamole en sí no almacena un sistema de escritorio completo, pero necesita transcodificar actualizaciones de pantalla y gestionar audio, portapapeles, transferencia de archivos y varias conexiones simultáneas. La latencia y el ancho de banda suelen afectar más directamente a la experiencia de uso que la capacidad de disco.

La resolución de pantalla, la frecuencia de refresco, el contenido de vídeo, el audio y la calidad de la red cambian el tráfico real. Navegar por una interfaz de administración estática puede requerir poco ancho de banda, mientras que reproducir vídeo o desplazarse con frecuencia lo aumenta mucho. No compres según un "X Mbps fijos por usuario"; primero haz pruebas de carga con cargas de trabajo reales y luego monitoriza los picos y el tráfico mensual.

El centro de datos debe estar cerca tanto de los usuarios como de los hosts de destino. La ruta de acceso es "usuario → VPS de Guacamole → host de destino", y la latencia alta en cualquier tramo se suma. Si los usuarios están en Asia y el host de destino en Europa, colocar la puerta de enlace en América normalmente no mejorará la experiencia.

Este artículo usa:

El 3389, 22 o 5900 del host de destino tampoco necesita estar abierto a toda Internet. Si el destino es otro servidor público, el firewall debe permitir solo la IP fija del VPS de Guacamole; si el destino está en una intranet doméstica o de oficina, primero establece WireGuard, una VPN de sitio a sitio u otro túnel controlado.

Actualizar Ubuntu:

sudo apt update
sudo apt upgrade -y
sudo apt install -y ca-certificates curl gnupg openssl ufw

Instala Docker Engine y el plugin Compose desde el repositorio oficial de Docker y verifica:

docker version
docker compose version
sudo systemctl enable --now docker
sudo systemctl status docker --no-pager

Para la rotación de logs, los límites de recursos, la reversión y la gestión de secretos en producción, puedes revisar la lista de verificación de configuración de producción de VPS Docker Compose.

Crear el directorio del proyecto:

sudo install -d -m 750 /opt/guacamole
sudo chown "$(id -u):$(id -g)" /opt/guacamole
cd /opt/guacamole

A fecha de agosto de 2026, la última versión estable de Apache Guacamole es 1.6.0. Este artículo fija explícitamente las versiones de las imágenes web y guacd para evitar que latest cambie de versión sin que nadie lo note. Antes de desplegar, conviene consultar los Apache Guacamole Release Archives para confirmar si ya existe una versión más reciente.

Generar el SQL de inicialización de MariaDB con el script integrado en la imagen oficial:

docker run --rm guacamole/guacamole:1.6.0 \
  /opt/guacamole/bin/initdb.sh --mysql > initdb.sql

test -s initdb.sql
chmod 600 initdb.sql
head -n 5 initdb.sql

Guacamole no crea automáticamente las tablas de autenticación JDBC; primero hay que inicializar la base de datos. Este archivo SQL se ejecuta la primera vez que el directorio de datos de MariaDB está vacío; si más adelante reutilizas un volumen de base de datos existente, el script de entrada de Docker no lo ejecutará de nuevo.

Crear /opt/guacamole/.env con un valor aleatorio:

cd /opt/guacamole
umask 077

GUAC_DB_PASSWORD=$(openssl rand -hex 32)
GUAC_ROOT_PASSWORD=$(openssl rand -hex 32)

{
  printf 'MARIADB_DATABASE=guacamole_db\n'
  printf 'MARIADB_USER=guacamole_user\n'
  printf 'MARIADB_PASSWORD=%s\n' "$GUAC_DB_PASSWORD"
  printf 'MARIADB_ROOT_PASSWORD=%s\n' "$GUAC_ROOT_PASSWORD"
} > .env

unset GUAC_DB_PASSWORD GUAC_ROOT_PASSWORD
chmod 600 .env

Confirma que el nombre de la variable existe, pero no imprimas el valor de la contraseña en una terminal compartida ni en una captura de pantalla:

cut -d= -f1 .env

.env, las copias de seguridad de la base de datos y las configuraciones de conexión de Guacamole pueden contener información sensible y no deben subirse a un repositorio Git público.

Crear /opt/guacamole/compose.yaml:

services:
  mariadb:
    image: mariadb:11.4
    container_name: guacamole-mariadb
    environment:
      MARIADB_ROOT_PASSWORD: "${MARIADB_ROOT_PASSWORD}"
      MARIADB_DATABASE: "${MARIADB_DATABASE}"
      MARIADB_USER: "${MARIADB_USER}"
      MARIADB_PASSWORD: "${MARIADB_PASSWORD}"
    volumes:
      - mariadb-data:/var/lib/mysql
      - ./initdb.sql:/docker-entrypoint-initdb.d/001-guacamole.sql:ro
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 12
      start_period: 30s
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    logging:
      driver: json-file
      options:
        max-size: 10m
        max-file: "3"

  guacd:
    image: guacamole/guacd:1.6.0
    container_name: guacamole-guacd
    environment:
      LOG_LEVEL: info
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    logging:
      driver: json-file
      options:
        max-size: 10m
        max-file: "3"

  guacamole:
    image: guacamole/guacamole:1.6.0
    container_name: guacamole-web
    depends_on:
      mariadb:
        condition: service_healthy
      guacd:
        condition: service_started
    environment:
      GUACD_HOSTNAME: guacd
      MYSQL_ENABLED: "true"
      MYSQL_HOSTNAME: mariadb
      MYSQL_DATABASE: "${MARIADB_DATABASE}"
      MYSQL_USERNAME: "${MARIADB_USER}"
      MYSQL_PASSWORD: "${MARIADB_PASSWORD}"
      WEBAPP_CONTEXT: ROOT
      REMOTE_IP_VALVE_ENABLED: "true"
      TOTP_ENABLED: "true"
      BAN_ENABLED: "true"
    ports:
      - "127.0.0.1:8080:8080"
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    logging:
      driver: json-file
      options:
        max-size: 10m
        max-file: "3"

volumes:
  mariadb-data:

Esta configuración aplica deliberadamente las siguientes restricciones:

1. Guacamole Web se mapea solo a 127.0.0.1:8080;
2. guacd no tiene mapeo de puertos al host y solo es accesible desde la aplicación web en la red de Compose;
3. MariaDB no tiene puerto público y solo persiste en un volumen con nombre;
4. El SQL de inicialización de la base de datos se monta en modo de solo lectura;
5. Se configura rotación de logs para web, guacd y la base de datos;
6. Guacamole activa TOTP y conserva el bloqueo por fallos de inicio de sesión que la imagen Docker 1.6.0 proporciona por defecto;
7. RemoteIpValve permite que la aplicación detrás del proxy inverso reconozca la IP real del cliente; de lo contrario, todos los inicios de sesión fallidos podrían parecer provenientes de Caddy.

WEBAPP_CONTEXT=ROOT coloca la página de inicio de sesión directamente en / en lugar de la predeterminada /guacamole/. Si eliminas esta variable, tanto Caddy como la URL de acceso deben cambiarse a la subruta correspondiente; no puedes cambiar solo un lado.

Primero deja que Compose expanda y valide la configuración:

cd /opt/guacamole
docker compose config > /tmp/guacamole-compose-resolved.yaml
docker compose pull
docker compose up -d
docker compose ps

Revisar los logs de arranque:

docker compose logs --tail=200 mariadb
docker compose logs --tail=200 guacd
docker compose logs --tail=200 guacamole

Comprobar las tablas de la base de datos:

docker compose exec mariadb sh -c \
  'mariadb -u"$MARIADB_USER" -p"$MARIADB_PASSWORD" "$MARIADB_DATABASE" -e "SHOW TABLES;"'

Deberías ver tablas como guacamole_user y guacamole_connection. Si las tablas están vacías, comprueba primero si MariaDB ya había creado un volumen de datos antes de generar initdb.sql. El script de inicialización solo se ejecuta en el primer arranque con un directorio de datos vacío; no intentes tener suerte reiniciando repetidamente.

Probar la web en el propio VPS:

curl -I http://127.0.0.1:8080
sudo ss -lntp | grep ':8080'

En este punto, que http://VPS-IP:8080 no sea accesible desde Internet es el resultado correcto.

Accede temporalmente desde tu ordenador personal mediante un túnel SSH:

ssh -L 8080:127.0.0.1:8080 [email protected]

203.0.113.10 es una dirección de ejemplo de la documentación y debe sustituirse por la IP pública real del VPS. Mantén la sesión SSH abierta y abre en el navegador:

http://127.0.0.1:8080

El SQL de inicialización oficial de la base de datos crea un administrador predeterminado:

用户名：guacadmin
密码：guacadmin

Estas credenciales predeterminadas son información pública y solo sirven para el primer inicio de sesión. Inmediatamente después de entrar en el sistema:

1. Cambia la contraseña de guacadmin por una contraseña fuerte y aleatoria generada por un gestor de contraseñas;
2. Completa el registro de TOTP y guarda de forma segura el proceso de recuperación;
3. Crea una nueva cuenta de administrador para el uso diario;
4. Crea un usuario de prueba no administrador;
5. Tras verificar que la nueva cuenta puede iniciar sesión, deja de usar el administrador predeterminado en el día a día;
6. No concedas a los usuarios normales permisos para crear usuarios, modificar el sistema o gestionar todas las conexiones.

Si aún no has cambiado la contraseña predeterminada, no expongas el dominio HTTPS a toda Internet ni empieces a crear conexiones de backend.

Apunta el registro DNS A/AAAA de remote.example.com al VPS. El dominio de ejemplo debe sustituirse por tu dominio real.

Añade lo siguiente al Caddyfile:

remote.example.com {
    encode zstd gzip
    reverse_proxy 127.0.0.1:8080
}

Caddy gestiona automáticamente el proxy WebSocket que necesita Guacamole; normalmente no hace falta escribir manualmente las cabeceras Upgrade. Valida y recarga:

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
sudo systemctl status caddy --no-pager
sudo journalctl -u caddy -n 100 --no-pager

Abrir el puerto web:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp comment 'Caddy HTTP'
sudo ufw allow 443/tcp comment 'Caddy HTTPS'
sudo ufw enable
sudo ufw status numbered

No abras 8080, 4822 ni 3306. Para el proceso completo de instalación de Caddy, DNS y certificados automáticos, consulta la guía completa de Caddy como proxy inverso en un VPS.

Guacamole recomienda oficialmente terminar TLS en el proxy inverso. REMOTE_IP_VALVE_ENABLED=true hace que Tomcat use la dirección del cliente y la información de protocolo transmitidas por el proxy, lo cual es importante para el bloqueo de inicios de sesión, la auditoría y las restricciones basadas en la IP de origen.

Tras iniciar sesión en la interfaz de administración, crea Connections en los ajustes. Empieza con una cuenta de prueba de bajo privilegio y destinos que no sean de producción.

Protocol: SSH
Hostname: 10.20.0.10
Port: 22
Username: ops-test

Protocol: RDP
Hostname: 10.20.0.20
Port: 3389
Username: remote-user
Domain: 按实际环境填写
Security mode: NLA

Protocol: VNC
Hostname: 10.20.0.30
Port: 5900

nc -vz 10.20.0.10 22
nc -vz 10.20.0.20 3389
nc -vz 10.20.0.30 5900

No hagas administrador a todo el mundo ni dejes que todos los usuarios compartan la misma cuenta del sistema de destino.

Capas recomendadas:

• Administradores del sistema: solo responsables de la configuración y auditoría de Guacamole;
• Administradores de conexiones: gestionan conexiones concretas, no todos los usuarios del sistema;
• Usuarios normales: solo pueden usar las conexiones que se les asignan;
• Usuarios de solo lectura o demostración: desactiva el portapapeles, la transferencia de archivos y las capacidades de entrada que no necesiten;
• Usuarios temporales: establece una fecha de caducidad explícita y revoca el acceso al terminar la tarea.

Para conexiones sensibles, considera:

• No guardar contraseñas de destino de forma permanente en Guacamole; pedir que se introduzcan al iniciar sesión;
• Que cada usuario use una cuenta de destino independiente para facilitar la auditoría y la revocación;
• Desactivar el portapapeles, el mapeo de unidades, la impresión, el audio y la transferencia de archivos que no se necesiten;
• Colocar los entornos de producción, pruebas y clientes en grupos de conexión distintos;
• Restringir las horas y las subredes de origen desde las que los usuarios pueden iniciar sesión;
• Revisar periódicamente Active Sessions e History.

Los privilegios de administrador deben ser mínimos. Los administradores del sistema normalmente no se ven afectados por algunas restricciones de inicio de sesión, así que las restricciones por hora o por dirección de origen no pueden ser la única defensa de las cuentas de administrador.

La imagen Docker oficial de Guacamole 1.6.0 admite TOTP estándar mediante TOTP_ENABLED=true. Este artículo activa tanto la autenticación por base de datos como TOTP, por lo que los usuarios deben introducir un código de verificación dinámico después de la contraseña.

Antes de ponerlo en producción, prueba al menos:

• Que administradores y usuarios normales completen el registro TOTP;
• Que la hora del servidor sea precisa para que TOTP no falle continuamente por desfase de reloj;
• Que exista un proceso de recuperación controlado si se pierde el teléfono;
• Que la recuperación requiera verificación del administrador en lugar de desactivar todo el MFA;
• Que la IP del cliente transmitida por el proxy inverso sea correcta.

La imagen Docker de Guacamole 1.6.0 incluye por defecto una extensión de bloqueo por fallos de inicio de sesión. El umbral predeterminado oficial es de 5 fallos desde la misma fuente, con un bloqueo de 300 segundos. Reduce la frecuencia de adivinación de contraseñas en línea, pero no sustituye contraseñas fuertes, TOTP, restricciones de origen y monitorización de logs.

Ver los logs relacionados con inicios de sesión fallidos y bloqueos:

docker compose logs --since=1h guacamole | grep -i -E 'auth|fail|ban|invalid'

Si todas las solicitudes aparecen como 127.0.0.1 o la misma dirección Docker, primero corrige el reenvío de la IP del cliente a través del proxy inverso y luego configura políticas basadas en la dirección de origen.

Los usuarios, conexiones, permisos e historial de Guacamole están principalmente en la base de datos. Copiar solo compose.yaml no permite restaurar estos datos.

Crear una copia de seguridad:

cd /opt/guacamole
backup_stamp=$(date +%Y%m%d-%H%M%S)
sudo install -d -m 700 /var/backups/guacamole

docker compose exec -T mariadb sh -c \
  'mariadb-dump -uroot -p"$MARIADB_ROOT_PASSWORD" --single-transaction "$MARIADB_DATABASE"' \
  | gzip > "/var/backups/guacamole/database-${backup_stamp}.sql.gz"

sudo tar -C /opt/guacamole -czf \
  "/var/backups/guacamole/config-${backup_stamp}.tar.gz" \
  compose.yaml .env initdb.sql

sudo chmod 600 /var/backups/guacamole/*

Verificar la copia de seguridad:

gzip -t "/var/backups/guacamole/database-${backup_stamp}.sql.gz"
sudo tar -tzf "/var/backups/guacamole/config-${backup_stamp}.tar.gz"
ls -lh /var/backups/guacamole

Los archivos de copia de seguridad contienen hashes de contraseñas, información de conexiones y credenciales de la base de datos, por lo que deben transferirse cifrados y con acceso restringido. No dejes las copias solo en el mismo disco del VPS; para un simulacro completo de restauración, consulta el tutorial de simulacro de copia de seguridad y restauración en VPS.

Consulta las Guacamole Release Notes antes de actualizar. El esquema de la base de datos puede requerir ejecutar SQL de actualización en orden de versión; no basta con cambiar la etiqueta de la imagen y arrancar.

Registrar el estado actual:

cd /opt/guacamole
docker compose images
docker image inspect guacamole/guacamole:1.6.0 \
  --format '{{index .RepoDigests 0}}'
docker image inspect guacamole/guacd:1.6.0 \
  --format '{{index .RepoDigests 0}}'
docker compose ps

Proceso de actualización:

1. Elige una ventana de mantenimiento y avisa a los usuarios activos;
2. Detén las nuevas conexiones y confirma que las sesiones activas han terminado;
3. Haz copia de seguridad de MariaDB, .env, Compose y los archivos de inicialización;
4. Lee todas las notas de Schema Upgrade desde la versión actual hasta la versión objetivo;
5. Descarga las nuevas imágenes y verifica las versiones;
6. Ejecuta el SQL de actualización de la base de datos en el orden oficial;
7. Actualiza web y guacd a la misma versión;
8. Recrea los contenedores y prueba el inicio de sesión, TOTP, SSH, RDP, VNC y el historial de auditoría;
9. Conserva las imágenes antiguas y las copias de seguridad, y limpia solo tras confirmar la estabilidad.

Los componentes de Guacamole 1.x tienen cierta compatibilidad de protocolo, pero mantener web, guacd, extensiones y esquema de base de datos en la misma versión a largo plazo es más fácil de mantener. Las extensiones de terceros deben confirmar su compatibilidad de API por separado.

• Usa una versión estable de Guacamole actualmente soportada y versiones coincidentes de web y guacd;
• Usa autenticación por base de datos y no trates user-mapping.xml como una solución de producción pública;
• El guacadmin / guacadmin predeterminado se ha cambiado de inmediato;
• TOTP está activado tanto para administradores como para usuarios normales;
• REMOTE_IP_VALVE_ENABLED=true, y la auditoría puede ver la IP real del cliente;
• 8080 se enlaza solo a 127.0.0.1;
• 4822 y 3306 no tienen mapeos de puertos al host;
• HTTPS de Caddy funciona y HTTP redirige automáticamente a HTTPS;
• RDP, SSH y VNC de destino permiten el acceso solo desde el VPS de Guacamole o la subred VPN;
• Los usuarios normales no tienen permisos de administración del sistema ni de todas las conexiones;
• El portapapeles, la transferencia de archivos, la impresión y el mapeo de unidades que no se necesitan están desactivados;
• La base de datos, .env y las configuraciones de conexión tienen copias de seguridad cifradas;
• Se han probado la restauración de la base de datos, la recuperación de TOTP y la reversión de imágenes;
• Se monitorizan los inicios de sesión fallidos, las sesiones activas, la CPU, la memoria, el ancho de banda y el disco;
• Existe un proceso fijo para eliminar usuarios temporales, conexiones antiguas y permisos de personal que se marcha.

• Apache Guacamole 1.6.0 Release Notes
• Documentación de instalación de Apache Guacamole con Docker
• Documentación de autenticación de base de datos MariaDB / MySQL
• Guía de despliegue seguro de Guacamole
• Autenticación multifactor TOTP de Guacamole