Pocket-ID项目中使用Caddy反向代理的配置要点解析

在使用Pocket-ID项目时，很多开发者会遇到反向代理配置不当导致404错误的问题。本文将深入分析这一常见问题的根源，并提供完整的解决方案。

问题现象分析

当开发者尝试通过Caddy配置反向代理访问Pocket-ID的/admin/setup页面时，系统会报出"SvelteKitError: Not found: /api/one-time-access-token/setup"错误。从日志中可以看到，前端服务能够正常响应，但API路由却无法正确匹配。

根本原因

这个问题源于Pocket-ID内部服务的端口配置与反向代理设置不匹配。项目默认情况下：

1. 前端服务运行在3000端口
2. 后端API服务运行在80端口
3. 当使用Caddy反向代理时，如果只代理前端端口，会导致API路由无法访问

解决方案

正确的配置步骤如下：

1. 环境变量配置：在.env文件中添加或修改以下配置

CADDY_PORT=3333

2. Caddyfile配置：将反向代理指向3333端口

id.example.com {
    reverse_proxy pocketid:3333
}

3. Docker-compose调整：确保端口映射正确

ports:
  - "127.0.0.1:5039:80"

技术原理

Pocket-ID项目采用了前后端分离架构，前端使用SvelteKit框架，后端使用Gin框架。当CADDY_PORT环境变量设置为3333时，项目会：

1. 自动调整内部路由配置
2. 确保前后端服务在统一端口下协调工作
3. 避免端口冲突导致的API路由丢失问题

最佳实践建议

1. 始终确保反向代理配置与CADDY_PORT环境变量一致
2. 在容器化部署时，注意检查端口映射关系
3. 生产环境中建议启用TRUST_PROXY=true以正确处理X-Forwarded-*头信息
4. 定期检查日志中的401/404错误，及时发现配置问题

通过以上配置调整，Pocket-ID项目能够正确处理/admin/setup等管理接口，确保系统正常初始化和管理员账户创建流程的完整性。