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，大概率是以下任一环节漏了：

Zynq Linux Hardware Debug

Zynq‑7000 / Zynq UltraScale+ 硬件调试技能。适用于 Xilinx Zynq（Cortex‑A9/A53 + FPGA）Linux 环境，调试 I2C、I2S、UART、GPIO 等外设。包括设备树配置、内核驱动、用户空间调试工具、交叉编译和常见问题排查，支持 PetaLinux 开发。

下载

• 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。