Cursor 连接自建网关时 SSL 证书校验失败怎么处理?

文章导读
连接自建网关报 SSL 校验失败,遇到这种事我一般先压住改配置的手,因为问题大概率出在网关侧。先看报错文本,再决定下一步。
📋 目录
  1. Ⅰ 排查时容易走偏的地方
  2. Ⅱ 补全证书链,先改网关
  3. Ⅲ 自签CA怎么让Cursor信任
  4. Ⅳ 验证和回滚
  5. Ⅴ 后续维护还有两点
A A

连接自建网关报 SSL 校验失败,遇到这种事我一般先压住改配置的手,因为问题大概率出在网关侧。先看报错文本,再决定下一步。

当 Cursor 连接自建网关时,如果报错信息里出现 "SSL certificate verify failed" 或 "unable to verify the first certificate",基本可以判定是客户端在校验服务端证书时中断了握手。这时不要先怀疑网络,先检查自建网关返回的证书链是否完整。多数情况下,是网关只配置了叶子证书,没有带上中间 CA,或者证书链顺序错误。另外,如果使用自签证书,还需要确认该证书是否被客户端所在的操作系统或运行时信任。

排查时容易走偏的地方

不少网上的建议是直接关掉 Cursor 的 SSL 校验,或者让网关忽略证书错误。这个动作确实能立刻去掉报错,但连接安全也就没了。中间人截获连接时,客户端不会发现任何异常。除非是本地开发的隔离环境,临时测试用一下,否则不建议长期这么开着。就算要试,最好只针对特定域名关闭,并且尽快恢复。另一个容易绕远的方向是反复检查端口连通性和代理设置,这些跟证书校验不冲突,通常放着后面再查。

补全证书链,先改网关

如果确认是证书链不完整,处理顺序应该从网关开始。

在自建网关上配置证书时,要把完整的证书链一并提供,顺序通常是从叶子证书开始,依次拼上中间 CA 和根 CA。例如在 Nginx 中,ssl_certificate 文件里应包含该证书链全部内容。配置后,用 openssl s_client -connect 网关地址:端口 观察输出的证书链,确认服务端确实返回了完整链条,而不是只有叶子证书。这样可以避免因中间 CA 缺失导致 Cursor 校验失败。

实际拼接时,把叶子证书、中间证书、根证书按顺序放进同一个 PEM 文件。比如用这条命令生成 fullchain.pem:

cat 叶子证书.crt 中间证书.crt 根证书.crt > /etc/ssl/fullchain.pem

在 Nginx 站点配置里,ssl_certificate 指向这个文件,ssl_certificate_key 指向私钥即可。其他网关软件虽然没有统一写法,但原理一样。改完之后先重载服务,再抓一次证书链看是否完整。

自签CA怎么让Cursor信任

证书链补全后,如果 Cursor 依然报错,那就需要确认客户端是否信任签发网关证书的 CA。

Cursor 连接自建网关时 SSL 证书校验失败怎么处理?

如果自建网关用的是内部 CA 签发的证书,可以把该 CA 的根证书加入操作系统的受信任根证书存储。之后重启 Cursor 或相关服务,让信任配置生效。如果 Cursor 依赖 Node.js 运行时,还可以通过设置环境变量 NODE_EXTRA_CA_CERTS 指向该 CA 文件,这样可以只对当前进程生效,不污染系统信任库。注意环境变量需要提前设置,而且文件路径必须是绝对路径。

在 macOS 上,可以打开钥匙串访问,把根证书导入到“系统”范围,并标记为信任。在 Windows 上,可以通过证书管理单元导入到“受信任的根证书颁发机构”。Linux 发行版一般放在 /etc/ssl/certs 或系统指定的 ca-certificates 目录。如果不想动系统信任库,就在启动 Cursor 的终端里设置 NODE_EXTRA_CA_CERTS 环境变量,再重新启动应用。这个变量只在当前会话生效,值得优先考虑。

验证和回滚

改完配置后,用这条命令看服务端实际下发的证书链:

openssl s_client -connect 你的网关地址:端口 -showcerts

输出里 Certificate chain 部分,每一行对应一个证书。如果只有一行,说明证书链还是不全,需要回网关检查拼接顺序。也可以带着 -servername 参数指定服务器名称,避免因 SNI 拿错证书。客户端那边,可以用 openssl verify -CAfile 你的根证书文件 你的证书文件 来确认信任链,返回 OK 说明校验能通过。如果仍失败,把报错文本和链的输出来对比,能省不少时间。

改动前记得备份原文件。Nginx 的证书文件改成 fullchain.pem 之前,先保留原来的单独证书。万一新文件有问题,把路径指回原文件就能恢复。信任库方面,撤销就是把导入的根证书删除,或者取消 NODE_EXTRA_CA_CERTS 环境变量。整体来说,回滚动作都不复杂,难点在于判断哪个环节出了问题。

后续维护还有两点

证书链完整、信任库也正常后,还要留意证书有效期和客户端系统时间。证书过期会让校验失败,时间偏差过大也一样。自建网关的证书如果由公共 CA 签发已经过期,导入信任库也没用,需要重新申请。检查证书到期时间可以用 openssl x509 -in 证书文件 -noout -dates。如果 Cursor 所在机器的时间经常漂移,记得开启时间同步。这个和证书问题混在一起时,容易让人误判成网络故障。

处理这个问题的稳妥顺序是先补全证书链,再确认信任来源,最后才是考虑临时关闭校验。每一步验证都可以用 openssl 命令直接看到结果,不会花太多时间。