Apache Guacamole 入门指南

Apache Guacamole 入门指南：一个浏览器搞定所有远程桌面

本文是面向新手的 Apache Guacamole 入门教程，涵盖项目介绍、核心架构、Docker 部署、日常使用与常见问题排查。全文以 1.5.x / 1.6.x 系列版本为例。

一、Guacamole 是什么

Apache Guacamole 是 Apache 基金会旗下的开源无客户端远程桌面网关（clientless remote desktop gateway）。一句话概括它的核心卖点：

你只需要一个浏览器，就能访问 RDP、VNC、SSH、Telnet 等各种远程桌面和终端，不需要安装任何客户端软件或浏览器插件。

它能干什么

场景	说明
远程办公	在任意设备（电脑 / 平板 / 手机）的浏览器里连回公司内网电脑
运维入口	给运维人员提供一个统一的 Web 入口，集中管理所有 SSH / RDP 资源
堡垒机雏形	配合用户权限、会话审计与录制，实现轻量级的访问管控
云桌面接入	为客户机 / 教学机 / 实验环境提供即开即用的远程访问页面

主要特性

无客户端：基于 HTML5，浏览器打开即用，零插件、零安装
多协议支持：VNC、RDP、SSH、Telnet、Kubernetes（容器终端）等
完全开源：Apache License 2.0，可自由用于商业环境
可扩展认证：支持数据库（MySQL / PostgreSQL）、LDAP、OpenID SSO、TOTP 双因素等
审计能力：支持会话录制（可回放）、操作日志
文件传输：RDP 驱动器重定向、SSH/VNC 走 SFTP

二、核心架构：它是如何工作的

Guacamole 主要由两个组件构成，理解它们是理解整个项目的关键：

复制代码

                  ┌──────────────────────────────────────────────┐
                  │              远程资源（内网机器）               │
                  │  ┌─────────┐   ┌─────────┐   ┌────────────┐  │
                  │  │ Windows │   │  Linux  │   │ VNC 服务器  │  │
                  │  │ RDP:3389│   │ SSH:22  │   │ VNC:5900   │  │
                  │  └────┬────┘   └────┬────┘   └─────┬──────┘  │
                  └───────┼─────────────┼───────────────┼─────────┘
                          │ RDP         │ SSH           │ VNC
                  ┌───────┴─────────────┴───────────────┴─────────┐
                  │     guacamole-server（guacd，C 语言守护进程）    │
                  │        负责与目标机器通信、翻译协议（端口 4822）    │
                  └──────────────────────┬────────────────────────┘
                                         │ Guacamole 私有绘图协议
                  ┌──────────────────────┴────────────────────────┐
                  │  guacamole-client（Java Web 应用，跑在 Tomcat）  │
                  │     认证授权 / 连接管理 / 提供 Web 界面（8080）    │
                  └──────────────────────┬────────────────────────┘
                                         │ WebSocket（回退 HTTP 轮询）
                                    ┌────┴────┐
                                    │  浏览器  │
                                    │ (HTML5) │
                                    └─────────┘

guacamole-server（guacd）：C 语言编写的守护进程。它主动去连接目标机器（RDP/SSH/VNC......），把远端画面"翻译"成 Guacamole 自有的绘图指令流；同时把浏览器的键盘鼠标事件反向传给远端。
guacamole-client：Java 编写的 Web 应用（WAR 包），提供登录页面、连接管理、用户权限等功能，通过 WebSocket 与浏览器交互，通过 Guacamole 协议（默认 TCP 4822）与 guacd 通信。
数据流向：浏览器 ←WebSocket→ guacamole-client ←4822→ guacd ←RDP/SSH/VNC→ 目标机器。

注意：guacd 必须能直接访问到目标机器，它部署在哪、网络是否可达，直接决定连接是否成功。

三、快速体验：5 分钟跑起来

最快的方式是 Docker。先跑两个容器：

bash 复制代码

# 1. 启动 guacd（协议翻译层）
docker run --name guacd -d guacamole/guacd

# 2. 启动 guacamole Web 应用，映射 8080 端口
docker run --name guacamole -d -p 8080:8080 --link guacd:guacd guacamole/guacamole

