Pocket-ID项目在Unraid环境下的反向代理配置问题解析

在Pocket-ID项目的实际部署过程中，部分用户在使用Unraid系统配合SWAG（Nginx）反向代理时遇到了访问异常问题。本文将从技术原理和解决方案两个维度深入剖析该问题。

问题现象分析

当用户通过反向代理访问Pocket-ID的初始化页面时，系统报错"Failed to get application configuration: connect ECONNREFUSED"。通过日志分析可发现以下关键信息：

1. 前端服务（3000端口）和后端API服务（8080端口）通信异常
2. 静态资源请求路径解析失败（如/logo和/background-image）
3. 初始化令牌接口访问出现404错误

核心问题定位

经过技术团队深入排查，发现根本原因在于Unraid社区模板的默认端口配置与Pocket-ID实际架构不匹配。Pocket-ID采用前后端分离架构：

• 前端服务默认运行在3000端口
• 后端API服务默认运行在8080端口
• 反向代理应监听80/443标准端口

解决方案实施

正确的配置方案应遵循以下原则：

1. 环境变量配置：

PORT=3000       # 前端服务端口
BACKEND_PORT=8080 # 后端API端口
PUBLIC_APP_URL=https://your.domain.com # 必须配置为反向代理地址

2. 反向代理配置要点：

• 代理目标应指向容器80端口
• 确保域名解析正确
• 代理规则需同时覆盖前端和后端路径

3. Unraid模板调整： 最新版社区模板已修正此问题，用户可通过以下方式验证：

docker exec container_name env | grep PUBLIC_APP_URL

技术原理延伸

该案例揭示了容器化部署中常见的网络拓扑问题。在微服务架构下，开发者需特别注意：

1. 容器间通信的网络隔离性
2. 反向代理对路径转发的完整性
3. 环境变量在多层服务中的传递一致性

建议用户在类似场景部署时，先通过docker logs命令观察各服务的启动日志，确保所有组件都按预期端口正常监听。对于复合应用架构，推荐使用docker-compose进行服务编排，可以更清晰地定义服务间的网络关系。

通过本次问题的解决，我们不仅修复了特定环境下的配置问题，更为社区贡献了一个典型的容器网络配置参考案例。这将对后续用户在复杂网络环境下部署身份认证服务提供重要借鉴价值。