Biliup项目WebUI在Nginx子目录反代配置问题解析

问题背景

在使用Biliup项目的WebUI功能时，当用户尝试通过Nginx反向代理将WebUI部署在子目录路径下（例如example.com/live/）时，会遇到页面自动跳转到根目录的问题。这种配置需求在实际部署中非常常见，特别是当用户希望将多个服务通过同一域名不同路径进行区分访问时。

技术原理分析

该问题的本质是前端路由与反向代理配置的匹配问题。现代前端应用（如React/Vue等框架构建的应用）通常采用两种路由模式：

1. BrowserRouter模式：依赖HTML5 History API实现前端路由
2. HashRouter模式：使用URL hash部分实现路由

Biliup的WebUI采用的是BrowserRouter模式，这种模式在直接访问时工作正常，但在子目录反代时会出现路径匹配问题，因为：

• 前端应用默认认为自己是部署在根路径下
• 所有资源请求和路由跳转都会基于根路径进行
• Nginx反代后，实际应用是部署在子路径下，导致路径不匹配

解决方案

方案一：修改前端配置（推荐）

1. 在React应用的配置中设置homepage字段为子目录路径
2. 确保所有路由链接都使用绝对路径（包含子目录前缀）
3. 配置Webpack等构建工具的publicPath为子目录路径

具体实现需要修改Biliup的源码中的相关配置，然后重新构建前端资源。

方案二：Nginx重写规则

通过Nginx的rewrite规则将子目录请求正确转发：

location /live/ {
    proxy_pass http://localhost:端口号/;
    proxy_set_header Host $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 $scheme;
    
    # 处理前端路由
    try_files $uri $uri/ /live/index.html;
}

方案三：使用HashRouter模式

修改前端路由模式为HashRouter，这样URL会使用#来管理路由，不依赖服务器配置。但这种方式会改变URL结构，可能影响用户体验。

最佳实践建议

1. 开发环境与生产环境一致：确保开发时就在子目录环境下测试
2. 环境变量配置：使用环境变量动态配置基础路径
3. API请求处理：确保所有API请求也正确处理子目录前缀
4. 静态资源路径：检查所有静态资源引用是否使用正确路径

总结

Biliup项目WebUI在子目录反代场景下的路径问题，本质上是前端应用部署路径与预期访问路径不一致导致的。通过合理配置前端构建参数或调整Nginx反代规则，都可以解决这一问题。对于希望保持项目原样的用户，Nginx重写方案更为简便；而对于有能力维护自定义版本的用户，修改前端配置是更彻底的解决方案。