Pocket-ID项目中使用非标准端口的配置指南

背景介绍

Pocket-ID是一个开源的身份验证解决方案，采用SvelteKit作为前端框架，Gin作为后端框架。在实际部署过程中，很多开发者会遇到需要修改默认端口的情况，特别是在使用反向代理或容器化部署时。

问题现象

当开发者尝试将Pocket-ID运行在非80端口时（例如3000端口），虽然基础页面可以正常加载，但在进行身份验证操作时会出现SvelteKitError: Not found错误。具体表现为无法访问/api/application-configuration/logo、/api/application-configuration/background-image等API端点。

问题根源

经过分析，这个问题源于Pocket-ID内部的多层架构设计：

1. 前端服务：运行在SvelteKit环境下
2. 后端服务：基于Gin框架
3. Caddy服务器：作为反向代理和静态文件服务器

当修改运行端口时，仅设置PORT环境变量是不够的，因为Caddy服务器的监听端口也需要相应调整。

解决方案

最新版本的Pocket-ID(v0.9.0)引入了CADDY_PORT环境变量，专门用于配置Caddy服务器的监听端口。以下是正确的配置方法：

1. 不使用默认80端口：如果你的部署环境需要使用其他端口（如3080）
2. 同时设置两个环境变量：

   environment:
     - PORT=3080
     - CADDY_PORT=3080
   

配置示例

以下是一个完整的Docker Compose配置示例，展示了如何在3080端口运行Pocket-ID：

services:
  pocket-id:
    image: stonith404/pocket-id
    environment:
      - PORT=3080
      - CADDY_PORT=3080
      - PUBLIC_APP_URL=https://your-domain.example.com
    ports:
      - "3080:3080"

注意事项

1. 端口选择：避免使用3000端口，因为它可能被内部服务占用
2. 反向代理配置：如果使用Traefik等反向代理，确保将流量正确转发到CADDY_PORT指定的端口
3. 权限问题：在容器化部署时，注意文件系统权限，特别是当Caddy需要写入配置时

最佳实践

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

1. 使用高于1024的非特权端口
2. 保持PORT和CADDY_PORT的值一致
3. 通过反向代理提供HTTPS终止
4. 定期检查项目更新，获取最新的配置选项

通过正确配置这些环境变量，开发者可以灵活地将Pocket-ID部署在各种网络环境中，而不会遇到API端点不可用的问题。