Pocket-ID 项目中使用 Caddy 反向代理的配置指南

背景介绍

Pocket-ID 是一个基于 Passkey 的身份验证工具，可以作为 OpenID Connect (OIDC) 提供者为其他应用提供认证服务。在实际部署中，很多用户会选择使用 Caddy 作为前端反向代理来管理 Pocket-ID 和其他服务的访问。

常见配置问题

在将 Pocket-ID 部署在 Caddy 反向代理后面时，用户可能会遇到以下典型问题：

1. 直接访问 Pocket-ID 的 /.well-known 端点可以正常工作，但通过 OIDC 集成时返回 40x 错误
2. 客户端应用无法正确完成 OIDC 认证流程
3. 日志中出现 403 或 400 状态码

解决方案

基础 Caddy 配置

以下是一个基本的 Caddy 反向代理配置示例，适用于将 Pocket-ID 暴露在公网：

pocketid.yourdomain.com {
    reverse_proxy http://172.17.0.1:3000

    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
    }

    tls {
        protocols tls1.2 tls1.3
        ciphers TLS_AES_128_GCM_SHA256 TLS_CHACHA20_POLY1305_SHA256
    }
}

Pocket-ID 环境变量配置

在 Pocket-ID 的 .env 文件中，必须正确设置以下关键参数：

PUBLIC_APP_URL=https://pocketid.yourdomain.com
TRUST_PROXY=true

TRUST_PROXY 参数特别重要，它告诉 Pocket-ID 信任来自反向代理的头部信息，这对于正确处理 OIDC 重定向至关重要。

客户端应用配置

当配置客户端应用（如 Mealie 或 FreshRSS）使用 Pocket-ID 作为 OIDC 提供者时，需要注意：

1. OIDC 配置 URL 必须指向正确的 /.well-known/openid-configuration 端点
2. 客户端密钥 必须完全匹配，包括大小写和特殊字符
3. 回调 URL 必须精确匹配，包括结尾的斜杠（如有）

常见错误排查

1. 403 错误：通常表示客户端密钥不匹配或 TRUST_PROXY 未正确设置
2. 400 错误：可能由于回调 URL 配置错误或 OIDC 参数不完整
3. 端点访问问题：确保 /.well-known 端点可以从客户端应用网络访问

与 Mealie 集成的特别说明

Mealie 对 OIDC 实现有特定要求，需要注意：

1. 使用官方 Mealie 镜像（ghcr.io/mealie-recipes/mealie）而非第三方镜像
2. 确保 BASE_URL 配置正确
3. OIDC_USER_CLAIM 通常设置为 "email"

总结

通过正确配置 Caddy 反向代理和 Pocket-ID 的环境变量，大多数 OIDC 集成问题都可以解决。关键点包括信任代理设置、精确的客户端配置以及使用兼容的客户端应用版本。当遇到问题时，检查日志中的具体错误代码和请求路径是快速定位问题的有效方法。