从Wildfly 23迁移至30后WebSocket服务端点无法正常工作

将应用从Wildfly 23迁移至Wildfly 30后，WebSocket服务端点无法建立连接。当前使用默认的standalone.xml配置，HTTP/HTTPS（已通过内置Let's Encrypt配置SSL）下的WEB内容可正常加载，但WebSocket连接始终失败，不清楚问题所在或遗漏的配置项。

相关配置文件 #

/WEB-INF/jboss-web.xml #

<?xml version="1.0" encoding="UTF-8"?>
<jboss-web >
   
   <context-root>/</context-root>  
   <enable-websockets>true</enable-websockets>
   <virtual-host>WebApp1</virtual-host>
      
</jboss-web>

standalone.xml相关片段 #

<server name="default-server">
    <http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true"/>
    <https-listener name="https" socket-binding="https" ssl-context="ssl-context-36669590-7d69-4fed-aa77-fd7b2705472c" enable-http2="true"/>
    <host name="default-host" alias="localhost">
        <location name="/" handler="welcome-content"/>
        <http-invoker http-authentication-factory="application-http-authentication"/>
    </host>
    <host name="app1" alias="app1.co,www.app1.co"/>
</server>
<servlet-container name="default">
    <jsp-config/>
    <websockets/>
</servlet-container>

防火墙规则（ufw） #

Status: active

To                         Action      From
--                         ------      ----
Postfix                    ALLOW       Anywhere
6001/tcp                   ALLOW       Anywhere
8080/tcp                   ALLOW       Anywhere
8443/tcp                   ALLOW       Anywhere
3389                       ALLOW       Anywhere
Postfix (v6)               ALLOW       Anywhere (v6)
6001/tcp (v6)              ALLOW       Anywhere (v6)
8080/tcp (v6)              ALLOW       Anywhere (v6)
8443/tcp (v6)              ALLOW       Anywhere (v6)
3389 (v6)                  ALLOW       Anywhere (v6)

排查关键点 #

• 虚拟主机名称不匹配：jboss-web.xml中<virtual-host>WebApp1</virtual-host>的主机名，和standalone.xml里定义的<host name="app1">名称、大小写都不一致。Wildfly虚拟主机名称大小写敏感，需保持两者一致，要么修改jboss-web.xml的虚拟主机名为app1，要么调整standalone.xml的主机名为WebApp1。
• WebSocket API包路径检查：Wildfly 30基于Jakarta EE 10，WebSocket API已从javax.websocket迁移到jakarta.websocket，确认代码中是否仍在使用旧的javax包路径，需要替换为Jakarta的包。
• 端点URI与客户端连接URL匹配：检查服务端@ServerEndpoint注解的路径是否正确，客户端连接需使用对应协议：HTTP对应ws://，HTTPS对应wss://，且路径需与服务端映射完全一致。
• 虚拟主机配置完整性：standalone.xml中的<host name="app1">未配置<location>指向应用，需添加类似<location name="/" handler="welcome-content"/>的配置，确保应用部署到该虚拟主机下。
• 服务器日志排查：查看Wildfly的standalone/log/server.log，搜索WebSocket相关的错误日志（如握手失败、端点注册失败等），定位具体问题原因。

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