如何通过guacamole-common-js连接Guacamole？遇GUAC_ID缺失错误

问题原因 #

你遇到的GUAC_ID is required错误，是因为通过guacamole-common-js直接使用WebSocket隧道时，未完成Guacamole的认证流程获取有效会话令牌（即GUAC_ID）。浏览器端的Guacamole界面会自动处理会话认证并传递GUAC_ID，但自定义应用需要手动完成认证步骤。

解决步骤 #

1. 通过Guacamole REST API获取认证令牌 #

Guacamole提供/api/tokens接口用于认证，需先发送POST请求获取会话令牌，再用令牌构造WebSocket隧道地址。修改你的JavaScript代码如下：

async function initializeGuacamoleClient() {
    // 1. 发起认证请求获取令牌
    const authResponse = await fetch("http://[virtualmachineaddress]:8080/guacamole/api/tokens", {
        method: "POST",
        headers: {
            "Content-Type": "application/x-www-form-urlencoded"
        },
        body: "username=guacadmin&password=guacadmin"
    });

    if (!authResponse.ok) {
        throw new Error("认证失败: " + authResponse.statusText);
    }

    const { authToken } = await authResponse.json();

    // 2. 使用令牌构造WebSocket隧道地址
    var tunnel = new Guacamole.WebSocketTunnel(
        `ws://[virtualmachineaddress]:8080/guacamole/websocket-tunnel?token=${authToken}`
    );

    guacClient = new Guacamole.Client(tunnel);

    if (displayContainer) {
        displayContainer.appendChild(guacClient.getDisplay().getElement());
        displayContainer.style.display = "block";
        // 3. 连接时无需再传用户名密码，令牌已包含认证信息
        guacClient.connect();
    }
}

2. 完善CORS配置 #

你的docker-compose.yml中已启用CORS，但需确保请求头允许Content-Type，补充以下环境变量：

guacamole:
  # ... 原有配置
  environment:
    # ... 已有的环境变量
    GUACAMOLE_CORS_ALLOWED_HEADERS: 'Content-Type'

3. 关键注意事项 #

• 令牌存在过期时间，连接断开后需重新获取
• 生产环境禁止硬编码用户名密码，建议通过安全方式传递凭证
• 确认虚拟机防火墙已开放8080端口的HTTP和WebSocket流量

原代码失效原因 #

直接调用guacClient.connect("username=guacadmin&password=guacadmin")仅适用于HTTP隧道（Guacamole.HTTPTunnel）场景。WebSocket握手阶段无法像HTTP请求那样传递认证参数，必须预先完成认证并在URL中携带令牌。

内容的提问来源于stack exchange，提问作者sergi martinez