Sub-Store项目Nginx子目录代理冲突问题解决方案

问题背景

在Web应用部署实践中，开发者经常需要通过Nginx反向代理实现同一域名下不同子目录指向不同后端服务。Sub-Store项目作为前端应用，当与xui等面板类应用共享域名时，若采用/和/panel/的子目录划分方式，会出现路由冲突问题：访问/panel/路径时仍会返回Sub-Store的404页面。

技术原理分析

该问题的核心在于Sub-Store作为PWA（渐进式Web应用）的特殊行为机制：

1. Service Worker缓存策略：PWA默认会注册Service Worker来缓存应用资源，其navigateFallback机制会将所有导航请求回退到入口页面
2. 路由拦截规则：Sub-Store默认配置的navigateFallbackDenylist规则为/(^|\/.+)\/(api|download)\/.+/，这意味着只有包含/api/或/download/的路径才会绕过PWA缓存
3. 路径匹配优先级：Nginx虽然正确代理了/panel/路径，但浏览器端已被缓存的Service Worker会优先拦截请求

解决方案对比

方案一：修改PWA配置（需重新编译）

1. 调整navigateFallbackDenylist配置，添加/panel/路径规则
2. 修改runtimeCaching策略为NetworkOnly模式
3. 需要重新构建前端应用
4. 局限性：可能影响其他缓存功能，需全面测试

方案二：路径命名规范调整

1. 遵循现有拦截规则，改用/api/panel/或/download/panel/等路径
2. 保持Nginx配置同步修改
3. 优势：无需修改前端代码
4. 缺点：URL结构不够直观

方案三：禁用PWA特性

1. 移除Service Worker注册逻辑
2. 或配置skipWaiting和clientsClaim
3. 效果：彻底避免前端路由拦截
4. 影响：失去离线访问等PWA优势

生产环境建议

对于已部署的生产环境，推荐采用组合方案：

1. 短期方案：立即禁用PWA功能确保业务连续性
2. 长期方案：规划合理的URL命名空间，如：
   • /app/作为前端应用路径
   • /manage/作为管理后台路径
3. 配套措施：在Nginx配置中添加缓存控制头Cache-Control: no-store

配置优化示例

location ~ ^/(panel|api|admin)/ {
    proxy_pass http://backend;
    proxy_set_header Connection "";
    proxy_http_version 1.1;
    add_header Cache-Control "no-cache, no-store, must-revalidate";
}

location / {
    proxy_pass http://frontend;
    # 特别声明PWA路径
    add_header Service-Worker-Allowed "/";
}

经验总结

1. PWA应用部署需特别注意路由拦截行为
2. 子目录划分应提前规划命名规范
3. 混合部署时应进行完整的集成测试
4. Nginx的proxy_cache指令可与前端缓存配合使用
5. 开发环境与生产环境的缓存表现可能存在差异

通过理解这些技术原理和解决方案，开发者可以更优雅地实现多应用同域部署，避免路由冲突问题。