Как установить и настроить Apache Guacamole на VPS

MAATRIX

Если у вас несколько удалённых машин — Windows-сервер по RDP, старый Linux по VNC, десяток серверов по SSH — держать под каждую отдельный клиент неудобно, особенно когда подключаетесь с чужого компьютера или планшета. Apache Guacamole решает это одним движением: ставите шлюз на VPS, и дальше все подключения открываются прямо в браузере — без RDP-клиента, без VNC-viewer'а, без установки чего-либо на клиентскую машину. Ниже — рабочая установка через Docker Compose с нуля до готового к работе шлюза.

Что такое Guacamole и когда он нужен

Apache Guacamole — clientless remote desktop gateway: сервер, транслирующий протоколы RDP, VNC, SSH и Telnet в HTML5-канвас внутри браузера. Состоит из трёх частей:

• guacd — демон, который умеет говорить на языке RDP/VNC/SSH и превращать это в поток для веб-клиента;
• guacamole-client — Java-приложение (Tomcat), веб-интерфейс и REST API;
• база данных (MySQL/MariaDB или PostgreSQL) — хранит пользователей, подключения, права доступа.

Сценарии, где это оправдано: администрирование парка серверов из браузера без VPN-клиента на каждой машине; безопасный доступ подрядчиков к конкретным серверам без выдачи паролей и ключей напрямую; централизованный аудит сессий (Guacamole умеет писать видеозаписи RDP/VNC-сессий); доступ к внутренним ресурсам с ограниченного рабочего места, где нельзя ставить ПО.

Не путайте Guacamole с VPN — это не туннель на уровне сети, а прокси конкретных протоколов удалённого рабочего стола. Если нужен полный доступ к сети целиком — это другая задача, смежный подход описан в статье про RDP через WireGuard.

Для установки хватит бюджетного VPS: 1-2 vCPU и 2 ГБ RAM держат guacd, Tomcat и MySQL при десятке одновременных сессий. Если планируете запись видео сессий или много параллельных RDP-подключений в высоком разрешении — закладывайте 4 ГБ RAM и SSD с запасом.

Подготовка сервера

Понадобится чистый VPS на Ubuntu 24.04 с установленным Docker и Docker Compose. Если Docker ещё не стоит — сначала пройдите базовую установку, это отдельная процедура: установка Docker с нуля на Ubuntu 24.04.

Проверяем версии и создаём рабочую директорию:

docker --version
docker compose version

mkdir -p /opt/guacamole
cd /opt/guacamole

Сразу настройте firewall — Guacamole будет смотреть в интернет, и открывать наружу нужно только 443/80 (через reverse proxy), никогда не выставляйте порт Tomcat 8080 напрямую в мир. Если UFW ещё не настроен на сервере — сделайте это заранее: установка и настройка UFW на VPS.

ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable

Docker Compose: guacd, база и клиент

Официальный образ guacamole/guacamole не тянет за собой готовую схему БД — её нужно сгенерировать отдельно. Сначала создаём docker-compose.yml:

services:
  guacd:
    image: guacamole/guacd:1.5.5
    container_name: guacd
    restart: unless-stopped
    networks:
      - guac-net

  guac-db:
    image: mysql:8.4
    container_name: guac-db
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: "СМЕНИТЕ_МЕНЯ_root"
      MYSQL_DATABASE: guacamole_db
      MYSQL_USER: guacamole_user
      MYSQL_PASSWORD: "СМЕНИТЕ_МЕНЯ_user"
    volumes:
      - ./mysql-data:/var/lib/mysql
      - ./init:/docker-entrypoint-initdb.d
    networks:
      - guac-net

  guacamole:
    image: guacamole/guacamole:1.5.5
    container_name: guacamole
    restart: unless-stopped
    depends_on:
      - guacd
      - guac-db
    environment:
      GUACD_HOSTNAME: guacd
      MYSQL_HOSTNAME: guac-db
      MYSQL_DATABASE: guacamole_db
      MYSQL_USER: guacamole_user
      MYSQL_PASSWORD: "СМЕНИТЕ_МЕНЯ_user"
    ports:
      - "127.0.0.1:8080:8080"
    networks:
      - guac-net

networks:
  guac-net:
    driver: bridge

Обратите внимание на 127.0.0.1:8080:8080 — порт биндится только на localhost, наружу его открывать не нужно, доступ пойдёт через nginx с SSL. Пароли из примера обязательно замените на свои перед запуском — это не декоративная строка, а рабочий пароль root к MySQL-контейнеру.

Теперь генерируем SQL-схему для базы. Официальный образ guacamole умеет сделать это одной командой через временный контейнер:

mkdir -p init
docker run --rm guacamole/guacamole:1.5.5 /opt/guacamole/bin/initdb.sh --mysql > init/01-initdb.sql

Файл init/01-initdb.sql подхватится MySQL-контейнером автоматически при первом старте (папка /docker-entrypoint-initdb.d — стандартный механизм официального образа mysql). Дальше просто поднимаем стек:

docker compose up -d
docker compose ps
docker compose logs -f guacamole

Дайте Tomcat 30-60 секунд на прогрев при первом старте — в логах должна появиться строка о готовности деплоймента. Проверить изнутри сервера:

curl -I http://127.0.0.1:8080/guacamole/

Должен вернуться 200 OK (или 302 на страницу логина) — если получаете Connection refused, смотрите логи контейнера guacamole на предмет ошибок подключения к БД.

