231 lines
5.2 KiB
Markdown
231 lines
5.2 KiB
Markdown
# 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 范围
|
||
|
||
## 文件传输功能
|
||
|
||
系统已启用 Guacamole 的驱动器重定向功能，可以在远程桌面中传输文件。
|
||
|
||
### 使用方法
|
||
|
||
1. 连接远程桌面后，打开 **文件资源管理器**
|
||
2. 在左侧导航栏找到 **网络位置** 或 **此电脑**
|
||
3. 会看到一个名为 **共享文件夹** 的网络驱动器
|
||
4. 将文件拖放到该驱动器即可上传，从该驱动器复制文件即可下载
|
||
|
||
### 注意事项
|
||
|
||
- 共享文件夹存储在 Docker 卷 `guacd-drive` 中
|
||
- 所有连接共享同一个文件夹，请注意文件管理
|
||
- 大文件传输可能较慢，取决于网络带宽
|
||
- 如需为每个用户/连接分配独立文件夹，需要进一步配置
|