NapCatQQ WebUI 通过 Nginx 反向代理的配置实践

背景介绍

NapCatQQ 是一款基于 Node.js 开发的 QQ 机器人框架，其提供了 WebUI 管理界面，默认运行在 6099 端口。在实际生产环境中，我们通常需要通过 Nginx 反向代理来提供更安全的访问方式和更好的性能表现。

标准配置方案

经过实践验证，以下 Nginx 配置可以完美支持 NapCatQQ WebUI 的反向代理：

location /webui/ {
    proxy_pass http://127.0.0.1:6099/;
    proxy_http_version 1.1;

    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto http;
    proxy_redirect http:// $scheme://;
    proxy_set_header REMOTE-HOST $remote_addr;
    add_header X-Cache $upstream_cache_status;
}

location /api/ {
    proxy_pass http://127.0.0.1:6099;
    proxy_http_version 1.1;

    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto http;
    proxy_redirect http:// $scheme://;
    proxy_set_header REMOTE-HOST $remote_addr;
    add_header X-Cache $upstream_cache_status;
}

location /files/ {
    proxy_pass http://127.0.0.1:6099;
    proxy_http_version 1.1;

    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto http;
    proxy_redirect http:// $scheme://;
    proxy_set_header REMOTE-HOST $remote_addr;
    add_header X-Cache $upstream_cache_status;
}

location /auth/ {
    proxy_pass http://127.0.0.1:6099;
    proxy_http_version 1.1;

    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto http;
    proxy_redirect http:// $scheme://;
    proxy_set_header REMOTE-HOST $remote_addr;
    add_header X-Cache $upstream_cache_status;
}

配置说明

1. 路径匹配：配置中分别处理了 /webui/、/api/、/files/ 和 /auth/ 四个路径的代理请求
2. WebSocket支持：通过 Upgrade 和 Connection 头部的设置，确保 WebSocket 连接能够正常工作
3. 真实IP传递：X-Real-IP 和 X-Forwarded-For 头部确保了后端服务能够获取到客户端的真实IP
4. 协议转换：proxy_redirect 指令处理了 HTTP 到 HTTPS 的重定向问题

常见问题与解决方案

修改默认路径的问题

尝试将 /webui/ 修改为其他路径（如 /example/）并添加重写规则时，会出现404错误。这是因为：

1. WebUI 前端代码中硬编码了 /webui/ 路径
2. 静态资源请求和API调用都基于这个基础路径

推荐解决方案

1. 使用子域名：为 WebUI 分配独立的子域名（如 webui.example.com），然后使用最简单的代理配置：

   location / {
       proxy_pass http://127.0.0.1:6099;
       # 其他代理设置...
   }
   

2. 保持默认路径：如果必须使用路径而非子域名，建议保持 /webui/ 不变，避免兼容性问题

最佳实践建议

1. 启用HTTPS：在生产环境中务必配置SSL证书，确保通信安全
2. 访问控制：结合Nginx的auth_basic或IP限制功能，增加额外的安全层
3. 性能优化：对于静态资源可考虑添加缓存头，减少服务器负载
4. 日志监控：配置单独的访问日志，便于问题排查和流量分析

通过以上配置和方案，可以确保NapCatQQ WebUI在Nginx反向代理环境下稳定运行，同时兼顾安全性和性能需求。