浏览器访问：

复制代码

http://服务器IP:8080/guacamole

默认账号 / 密码：guacadmin / guacadmin（登录后请立即修改密码！）。

此时还没有配置任何数据库，适合先看看界面长什么样。真实使用建议按下一节部署带数据库的完整方案。

四、生产部署：Docker Compose + MySQL（推荐）

单机玩玩可以用 XML 文件存用户和连接，但正式环境强烈建议用数据库存储------方便管理用户、连接、权限，也方便后续扩展双因素认证等插件。

4.1 目录结构与 docker-compose.yml

新建一个目录，例如 ~/guacamole，在其中创建 docker-compose.yml：

yaml 复制代码

services:
  mysql:
    image: mysql:8.0
    container_name: guac-mysql
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: ChangeMe_RootPwd
      MYSQL_DATABASE: guacamole_db
      MYSQL_USER: guacamole_user
      MYSQL_PASSWORD: ChangeMe_UserPwd
    volumes:
      - ./mysql-data:/var/lib/mysql

  guacd:
    image: guacamole/guacd:1.5.5
    container_name: guacd
    restart: always
    volumes:
      - ./drive:/drive      # RDP 文件传输目录
      - ./record:/record    # 会话录制目录

  guacamole:
    image: guacamole/guacamole:1.5.5
    container_name: guacamole
    restart: always
    ports:
      - "8080:8080"
    environment:
      GUACD_HOSTNAME: guacd
      DATABASE_DRIVER: mysql
      DATABASE_HOSTNAME: mysql
      DATABASE_PORT: 3306
      DATABASE_DATABASE: guacamole_db
      DATABASE_USER: guacamole_user
      DATABASE_PASSWORD: ChangeMe_UserPwd
    depends_on:
      - mysql
      - guacd

密码请自行替换，不要照抄示例。镜像版本号可按需换成最新版。

4.2 初始化数据库（关键步骤）

Guacamole 首次启动前，需要先导入数据库表结构，否则登录会失败。

第一步：生成初始化 SQL

bash 复制代码

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

第二步：导入到 MySQL

bash 复制代码

docker exec -i guac-mysql mysql -uroot -pChangeMe_RootPwd guacamole_db < initdb.sql

4.3 启动并验证

bash 复制代码

docker compose up -d
docker compose logs -f guacamole   # 观察启动日志，确认没有报错

再次访问 http://服务器IP:8080/guacamole，用 guacadmin / guacadmin 登录即可。

五、基本使用

5.1 创建第一个连接

以连接一台 Windows（RDP）和一台 Linux（SSH）为例：

登录后，点击右上角用户名 → 设置（Settings）
切换到 连接（Connections） 标签页 → 点击 新建连接（New Connection）
按协议填写关键参数：

连接 Windows（RDP）：

参数	填写值
名称	`办公电脑-Win10`
协议	`RDP`
网络 → 主机名	`192.168.1.100`
网络 → 端口	`3389`
身份验证 → 用户名 / 密码	目标机器的账号（留空则连接时手动输入）

连接 Linux（SSH）：

参数	填写值
名称	`开发服务器-CentOS`
协议	`SSH`
网络 → 主机名	`192.168.1.200`
网络 → 端口	`22`
身份验证 → 用户名 / 密码	目标机器的账号

保存后回到首页（Home），点击连接卡片上的协议图标，即可在浏览器中打开远程会话。

常用协议默认端口速查：RDP 3389、SSH 22、VNC 5900、Telnet 23。

5.2 用户与权限管理

进入 设置 → 用户 → 新建用户，可以：

创建新账号并设置密码
勾选该用户可访问哪些连接（细粒度授权）
授予或收回管理员权限（"管理用户 / 连接 / 系统"等）

推荐做法：日常使用普通账号，guacadmin 只做管理，且第一时间改掉默认密码。

5.3 日常使用体验

在浏览器会话窗口里，顶部/侧边的菜单提供：

剪贴板：跨机器复制粘贴（RDP/SSH 均支持）
文件传输：见下节
全屏、缩放、触控板模式：手机 / 平板上也能比较顺畅地操作
Ctrl+Alt+Shift：会话快捷键（唤出菜单，避免快捷键被远端"吃掉"）

