Stirling-PDF项目中使用Nginx反向代理配置子目录路径的解决方案

问题背景

在使用Stirling-PDF项目时，很多开发者希望通过Nginx反向代理将其部署在子目录下（如/stirling），而非根目录。然而在实际配置过程中，经常遇到资源加载路径错误的问题，表现为页面可以访问但CSS、JS等静态资源无法正确加载。

核心问题分析

当Stirling-PDF运行在Docker容器中并通过Nginx反向代理时，主要存在两个配置要点：

1. Docker环境变量配置：需要在容器启动时设置正确的BASE_URL参数
2. Nginx代理配置：需要正确处理路径重写和代理请求

详细解决方案

Docker容器配置

在docker-compose.yml文件中，必须明确设置BASE_URL环境变量：

environment:
  - BASE_URL=/stirling

这个设置告诉Stirling-PDF应用它将被访问的基础路径是/stirling，这样应用生成的所有资源链接都会自动包含此前缀。

Nginx配置要点

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

1. location匹配：确保正确捕获/stirling路径下的所有请求
2. 代理头设置：传递必要的头信息
3. 路径重写：正确处理应用内部路径

示例配置片段：

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;
    
    # 重要：重写路径，移除/stirling前缀
    rewrite ^/stirling/(.*)$ /$1 break;
}

常见问题排查

如果按照上述配置后仍然遇到问题，可以检查以下几个方面：

1. BASE_URL设置是否正确：确认Docker容器中确实设置了正确的环境变量
2. Nginx日志分析：查看Nginx的access和error日志，确认请求是否被正确转发
3. 应用日志检查：查看Stirling-PDF容器的日志，确认应用是否收到预期格式的请求
4. 浏览器开发者工具：使用浏览器开发者工具的网络面板，查看资源加载失败的具体原因

高级配置建议

对于生产环境部署，还可以考虑以下优化措施：

1. 启用HTTPS：通过Let's Encrypt等工具配置SSL证书
2. 静态资源缓存：为CSS、JS等静态资源配置适当的缓存策略
3. 访问限制：配置基本的HTTP认证或IP白名单
4. 负载均衡：如果需要，可以配置多个Stirling-PDF实例进行负载均衡

总结

通过正确配置Docker环境变量和Nginx反向代理规则，可以顺利将Stirling-PDF部署在子目录下。关键在于确保应用知晓自己的部署路径（通过BASE_URL），同时Nginx能够正确处理路径重写和请求转发。遵循上述配置指南，即可解决常见的资源加载路径问题。