guacd和guacamole.war必须同时部署，缺一不可；否则浏览器访问必报404或Connection refused。这是Guacamole架构硬性要求：guacd处理协议通信，guacamole.war提供Web前端，二者通过默认端口4822通信，任一缺失或配置错误（如路径、权限、版本、主机名解析）均导致链路中断。
guacd 和 guacamole.war 必须同时部署，缺一不可；否则浏览器打开就是 404 或 Connection refused。这不是配置问题，是架构硬性要求。
为什么编译 guacd 总失败？三个关键依赖别搞错
Ubuntu/Debian 上最常卡在 configure 阶段，报 jpeglib.h not found 或 no acceptable C compiler found，本质是系统级依赖没对齐：
-
libjpeg-turbo8-dev（Ubuntu 22.04+）必须装，libjpeg62-turbo-dev已废弃，硬装会冲突 -
uuid-dev和libossp-uuid-dev要共存（Ubuntu）；CentOS/RHEL 只需libuuid-devel，但若已装ossp-uuid相关包，反而会干扰 -
build-essential（Ubuntu）或gcc+make（RHEL）不是可选——没它们连./configure都跑不起来
guacamole.war 放进 webapps 就能用？别信
Tomcat 启动后访问 /guacamole 仍 404，大概率是以下任一环节漏了：
- WAR 包名必须是
guacamole.war—— 带版本号如guacamole-1.5.0.war不会被自动解压，路径就错了 -
/etc/guacamole目录必须手动创建，且tomcat用户（或运行 Tomcat 的用户）要有读权限，否则guacamole.properties找不到 - 哪怕只用文件认证（
user-mapping.xml），也得在guacamole.properties里显式声明：auth-provider: net.sourceforge.guacamole.net.basic.BasicFileAuthenticationProvider和basic-user-mapping: /etc/guacamole/user-mapping.xml；删掉auth-provider行，Guacamole 默认连 PostgreSQL，直接卡住
JDK 和 Tomcat 版本不匹配，启动日志里藏了线索
Tomcat 启动成功但 /guacamole 页面空白或 500，先看 catalina.out：
- 出现
UnsupportedClassVersionError→ JDK 太旧，guacamole.war（1.4+）要求 JDK 11+，OpenJDK 8 不行 - Tomcat 日志里反复打印 “Initializing ProtocolHandler” 但没后续 →
guacamole.war没加载，检查 WAR 名、webapps权限、guacamole.properties路径是否拼错 -
guacd进程没起来，netstat -tlnp | grep :4822看不到监听 →guacd没启动或配置里hostname解析失败（比如guacamole.properties中guacd-hostname写成localhost，但/etc/hosts里没映射）
Docker Compose 是最快落地方式，但别跳过网络配置
如果只是想快速验证功能，docker-compose up -d 确实 5 分钟能跑起来，但注意两个易忽略点：
-
guacd容器和guacamole容器必须在同一个自定义网络里，不能靠默认 bridge；否则guacamole找不到guacd，页面报 “Connection closed before handshake” -
mysql容器初始化时，guacamole容器可能抢在数据库 ready 前就启动，导致初始化失败；加depends_on+healthcheck或用restart: on-failure更稳 - 浏览器访问
http://host:8080/guacamole登录后黑屏 → 检查guacamole容器是否挂载了/etc/guacamole卷，且里面guacamole.properties的guacd-hostname指向的是 compose 服务名（如guacd），不是localhost
guacd 和 guacamole.war 之间的那条隐式链路：路径、权限、版本、主机名解析，四个点任意一个断开，整个流程就停在 404。 
