Stirling-PDF项目Nginx反向代理配置问题解析

在使用Docker部署Stirling-PDF项目时，很多开发者会遇到通过Nginx反向代理在特定路径（如/stirling）下服务的问题。本文将深入分析这个常见问题的成因和解决方案。

问题现象

当尝试通过Nginx在/stirling路径下代理Stirling-PDF服务时，虽然主页面可以正常访问，但静态资源（如CSS、JS文件）会出现加载失败的情况。这是因为前端资源请求的路径没有自动包含/stirling前缀，导致404错误。

根本原因

这种问题通常由两个因素共同导致：

1. 前端资源路径配置：Stirling-PDF的前端代码中资源路径可能是硬编码为绝对路径（如/css/main.css），而不是相对路径

2. Nginx代理配置：Nginx的proxy_pass设置可能没有正确处理路径重写，导致请求转发时丢失了/stirling前缀

解决方案

1. Docker环境变量配置

在Docker Compose文件中，必须设置BASE_URL环境变量来告知应用它被挂载的路径：

environment:
  - BASE_URL=/stirling

这个设置会确保应用生成的前端资源路径都包含正确的前缀。

2. Nginx配置优化

Nginx配置需要特别注意以下几点：

1. 使用rewrite规则确保路径正确转发
2. 正确处理静态资源请求
3. 设置适当的proxy_set_header

示例配置片段：

location /stirling/ {
    proxy_pass http://localhost:8080/;
    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;
    
    rewrite ^/stirling/(.*)$ /$1 break;
}

3. 前端资源处理

对于更复杂的情况，可能需要：

1. 检查应用的静态资源是否支持路径前缀
2. 考虑使用sub_filter模块动态修改HTML中的资源路径
3. 确保所有API请求也正确处理了路径前缀

最佳实践建议

1. 测试环境验证：先在测试环境验证配置，避免影响生产服务
2. 日志分析：检查Nginx和Stirling-PDF的访问日志，确认请求路径是否正确
3. 浏览器调试：使用浏览器开发者工具查看资源加载失败的具体原因
4. 版本兼容性：确认使用的Stirling-PDF版本是否支持路径前缀功能

通过以上配置和检查，应该能够解决在特定路径下代理Stirling-PDF服务时遇到的资源加载问题。记住，关键在于确保前后端对路径前缀的理解一致，以及Nginx正确转发请求。