Apache Guacamole 部署指南：让你的 Homelab 远程桌面告别客户端

作者

发布于 Mooloco Blog · #Homelab #SelfHosted #Docker

项目简介

Apache Guacamole 是一个无客户端的远程桌面网关。它让你可以通过浏览器直接访问 RDP、VNC、SSH 和 Telnet 服务，不需要在本地安装任何远程桌面软件。

浏览器 ───→ Guacamole Web ───→ Guacd 代理 ───→ 你的服务器
  只需打开网页                 │
                       RDP → Windows VM
                       VNC → Linux 桌面
                       SSH → 终端

核心功能

功能说明
无客户端只需要浏览器，Chrome/Firefox/Edge 都行
多协议同时支持 RDP、VNC、SSH、Telnet、Kubernetes
会话录制可以录制所有操作，方便审计
双因素认证支持 TOTP 等二次验证
多用户权限细粒度的用户/用户组 + 连接权限管理
录音/录屏支持音频传输和屏幕录制
复制粘贴剪贴板在本地和远程之间互通

为什么在 Homelab 里需要它

过去你要管理家里这些机器：

  Win10 LTSC (192.168.1.39)     ← 要装 RDP 客户端
  iStoreOS 旁路由               ← 要 SSH 客户端
  gb-pve / ami-pve              ← 要 SSH 客户端

  → 每换一台设备就要装一遍客户端
  → 手机上管理特别麻烦

有了 Guacamole：

  浏览器打开 http://192.168.1.x:8090/guacamole
  一个页面管所有机器
  Windows/Mac/Linux/手机 都能用

部署方案

根据你的环境选择，这里给出两种常见场景。

场景一：内置 MySQL 容器（All-in-One）

适合没有现成数据库的新部署。

docker-compose.yml

version: "3.8"

services:
  mysql:
    image: mysql:8.0
    container_name: guacamole-mysql
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASS:-guacadmin}
      MYSQL_DATABASE: ${MYSQL_DATABASE:-guacamole_db}
      MYSQL_USER: ${MYSQL_USER:-guacamole}
      MYSQL_PASSWORD: ${MYSQL_PASS:-guacamole}
    volumes:
      - ./mysql-data:/var/lib/mysql
    restart: unless-stopped

  guacd:
    image: guacamole/guacd
    container_name: guacamole-guacd
    restart: unless-stopped

  guacamole:
    image: guacamole/guacamole
    container_name: guacamole-web
    depends_on:
      - guacd
      - mysql
    environment:
      GUACD_HOSTNAME: guacd
      MYSQL_HOSTNAME: mysql
      MYSQL_DATABASE: ${MYSQL_DATABASE:-guacamole_db}
      MYSQL_USER: ${MYSQL_USER:-guacamole}
      MYSQL_PASSWORD: ${MYSQL_PASS:-guacamole}
    ports:
      - "8080:8080"
    restart: unless-stopped

部署

mkdir -p /opt/guacamole && cd /opt/guacamole
# 创建 docker-compose.yml 后：
docker compose up -d mysql

# 初始化数据库
docker run --rm guacamole/guacamole \
  /opt/guacamole/bin/initdb.sh --mysql > ./initdb.sql
docker exec -i guacamole-mysql mysql -u root -pguacadmin guacamole_db < ./initdb.sql

docker compose up -d
数据库文件（下同）
initdb下载

场景二：使用外部数据库（推荐 Homelab 场景）

适合局域网内已有数据库服务器的情况（如 NAS、独立数据库容器等）。

docker-compose.yml

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

  guacamole:
    image: guacamole/guacamole:latest
    container_name: guacamole
    restart: unless-stopped
    depends_on:
      - guacd
    environment:
      GUACD_HOSTNAME: guacd
      GUACD_PORT: 4822

      MYSQL_ENABLED: "true"
      MYSQL_HOSTNAME: ${DB_HOST}
      MYSQL_PORT: ${DB_PORT:-3306}
      MYSQL_DATABASE: ${DB_NAME}
      MYSQL_USER: ${DB_USER}
      MYSQL_PASSWORD: ${DB_PASS}

      TZ: Asia/Shanghai

    ports:
      - "8090:8080"
    networks:
      - guac-net

networks:
  guac-net:
    driver: bridge

.env 文件

DB_HOST=192.168.1.x
DB_PORT=3306
DB_NAME=guacamole_db
DB_USER=guacamole
DB_PASS=your_password_here

初始化数据库（只需一次）

docker run --rm guacamole/guacamole \
  /opt/guacamole/bin/initdb.sh --mysql > ./initdb.sql
mysql -h ${DB_HOST} -u ${DB_USER} -p ${DB_NAME} < ./initdb.sql
初始化数据库文件
initdb下载

启动

docker compose up -d

访问与使用

地址: http://你的服务器IP:8090/guacamole
默认账号: guacadmin
默认密码: guacadmin

登录后进入管理界面：

  1. 点击右上角用户头像 → 设置
  2. 连接 → 新建连接
  3. 填写：
    • 名称：Win10 LTSC
    • 协议：RDP（或 VNC / SSH）
    • 主机名：192.168.1.39
    • 端口：3389（RDP 默认）
    • 认证：填写目标机器的用户名密码
  4. 保存后点击连接，浏览器里直接出现远程桌面

优势小结

优势说明
🖥️ 跨平台任何有浏览器的设备都能管理
🔒 集中认证所有远程连接用 Guacamole 的账号统一管理
📦 轻量部署Docker 一条命令启动
🎥 审计回放所有操作可录制，谁做了什么一目了然
🔗 多网段通过 Guacamole 统一入口访问不同 VLAN 的设备

如果你也在自建 Homelab，这个工具值得一试。有问题欢迎留言交流。

发表评论