Cal.diy 部署在反向代理后面出现 SSL 证书错误怎么排查？

Cal.diy 部署在反向代理后面出现 SSL 证书错误怎么排查？

【免费下载链接】cal.diyScheduling infrastructure for absolutely everyone.项目地址: https://gitcode.com/GitHub_Trending/ca/cal.diy

当你把 Cal.diy（一个自托管的日程安排应用，Next.js 技术栈）放在 Nginx 等反向代理或负载均衡器后面、由代理做 HTTPS 终结时，Cal.diy 内部发出的请求可能报 SSL 证书错误。项目文档在 Troubleshooting 的 "SSL / HTTPS Issues Behind a Reverse Proxy" 一节专门覆盖了这个现象：

Symptom:Requests fail with SSL certificate errors when Cal.diy is behind a load balancer or reverse proxy that handles HTTPS termination.

排查思路是：先确认内部流量的走向（代理对内转发的是 HTTP 还是自签名 HTTPS），然后对应选择一个方案，并保证NEXTAUTH_URL始终指向公网 HTTPS 地址。下面按文档给出的顺序说明。

先固定一个前提：NEXTAUTH_URL 保持公网 HTTPS 地址

无论采用哪种方案，.env中都应保持：

NEXTAUTH_URL=https://cal.yourdomain.com

cal.yourdomain.com替换为你的实际域名。文档明确提醒：把NEXTAUTH_URL改成http://localhost:3000虽然能消除内部 SSL 错误，但会破坏 OAuth 回调——Google、Microsoft 等外部提供商会把用户重定向到localhost，导致登录失败。所以必须使用公网 URL，不能为了绕过证书错误而把地址改回 localhost。

另外注意：对 Docker 部署，NEXT_PUBLIC_WEBAPP_URL是构建期变量，修改它之后需要重新构建镜像；NEXTAUTH_URL是运行期变量，改.env后重启容器即可生效。

方案一：代理对内转发 HTTP（最常见）

如果反向代理在代理与 Cal.diy 之间走 HTTP（这是文档标注的最常见形态），保持上面的NEXTAUTH_URL不动，然后让代理转发以下请求头，使内部请求被正确识别：

# Nginx example proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

判断依据：配置完成后，应用内部发起的请求（如会话、OAuth 回调）不再出现证书报错，外部 HTTPS 访问和 OAuth 登录均正常。

方案二：内部链路使用自签名证书

如果反向代理到 Cal.diy 之间也是 HTTPS，且内部使用的是自签名证书，则把你的内部 CA 加入 Node 的信任证书：

NODE_EXTRA_CA_CERTS=/path/to/your-internal-ca.crt

把/path/to/your-internal-ca.crt替换为你服务器上内部 CA 证书的实际路径。

方案三：NODE_TLS_REJECT_UNAUTHORIZED=0（不推荐用于生产）

Docker 文档 的 Troubleshooting 一节对 "SSL edge termination" 给出的做法是添加环境变量NODE_TLS_REJECT_UNAUTHORIZED=0，并附了同样的使用前提：

Only do this if you know what you are doing and trust the services/load-balancers directing traffic to your service.

而 Troubleshooting 文档把同一变量列为最后手段（Last resort, not recommended for production），并给出了更完整的安全说明：

NODE_TLS_REJECT_UNAUTHORIZED=0

Security Warning:This disablesallTLS certificate verification globally, including external API calls to Stripe, Google Calendar, and other services. This makes your instance vulnerable to man-in-the-middle attacks. Only use this in isolated development environments where you fully control all network traffic.

也就是说，该变量会全局关闭TLS 证书校验，包括应用对外调用 Stripe、Google Calendar 等服务时的校验，使实例暴露在中间人攻击风险之下。两份文档口径一致：只在完全可控的隔离开发环境使用，不要用于生产。

相邻错误：CLIENT_FETCH_ERROR

如果日志里出现的不是泛化的 SSL 报错，而是下面这类错误（文档示例）：

[next-auth][error][CLIENT_FETCH_ERROR] request to http://<your-domain>/api/auth/session failed, reason: getaddrinfo ENOTFOUND

那根因通常是 Docker 容器无法在自己的网络内解析NEXTAUTH_URL里配置的外部域名。文档给出的解法是给容器加 hosts 映射：

# docker-compose.yml services: calcom: extra_hosts: - "cal.yourdomain.com:127.0.0.1"

但要注意文档标注的边界：这种 hosts 映射方式只在NEXTAUTH_URL使用HTTP时有效（例如http://cal.yourdomain.com:3000）。如果你的NEXTAUTH_URL是 HTTPS，容器会尝试连接127.0.0.1:443，而应用实际监听 3000 端口，仍然会失败——这时要么让反向代理也运行在 Docker 网络内，要么回到上文"SSL / HTTPS Issues Behind a Reverse Proxy"一节的方案处理。文档还解释了为什么不建议用localhost解决这个 DNS 错误：同样会破坏 OAuth 回调。

范围与限制

• 文档在 Installation 中说明：Cal.diy 本质是一个 Next.js 应用，自托管用户可能配置各种复杂的反向代理和 SSL 网关，官方无法支持每一种配置；遇到边缘情况时，参照对应代理（X）关于 Next.js 应用的文档处理。
• 如果上述步骤执行后问题仍未解决，文档给出的求助路径是检索 Cal.diy 的 GitHub Issues、社区论坛，并复查 Docker 配置与安装指南中是否漏了步骤。

按方案一或方案二修复后，验证标准就是回到最初的现象：经反向代理的 HTTPS 请求不再出现 SSL 证书错误，OAuth 登录流程可以完整走完。若只有NODE_TLS_REJECT_UNAUTHORIZED=0才"正常"，说明内部证书链路本身没有配置好，应优先补齐方案一或方案二，而不是长期依赖该变量。

【免费下载链接】cal.diyScheduling infrastructure for absolutely everyone.项目地址: https://gitcode.com/GitHub_Trending/ca/cal.diy