Pingvin Share 配置 OpenID 连接时的 SSL 证书问题解决方案

在部署 Pingvin Share 文件共享服务时，许多管理员会选择集成 OpenID Connect (OIDC) 认证服务来实现统一身份管理。本文针对使用自签名 SSL 证书环境下配置 OIDC 时遇到的常见问题进行深入分析，并提供完整的解决方案。

问题现象

当尝试将 Pingvin Share 与 Authentik 等 OIDC 提供商集成时，如果 OIDC 提供商使用了自签名 SSL 证书，系统会返回 500 内部服务器错误。具体表现为：

1. 点击 OpenID 登录按钮后，浏览器跳转至 /api/oauth/auth/oidc 并显示内部服务器错误
2. 后端日志显示 fetch failed 和 unable to get local issuer certificate 错误
3. 通过容器内测试发现无法验证 SSL 证书的合法性

根本原因分析

这个问题源于 Node.js 运行环境默认不信任自签名证书。当 Pingvin Share 尝试从 OIDC 提供商获取配置信息时，Node.js 的 HTTP 客户端会严格验证 SSL 证书链，而自签名证书无法通过这一验证过程。

解决方案

方法一：配置 Node.js 信任自签名证书

最规范的解决方案是将自签名证书的 CA 证书添加到 Node.js 的信任链中：

1. 将 CA 证书文件（如 cert.pem）挂载到容器内
2. 设置 NODE_EXTRA_CA_CERTS 环境变量指向该证书

# docker-compose.yml 示例
services:
  pingvin-share:
    environment:
      - NODE_EXTRA_CA_CERTS=/etc/ssl/certs/cert.pem
    volumes:
      - /path/to/your/cert.pem:/etc/ssl/certs/cert.pem

方法二：临时解决方案（不推荐生产环境使用）

对于测试环境，可以设置 NODE_TLS_REJECT_UNAUTHORIZED=0 来禁用 SSL 验证：

environment:
  - NODE_TLS_REJECT_UNAUTHORIZED=0

注意：这种方法会降低安全性，不建议在生产环境中使用。

配置验证步骤

完成上述配置后，建议按以下步骤验证：

1. 进入容器内部测试连接：

   docker compose exec pingvin-share curl https://your-oidc-provider
   

2. 确认能够正常获取 OIDC 配置信息
3. 测试完整的 OIDC 登录流程

最佳实践建议

1. 对于生产环境，建议使用受信任的 CA 颁发的证书
2. 如果必须使用自签名证书，确保定期更新证书
3. 考虑在反向代理层面处理 SSL 终止，避免应用直接处理证书验证
4. 保持证书文件的权限设置合理，防止未授权访问

通过以上方法，可以解决 Pingvin Share 在自签名证书环境下集成 OIDC 认证时遇到的 SSL 验证问题，实现安全可靠的身份认证集成。