Nginx как reverse proxy с SSL

Внешний доступ организуем через nginx с Let's Encrypt — это стандартная и проверенная схема. Если у вас ещё нет nginx на сервере, разверните его как reverse proxy: nginx как reverse proxy на VPS, там разобран базовый конфиг подробно. Здесь — конфиг конкретно под Guacamole, с учётом того, что интерфейс активно использует WebSocket для передачи экрана:

server {
    listen 80;
    server_name remote.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name remote.example.com;

    ssl_certificate     /etc/letsencrypt/live/remote.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/remote.example.com/privkey.pem;

    location /guacamole/ {
        proxy_pass http://127.0.0.1:8080/guacamole/;
        proxy_buffering off;

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $http_connection;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_cookie_path /guacamole/ /;
        access_log off;
    }
}

Ключевой момент — Upgrade/Connection заголовки и proxy_http_version 1.1: без них WebSocket-туннель не поднимется, и вы увидите бесконечную загрузку экрана после логина при живом бэкенде. proxy_buffering off убирает лишнюю задержку в передаче кадров экрана.

Для выпуска сертификата используйте certbot — если ещё не определились с инструментом для SSL, сравнение вариантов есть здесь: certbot или acme.sh — что выбрать для сервера.

apt install -y certbot python3-certbot-nginx
certbot --nginx -d remote.example.com
nginx -t && systemctl reload nginx

После этого шлюз доступен по https://remote.example.com/guacamole/.

Первый вход и настройка учётных данных

По умолчанию в свежесозданной БД есть один администратор: логин guacadmin, пароль guacadmin. Первым делом после входа смените пароль (Settings → Users → guacadmin) на длинный сгенерированный, при желании создайте нового администратора и заблокируйте guacadmin — дефолтные креды не меняют почти никогда, и это первое, что перебирают боты на публично торчащих инсталляциях.

Дальше заведите отдельных пользователей под реальные задачи: администратор — с полным доступом, остальные — только с нужными подключениями через Settings → Users → New User, вкладка Permissions. Так подрядчик или коллега получает доступ ровно к тому серверу, к которому должен.

Настройка подключений: RDP, VNC, SSH

Подключения создаются в Settings → Connections → New Connection. Для каждого протокола — свой набор параметров.

RDP (доступ к Windows):

Protocol: RDP
Hostname: 192.168.1.50
Port: 3389
Username: administrator
Password: (пароль)
Security mode: NLA
Ignore server certificate: включить (для самоподписанных сертификатов Windows)

Для многопользовательских Windows-серверов с RDP заранее разберитесь с лицензированием: Windows Server: несколько пользователей RDP и лицензирование.

VNC (доступ к Linux с графическим окружением):

Protocol: VNC
Hostname: 192.168.1.60
Port: 5900
Password: (пароль VNC-сервера)

SSH (текстовый доступ, работает как веб-терминал):

Protocol: SSH
Hostname: 192.168.1.70
Port: 22
Username: deploy
Private key: (вставить содержимое ключа, если аутентификация по ключу)

Полезная функция для всех трёх протоколов — запись сессий: в разделе Screen Recording укажите путь внутри контейнера guacd (например GUAC_ROOT/recordings), и Guacamole сохранит видео каждой сессии — удобно для аудита, кто и что делал на проде. Если серверов много, группируйте подключения через Connection Groups — это упрощает выдачу прав пачками, а не по одному подключению на пользователя.

Обслуживание и безопасность

Обновление — это смена тега образа и пересоздание контейнеров:

cd /opt/guacamole
docker compose pull
docker compose up -d

Перед major-обновлением (например 1.5.x → 1.6.x) сверьтесь с changelog проекта — иногда меняется схема БД и нужен дополнительный SQL-патч поверх существующей базы. Простое up -d схему автоматически не мигрирует.

Бэкап — дамп MySQL плюс папка с volume, храните вне сервера:

docker exec guac-db mysqldump -u root -p"ПАРОЛЬ_ROOT" guacamole_db > guac-backup-$(date +%F).sql
tar czf guac-volume-backup-$(date +%F).tar.gz mysql-data/

При странностях с подключением смотрите docker compose logs guacd и docker compose logs guacamole. Чаще всего "чёрный экран после логина" — это неверный Security mode для RDP (попробуйте Any вместо NLA, если на Windows не включён Network Level Authentication) либо файрвол на целевой машине, блокирующий порт со стороны guacd-контейнера.

Guacamole открывает браузерный доступ к внутренней инфраструктуре, так что базовая защита обязательна:

• Fail2ban против брутфорса логина — форма входа открыта в интернет, и её будут перебирать. Настройте fail2ban на логи неудачных попыток: установка и настройка fail2ban на VPS.
• Двухфакторная аутентификация — расширение guacamole-auth-totp добавляет коды из Google Authenticator и аналогов поверх пароля, ставится как отдельный .jar в GUAC_HOME/extensions/.
• Изоляция сети — MySQL и guacd только во внутренней docker-сети без проброса портов наружу, в мир смотрит только nginx.
• Docker-хардening в целом — если сервис не первый на сервере, посмотрите общие практики: безопасность Docker: лучшие практики.

Если даёте доступ подрядчикам — не расшаривайте один общий аккаунт, заводите каждому свою учётку с ограниченным набором Connections. Это и безопаснее, и даёт понятный аудит-трейл.

Частые вопросы