六、进阶功能

6.1 文件传输

RDP（驱动器重定向）：

在连接参数的 设备重定向 中：

勾选"启用驱动器重定向"
驱动器路径填 /drive（对应 docker-compose 里挂载的 ./drive:/drive）

会话中会出现一个映射磁盘，直接在远端与本地磁盘间复制文件。

SSH / VNC（SFTP）：

在连接参数的 SFTP 中启用，并填写 SFTP 服务器地址、账号（通常与 SSH 相同）。会话侧边栏会出现文件浏览器，可上传下载。

6.2 会话录制（审计）

在连接参数的 屏幕（Display） 中：

录制路径填 /record
勾选"自动创建录制路径"

会话结束后，录制文件（.guv 格式）会落在宿主机 ./record 目录。可用官方工具 guacenc 转成 MP4 归档回放：

bash 复制代码

guacenc /record/xxxx.guv   # 生成同名 .m4v/mp4 视频

6.3 TOTP 双因素认证

Guacamole 支持通过扩展插件实现 Google Authenticator 式的动态口令：

从官网 Releases 下载 guacamole-auth-totp-1.x.x.jar
放入 GUACAMOLE_HOME/extensions（Docker 中通常把宿主机目录挂载到 /guacamole/extensions）
重启 guacamole 容器
用户下次登录时会引导绑定验证器 App，之后登录需输入动态验证码

同样的方式还可以对接 LDAP（域账号） 、OpenID Connect（单点登录） 等，思路一致：下载对应扩展 jar → 放入 extensions → 配置环境变量 → 重启。

6.4 Nginx 反向代理 + HTTPS

生产环境建议挂在 Nginx 后面并配 HTTPS。WebSocket 透传是关键：

nginx 复制代码

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;
    access_log         off;
}

配置好后即可通过 https://your-domain/guacamole 访问。

七、常见问题排查

现象	常见原因与解决
登录报"内部错误"，或连接时报网关错误	guacd 没起来或网络不通：检查 `GUACD_HOSTNAME` 配置、容器间网络、guacd 4822 端口
RDP 连接失败 / 黑屏后断开	目标机未开启远程桌面、3389 被防火墙拦截、或 NLA 协商失败（连接参数"安全模式"改为 `any`，或在 Windows 侧调整 NLA 设置）
SSH 终端中文乱码	连接参数 → 终端 → 显示中把字体改为中文字体（如 `Noto Sans Mono CJK SC`），并确认目标机 locale 为 UTF-8
画面卡顿 / 模糊	降低连接分辨率、VNC 调低色彩深度；确认 WebSocket 正常（否则退化为轮询会明显变慢）
数据库方式无法登录	检查是否已导入 initdb 表结构；查看 `docker compose logs guacamole` 中数据库连接报错
忘记 guacadmin 密码	用其他管理员账号重置；没有可用账号时参考官方文档通过数据库重置密码字段

排错通用思路：先看 guacamole 与 guacd 两个容器的日志，绝大多数问题都能从日志里找到直接原因：

bash 复制代码

docker logs guacamole
docker logs guacd

八、小结

Guacamole = 浏览器直连一切远程桌面：HTML5 前端 + Java Web 应用（guacamole-client）+ C 协议网关（guacd）
部署首选 Docker Compose + MySQL，记得先导入 initdb 表结构
核心操作就两件事：建连接 （协议 + 主机 + 端口 + 账号）、管用户（授权可访问的连接）
进阶按需开启：文件传输、会话录制、TOTP 双因素、LDAP/OIDC 对接
排错先看容器日志，重点确认 guacd 与目标机器之间的网络连通性

参考资源

官网：https://guacamole.apache.org/
官方手册（Guacamole User Guide）：https://guacamole.apache.org/doc/gug/
GitHub 仓库：https://github.com/apache/guacamole-server
Docker 镜像：https://hub.docker.com/r/guacamole/guacamole

如果这篇文章对你有帮助，欢迎点赞收藏；有问题欢迎评论区交流。