# 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，运行：

```powershell
docker --version
docker-compose --version
```

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

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

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

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

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

4. 点击 **Apply & Restart**

## 第二步：部署 Guacamole

### 2.1 生成数据库初始化脚本

```powershell
# 创建 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. 启动服务

```powershell
cd guacamole
docker-compose up -d
```

### 3. 等待初始化完成

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

```powershell
# 检查服务状态
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** 保存

## 服务管理

```powershell
# 启动服务
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. 登录时提示"此操作无法完成"

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

```powershell
# 删除并重建
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，添加：

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

### 3. 远程桌面连接失败

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

### 4. 修改端口

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

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

## 安全建议

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