serverRoom/guacamole/README.md

Apache Guacamole 搭建指南

Apache Guacamole 是一个无客户端的远程桌面网关，支持 RDP、VNC、SSH 等协议，可以通过浏览器访问远程桌面。

前置要求

• Windows 10/11 专业版或企业版（需要 Hyper-V 支持）
• 网络能够访问 Docker Hub（或配置镜像加速器）

第一步：安装 Docker Desktop

1.1 下载 Docker Desktop

访问官网下载：https://www.docker.com/products/docker-desktop/

或直接下载 Windows 版本：https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe

1.2 安装步骤

1. 双击运行 Docker Desktop Installer.exe
2. 勾选 Use WSL 2 instead of Hyper-V（推荐）
3. 点击 Ok 开始安装
4. 安装完成后点击 Close and restart 重启电脑

1.3 首次启动配置

1. 重启后 Docker Desktop 会自动启动
2. 接受服务条款
3. 可以跳过登录（点击 Skip）
4. 等待 Docker Engine 启动完成（右下角托盘图标变绿）

1.4 验证安装

打开 PowerShell，运行：

docker --version
docker-compose --version

如果显示版本号，说明安装成功。

1.5 配置镜像加速器（国内用户推荐）

如果拉取镜像速度慢，配置镜像加速器：

1. 点击 Docker Desktop 右上角齿轮图标 → Settings
2. 选择 Docker Engine
3. 在 JSON 配置中添加：

{
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker.xuanyuan.me"
  ]
}

4. 点击 Apply & Restart

第二步：部署 Guacamole

2.1 生成数据库初始化脚本

# 创建 init 目录
mkdir guacamole\init

# 生成 MySQL 初始化脚本
docker run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --mysql | Out-File -Encoding utf8 guacamole\init\initdb.sql

2. 启动服务

cd guacamole
docker-compose up -d

3. 等待初始化完成

首次启动需要等待约 30 秒让 MySQL 完成初始化。

# 检查服务状态
docker-compose ps

# 查看日志（可选）
docker logs guacamole-db
docker logs guacamole

4. 访问 Guacamole

打开浏览器访问：http://localhost:8080/guacamole/

默认登录账号：

• 用户名：guacadmin
• 密码：guacadmin

⚠️ 首次登录后请立即修改默认密码！

添加远程连接

1. 登录后点击右上角用户名 → Settings
2. 选择 Connections 标签
3. 点击 New Connection
4. 填写连接信息：
   • Name: 连接名称（如：机房电脑01）
   • Protocol: RDP
   • Hostname: 目标电脑 IP 地址
   • Port: 3389
   • Username: Windows 用户名
   • Password: Windows 密码
5. 点击 Save 保存

服务管理

# 启动服务
docker-compose up -d

# 停止服务
docker-compose down

# 重启服务
docker-compose restart

# 查看日志
docker-compose logs -f

# 完全删除（包括数据）
docker-compose down -v

配置说明

docker-compose.yml 结构

服务	说明	端口
guacd	Guacamole 守护进程，处理远程连接	4822（内部）
guacamole-db	MySQL 数据库，存储用户和连接配置	3306（内部）
guacamole	Web 应用，提供浏览器界面	8080

数据库配置

配置项	值
数据库名	guacamole_db
用户名	guacamole_user
密码	guacamole_pwd
Root 密码	guacamole_root_pwd

生产环境请修改这些默认密码！

常见问题

1. 登录时提示"此操作无法完成"

数据库表未正确初始化。解决方法：

# 删除并重建
docker-compose down -v

# 重新生成初始化脚本（注意编码）
docker run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --mysql | Out-File -Encoding utf8 guacamole\init\initdb.sql

# 重新启动
docker-compose up -d

2. 无法拉取镜像

配置 Docker 镜像加速器：

Docker Desktop → Settings → Docker Engine，添加：

{
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker.xuanyuan.me"
  ]
}

3. 远程桌面连接失败

检查：

• 目标电脑是否开启了远程桌面
• 防火墙是否允许 3389 端口
• 用户名密码是否正确
• 目标电脑是否在同一网络

4. 修改端口

编辑 docker-compose.yml，修改 guacamole 服务的端口映射：

ports:
  - "9090:8080"  # 改为 9090 端口

安全建议

1. 修改默认管理员密码
2. 修改数据库默认密码
3. 生产环境使用 HTTPS（配置 Nginx 反向代理）
4. 限制访问 IP 范围