dushixiang/guacd

Apache Guacamole Server 增强镜像（中英文字体支持版）

一、镜像概述与主要用途

本镜像基于官方 Apache Guacamole Server 构建，在原生功能基础上优化了字体支持，新增常用中英文字体，并将容器默认运行用户调整为 root。主要用途为提供无客户端远程桌面网关服务，支持通过浏览器访问 VNC、RDP、SSH 等协议的远程桌面，特别适用于需要多语言（中英文）显示的场景。

二、核心功能与特性

2.1 原生功能继承

完整继承 Apache Guacamole Server 的核心能力，包括：

• 无客户端远程桌面访问（支持 VNC、RDP、SSH、Telnet 等协议）
• 轻量级架构，低资源占用
• 跨平台兼容性（支持主流浏览器访问）
• 可扩展的认证机制（LDAP、数据库、OAuth 等）

2.2 增强特性

• 中英文字体支持：预装常用中英文字体（如宋体、黑体、Arial、Times New Roman 等），解决远程桌面环境中中文显示乱码或字体缺失问题。
• 默认 root 用户：容器默认以 root 用户运行，便于执行高权限操作（如配置文件修改、字体自定义、服务启停等）。

三、使用场景与适用范围

3.1 多语言远程桌面环境

需在远程桌面中同时显示中英文内容的场景，如跨国团队协作、多语言文档编辑等。

3.2 开发与测试环境

开发者或测试人员需通过远程桌面访问服务器，且对界面字体显示有较高要求（如中文日志、多语言 UI 测试）。

3.3 需 root 权限配置的场景

需在容器内直接修改系统配置（如调整字体渲染参数、安装额外依赖）的场景，避免权限不足导致的操作受限。

四、使用方法与配置说明

4.1 快速启动（docker run）

通过以下命令启动容器，映射默认服务端口（guacd 服务端口 4822）：

bash
docker run -d \
  --name guacamole-server \
  -p 4822:4822 \  # guacd 服务默认端口
  -v /path/to/guacamole/config:/etc/guacamole \  # 挂载配置文件（可选，持久化配置）
  -v /path/to/fonts:/usr/share/fonts/custom \  # 挂载自定义字体（可选）
  your-image-name:tag

说明：/path/to/guacamole/config 为宿主机配置文件目录，/path/to/fonts 为自定义字体目录（如需新增字体，可将字体文件放入此目录并挂载）。

4.2 docker-compose 配置示例

yaml
version: '3'
services:
  guacamole-server:
    image: docker.xuanyuan.run/your-image-name:tag
    container_name: guacamole-server
    restart: always
    ports:
      - "4822:4822"  # guacd 服务端口
    environment:
      - GUACD_LOG_LEVEL=info  # 日志级别：debug/info/warn/error
      - GUACD_PORT=4822       # 服务监听端口（默认 4822）
    volumes:
      - ./guacamole/config:/etc/guacamole  # 持久化配置文件
      - ./guacamole/logs:/var/log/guacamole  # 日志持久化
      - ./custom-fonts:/usr/share/fonts/custom  # 自定义字体挂载（可选）
    networks:
      - guacamole-net

networks:
  guacamole-net:
    driver: bridge

4.3 环境变量说明

容器支持通过环境变量调整服务配置，常用参数如下：

4.4 配置文件与持久化

4.4.1 核心配置文件路径

• Guacamole 主配置目录：/etc/guacamole
  包含 guacd.conf（guacd 服务配置）、user-mapping.xml（用户映射配置）等核心文件。

• 字体文件路径：
  系统字体：/usr/share/fonts
  新增中英文字体：/usr/share/fonts/zh-CN（中文）、/usr/share/fonts/en-US（英文）

4.4.2 持久化方案

通过挂载宿主机目录到容器内实现配置持久化：

• 配置文件持久化：-v /path/on/host:/etc/guacamole
• 日志持久化：-v /path/on/host/logs:/var/log/guacamole
• 自定义字体：-v /path/on/host/custom-fonts:/usr/share/fonts/custom（需确保字体文件权限为 root:root）

五、注意事项

1. root 用户安全风险：容器默认以 root 运行，建议在生产环境中通过 --user 参数指定非 root 用户，或限制容器权限（如使用 --cap-drop=ALL）。

2. 字体自定义：如需添加额外字体，将字体文件（如 .ttf、.otf）放入宿主机自定义字体目录，挂载至容器 /usr/share/fonts/custom，并在容器内执行 fc-cache -fv 更新字体缓存。

3. 端口冲突：若宿主机 4822 端口被占用，可通过 GUACD_PORT 环境变量修改服务端口，并调整端口映射（如 -p 8080:4822）。

六、参考链接

• https://guacamole.apache.org/docs/
• https://guacamole.apache.org/docs/gug/guacd.html