Quarkus WebSocket无法连接求助：按官方指南配置仍报错

按照Quarkus官方WebSocket指南实现后，自己的代码无法连接WebSocket；随后通过code.quarkus.io生成仅包含quarkus-websockets扩展的新项目，编写了如下StartWebSocket类。服务器运行在http://localhost:8080，使用Postman连接ws://localhost:8080/start-websocket/test时，抛出错误Error: connect ECONNREFUSED ::1:8080。请问问题出在哪里？是否需要指南未提及的额外配置？

package org.acme;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.websocket.EncodeException;
import jakarta.websocket.OnClose;
import jakarta.websocket.OnError;
import jakarta.websocket.OnMessage;
import jakarta.websocket.OnOpen;
import jakarta.websocket.Session;
import jakarta.websocket.server.PathParam;
import jakarta.websocket.server.ServerEndpoint;
import java.io.IOException;

import static java.util.Objects.requireNonNull;

@ServerEndpoint("/start-websocket/{name}")
@ApplicationScoped
public class StartWebSocket {

@OnOpen
public void onOpen(Session session, @PathParam("name") String name) {
    System.out.println("onOpen> " + name);
}

@OnClose
public void onClose(Session session, @PathParam("name") String name) {
    System.out.println("onClose> " + name);
}

@OnError
public void onError(Session session, @PathParam("name") String name, Throwable throwable) {
    System.out.println("onError> " + name + ": " + throwable);
}

@OnMessage
public void onMessage(String message, @PathParam("name") String name) {
    System.out.println("onMessage> " + name + ": " + message);
  }
}

• 端口绑定与IPv6/IPv4差异：错误提示连接::1:8080（IPv6本地地址）被拒绝，可能Quarkus服务仅绑定了IPv4的127.0.0.1地址。

  • 检查Quarkus启动日志，确认绑定地址：若日志显示Listening on: http://127.0.0.1:8080，则尝试用ws://127.0.0.1:8080/start-websocket/test连接；
  • 若需要同时支持IPv4和IPv6，可在application.properties中添加配置：quarkus.http.host=0.0.0.0，让服务绑定所有可用地址。

• 路径正确性验证：

  • 确认项目未配置根路径前缀：若application.properties中有quarkus.http.root-path配置，需在WebSocket连接路径前加上该前缀，例如根路径为/myapp时，连接地址应为ws://localhost:8080/myapp/start-websocket/test；
  • 检查启动日志中是否有WebSocket端点注册信息，比如Registered web socket endpoint at path /start-websocket/{name}，若没有则说明端点未成功注册。

• 扩展依赖确认：虽然通过code.quarkus.io生成项目，但仍需检查构建文件确保quarkus-websockets扩展已正确引入：

  • Maven项目（pom.xml）需包含：

    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-websockets</artifactId>
    </dependency>
    

  • Gradle项目（build.gradle）需包含：

    implementation 'io.quarkus:quarkus-websockets'
    

• 网络环境排查：

  • 检查本地防火墙是否阻止了8080端口的连接；
  • 若Postman使用了代理，尝试关闭代理后重新连接；
  • 换用浏览器控制台测试：在开发者工具中执行new WebSocket('ws://localhost:8080/start-websocket/test')，观察是否能成功连接，排除Postman自身问题。

内容的提问来源于stack exchange，提问作者Biggy Poopa