Apache Guacamole 的部署方法与原理说明。
这是一份面向工程实践的完整部署指南，包括原理、环境准备、部署方式（Docker与手动安装）、多用户访问配置、远程协议支持（RDP/VNC/SSH）以及公网访问设置。

---

🧠 一、Apache Guacamole 简介与工作原理

Apache Guacamole 是一个 无客户端的远程桌面网关（Remote Desktop Gateway），支持通过 网页浏览器直接访问 RDP、VNC、SSH 等远程主机，无需在客户端安装任何插件或软件。

它的核心由三部分组成：

组件	作用	部署位置
guacd	协议代理守护进程，负责与远程主机通信（VNC/RDP/SSH）	后端服务器
guacamole.war	Web应用（Tomcat），负责网页界面和身份验证	Web服务器
数据库（MySQL/PostgreSQL）	存储用户、连接配置、权限信息	可同机或远程部署

🧩 工作流程：

1. 用户访问 Web 界面（通过浏览器）。
2. Guacamole Server（guacd）根据数据库配置建立与目标主机的远程连接。
3. Web 界面通过 WebSocket 与 guacd 交互，实现远程桌面画面传输与输入事件中继。

---

⚙️ 二、系统环境准备

建议使用 Ubuntu 20.04+ 或 CentOS 7/8+，并确保系统满足以下条件：

软件	版本建议	说明
Java JDK	11+	运行 guacamole.war
Tomcat	9+	Web容器
MySQL/PostgreSQL	最新稳定版	用户与连接配置
Docker（推荐）	20+	一键部署方式
防火墙	已开放 8080、4822、22、3389、5900 端口	分别为Web、guacd、SSH、RDP、VNC端口

---

🚀 三、部署方式一：Docker 一键部署（推荐）

Docker 是最简洁、可移植性最强的部署方式。

1️⃣ 拉取镜像

docker pull guacamole/guacd
docker pull guacamole/guacamole
docker pull mysql:8.0

2️⃣ 启动 MySQL 数据库

docker run --name guac-mysql -e MYSQL_ROOT_PASSWORD=123456 \
  -e MYSQL_DATABASE=guacamole_db -e MYSQL_USER=guacuser -e MYSQL_PASSWORD=guacpass \
  -d mysql:8.0

3️⃣ 初始化数据库结构

下载 SQL 初始化文件：

docker run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --mysql > initdb.sql
docker cp initdb.sql guac-mysql:/initdb.sql
docker exec -it guac-mysql bash -c "mysql -u root -p123456 guacamole_db < /initdb.sql"

4️⃣ 启动 guacd

docker run --name guacd -d guacamole/guacd

5️⃣ 启动 guacamole Web 服务

docker run --name guacamole --link guacd:guacd --link guac-mysql:mysql \
  -e MYSQL_HOSTNAME=mysql -e MYSQL_PORT=3306 \
  -e MYSQL_DATABASE=guacamole_db -e MYSQL_USER=guacuser -e MYSQL_PASSWORD=guacpass \
  -e GUACD_HOSTNAME=guacd -e GUACD_PORT=4822 \
  -p 8080:8080 -d guacamole/guacamole

6️⃣ 访问 Web 页面

浏览器访问：

http://<你的服务器IP>:8080/guacamole/

默认账号：

用户名：admin
密码：guacadmin

---

🛠 四、部署方式二：手动安装部署（Linux）

1️⃣ 安装依赖

sudo apt update
sudo apt install -y build-essential libcairo2-dev libjpeg-turbo8-dev libpng-dev \
libtool-bin libossp-uuid-dev freerdp2-dev libvncserver-dev libssh2-1-dev \
libtelnet-dev libssl-dev libvorbis-dev libwebp-dev tomcat9

2️⃣ 安装 guacd

wget https://downloads.apache.org/guacamole/1.5.5/source/guacamole-server-1.5.5.tar.gz
tar -xzf guacamole-server-1.5.5.tar.gz
cd guacamole-server-1.5.5
./configure --with-init-dir=/etc/init.d
make
sudo make install
sudo ldconfig
sudo systemctl enable guacd
sudo systemctl start guacd

3️⃣ 部署 Web 应用

wget https://downloads.apache.org/guacamole/1.5.5/binary/guacamole-1.5.5.war -O /var/lib/tomcat9/webapps/guacamole.war

4️⃣ 配置数据库

安装 MySQL 并导入初始化 SQL 文件（步骤同上）。

编辑 /etc/guacamole/guacamole.properties：

guacd-hostname: localhost
guacd-port: 4822
mysql-hostname: localhost
mysql-port: 3306
mysql-database: guacamole_db
mysql-username: guacuser
mysql-password: guacpass

创建软链接：

ln -s /etc/guacamole /usr/share/tomcat9/.guacamole

重启服务：

sudo systemctl restart tomcat9
sudo systemctl restart guacd

---

🌐 五、公网访问配置

1. 防火墙放行 8080 端口

   sudo ufw allow 8080
   

2. 使用 Nginx 反向代理（推荐）

   server {
       listen 80;
       server_name yourdomain.com;
   
       location / {
           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_cookie_path /guacamole/ /;
       }
   }
   

3. 申请 HTTPS 证书（Let’s Encrypt）

   sudo certbot --nginx -d yourdomain.com
   

---

👥 六、多用户与权限管理

Guacamole 默认数据库中可配置：

• 用户（User）
• 连接（Connection）
• 权限（User Permission / Connection Permission）

在 Web 管理界面可直接配置：

• 为每个用户分配特定的远程主机访问权限；
• 支持 LDAP / CAS / OpenID 集成；
• 支持自定义主题与登录界面。

---

🧩 七、支持的远程协议与配置示例

协议	端口	说明
RDP	3389	Windows 远程桌面
VNC	5900	Linux 图形桌面
SSH	22	命令行远程
Telnet	23	简易终端

🖥️ 添加 Windows RDP 示例：
在 “Connections → New Connection”：

Name: Windows10
Protocol: RDP
Hostname: 192.168.1.100
Port: 3389
Username: Administrator
Password: 123456

---

🧱 八、原理总结

Apache Guacamole 的核心是：

• guacd：协议转发器；
• guacamole.war：Web UI + WebSocket 通信；
• MySQL：存储配置；
• Browser：通过 WebSocket 接收远程桌面图像流。

通信流程：

Browser ⇄ Tomcat(guacamole.war) ⇄ guacd ⇄ RDP/VNC/SSH Server

---

🧭 九、扩展与集成

Guacamole 还支持：

• REST API / JSON Web Token (JWT) 集成
• 与企业认证系统（LDAP、Active Directory）结合
• 多租户远程管理系统
• 与 MeshCentral、Guacamole Gateway、Nginx Proxy Manager 等协同部署

---