Guacamole必须同时部署guacd（C服务端）和guacamole.war（Java Web应用），缺一则浏览器返回404或连接拒绝；常见失败原因包括依赖包不匹配、编译环境缺失、WAR包名错误、Tomcat JDK版本不足、配置目录权限不足、数据库配置遗漏及guacd主机名解析异常。
Guacamole 不是“装完就能用”的软件，它必须同时部署 guacd（C 服务端）和 guacamole.war（Java Web 应用），缺一不可。跳过任一环节，浏览器打开只会显示 404 或连接被拒绝。
guacd 编译失败最常见的三个原因
在 Ubuntu/Debian 或 RHEL/CentOS 上从源码编译 guacd 时，90% 的失败不是因为代码问题，而是系统级依赖没对齐：
-
libjpeg-turbo8-dev（Ubuntu）或libjpeg-turbo-devel（RHEL）必须安装，libjpeg62-turbo-dev是旧版包名，22.04+ 已废弃，硬装会导致 configure 报错 “jpeglib.h not found” -
uuid-dev和libossp-uuid-dev不能只装一个：Ubuntu 需两者共存；CentOS 只需libuuid-devel，但若已装了 ossp-uuid 相关包，反而可能冲突 - 执行
./configure --with-init-dir=/etc/init.d后，如果提示 “no acceptable C compiler found”，说明build-essential（Ubuntu）或gcc（RHEL）没装，不是“可选”而是硬依赖
guacamole.war 部署后打不开的直接检查项
guacamole.war 放进 Tomcat 的 webapps 目录不等于就跑起来了，常见卡点如下：
- Tomcat 必须运行在 JDK 11+，OpenJDK 8 会启动失败，日志里出现
UnsupportedClassVersionError - WAR 包名必须是
guacamole.war（不能带版本号如guacamole-1.5.0.war），否则 Tomcat 不会自动解压为guacamole/子目录，导致路径/guacamole404 - 必须手动创建
/etc/guacamole目录，并确保 Tomcat 进程（通常是tomcat用户）对该目录有读取权限，否则初始化时找不到guacamole.properties
数据库配置不是可选项，哪怕只用默认文件认证
很多人以为不用 MySQL 就能跳过数据库，这是误解。Guacamole 的 user-mapping.xml 文件认证方式，仍需数据库驱动支持——它底层用的是 HSQLDB 内存数据库，但需要显式启用：
- 在
/etc/guacamole/guacamole.properties中至少保留这三行：auth-provider: net.sourceforge.guacamole.net.basic.BasicFileAuthenticationProvider basic-user-mapping: /etc/guacamole/user-mapping.xml
- 如果删掉
auth-provider行，Guacamole 会默认尝试连接 PostgreSQL，报错Connection refused并卡住启动 -
user-mapping.xml里的密码字段必须是 BCrypt 加密后的字符串，明文 password 直接被忽略；可用在线工具生成，别手写
最易被忽略的一点：guacd 默认监听 127.0.0.1:4822，而 guacamole.war 默认尝试连 localhost:4822。在某些容器化或 hosts 配置异常的环境里，localhost 解析可能失败，此时必须在 guacamole.properties 中显式写成 guacd-hostname: 127.0.0.1，否则前端白屏无报错。
