CPanel部署NiceGUI应用遇阻求助（需WSGI配置或.htaccess修复方案）

我刚帮朋友排查过类似的问题，你遇到的页面仅加载框架、终端报Socket.IO版本不兼容的问题，大概率是代理配置缺失关键头信息，或是WSGI适配没做好，给你分两种方案来解决：

方案一：通过WSGI适配部署（CPanel官方推荐方式） #

NiceGUI底层基于FastAPI（ASGI框架），而CPanel的Python应用管理器通常要求WSGI可调用对象，我们可以通过ASGI转WSGI的方式完成适配，步骤如下：

1. 先确保虚拟环境安装好必要依赖：

source /home/username/virtualenv/tools/3.9/bin/activate && pip install gunicorn uvicorn fastapi nicegui

2. 在应用根目录（/home/username/tools）创建wsgi.py文件，内容如下：

from nicegui import app
from fastapi.middleware.wsgi import WSGIMiddleware

# 将NiceGUI的ASGI应用转换为WSGI兼容对象
wsgi_app = WSGIMiddleware(app)

3. 登录CPanel配置Python应用：
   • 找到「Python应用」管理器，点击「创建应用」，选择对应Python版本（3.9）
   • 设置应用根目录为/home/username/tools，启动文件为wsgi.py，可调用对象为wsgi_app
   • 保存后CPanel会自动生成适配的.htaccess规则，无需手动修改

如果你的应用部署在子目录下（比如https://yourdomain.com/tools），记得在main.py里添加基础路径配置：

from nicegui import app
app.router.base_path = '/tools'

方案二：修复.htaccess的WebSocket代理配置 #

你当前的.htaccess规则没有正确传递WebSocket所需的请求头，导致Socket.IO协议协商失败，修改后的完整配置如下：

# DO NOT REMOVE OR MODIFY. CLOUDLINUX ENV VARS CONFIGURATION BEGIN
<IfModule Litespeed>
</IfModule>
# DO NOT REMOVE OR MODIFY. CLOUDLINUX ENV VARS CONFIGURATION END

<IfModule mod_rewrite.c>
    RewriteEngine On

    # 处理WebSocket请求，强制传递关键头信息
    RewriteCond %{HTTP:Upgrade} =websocket [NC]
    RewriteRule ^(.*)$ ws://127.0.0.1:8080/$1 [P,L,QSA]
    RequestHeader set Upgrade "%{HTTP:Upgrade}e"
    RequestHeader set Connection "upgrade"

    # 处理普通HTTP请求
    RewriteCond %{HTTP:Upgrade} !=websocket [NC]
    RewriteRule ^(.*)$ http://127.0.0.1:8080/$1 [P,L,QSA]
</IfModule>

# 启用代理模块并设置反向代理
<IfModule mod_proxy.c>
    ProxyRequests Off
    ProxyPreserveHost On
    ProxyPass / http://127.0.0.1:8080/
    ProxyPassReverse / http://127.0.0.1:8080/
</IfModule>

# 单独配置WebSocket隧道支持
<IfModule mod_proxy_wstunnel.c>
    ProxyPass /ws ws://127.0.0.1:8080/ws
    ProxyPassReverse /ws ws://127.0.0.1:8080/ws
</IfModule>

修改后还需要注意：

• 联系主机商确认mod_proxy和mod_proxy_wstunnel模块已启用（CPanel默认可能未开启）
• 确保main.py里的启动命令绑定本地所有IP：app.run(host='0.0.0.0', port=8080)
• 子目录部署同样需要添加app.router.base_path配置

关于Socket.IO版本错误的说明 #

这个错误本质是浏览器和服务器的WebSocket连接未成功建立，导致Socket.IO无法协商正确的协议版本。你的原.htaccess没有传递Upgrade和Connection这两个关键请求头，服务器收不到WebSocket升级请求，自然会抛出版本不兼容的报错。

备注：内容来源于stack exchange，提问作者Anoop Jangra