Hoarder应用Nginx反向代理配置问题解决方案

问题背景

在使用Hoarder应用0.23版本更新后，部分用户报告"更改布局"功能失效的问题。这一问题主要出现在使用Nginx作为反向代理的环境中。经过排查，发现这是由于Next.js框架在最新版本中增强了安全验证机制，对HTTP头部信息进行了更严格的检查。

错误现象

当用户尝试使用"更改布局"功能时，系统会抛出以下错误：

x-forwarded-host header with value `hoarder.mai-space.net` does not match `origin` header with value `hoarder.mai-space.net:30000`

这表明反向代理配置中存在HTTP头部信息不匹配的问题，导致Next.js的安全机制阻止了服务器端操作的执行。

解决方案

对于使用Nginx Proxy Manager的用户，可以按照以下步骤进行修复：

1. 登录Nginx Proxy Manager管理界面
2. 在"代理主机列表"中找到Hoarder应用的配置项
3. 点击右侧的三个点，选择"编辑"
4. 切换到"高级"选项卡
5. 在配置区域粘贴以下Nginx配置代码：

location / {
    proxy_pass http://<Hoarder服务地址>:<端口>;
    proxy_set_header Host $http_host;
    proxy_redirect http:// https://; 
    proxy_set_header X-Forwarded-Host $http_host;
    proxy_set_header X-Forwarded-Port $server_port; 
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Scheme $scheme;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $http_connection;
    proxy_http_version 1.1;
}

注意：需要将<Hoarder服务地址>:<端口>替换为实际的Hoarder服务地址和端口号。例如：

• 如果Hoarder运行在同一主机的3000端口：http://localhost:3000
• 如果使用Docker容器名称：http://hoarder-web:3000

配置说明

这段Nginx配置主要解决了以下几个关键问题：

1. Host头传递：确保原始请求的Host头正确传递给后端服务
2. 协议重定向：将HTTP请求重定向到HTTPS
3. X-Forwarded头设置：完整设置转发相关的头部信息，包括：
   • 主机名
   • 端口号
   • 协议类型
   • 客户端真实IP
4. WebSocket支持：通过设置Upgrade和Connection头部，确保WebSocket连接能正常工作
5. HTTP版本：强制使用HTTP/1.1协议

技术原理

Next.js 14+版本增强了对服务器操作(Server Actions)的安全验证。当使用反向代理时，必须确保以下头部信息正确且一致：

1. Host头必须与X-Forwarded-Host头匹配
2. 协议信息(http/https)必须正确传递
3. 端口信息必须准确反映实际访问端口

这些验证机制是为了防止跨站请求伪造(CSRF)和其他安全威胁。当这些头部信息不匹配时，Next.js会主动拒绝服务器端操作的执行，从而保护应用安全。

最佳实践

对于生产环境部署Hoarder应用，建议：

1. 始终使用HTTPS协议
2. 确保反向代理配置中包含完整的转发头部
3. 定期检查Nginx配置，特别是在应用升级后
4. 考虑使用健康检查机制监控反向代理状态
5. 对于Docker环境，确保容器网络配置正确

通过以上配置调整，Hoarder应用的所有功能，包括"更改布局"等服务器端操作，应该能够恢复正常工作。这一解决方案不仅适用于当前问题，也为其他可能出现的反向代理相关问题提供了通用的解决框架。