Meteor 证书过期故障排查指南：Let‘s Encrypt DST Root CA X3 根证书过期后的命令、请求与客户端兼容性问题

Meteor 证书过期故障排查指南：Let's Encrypt DST Root CA X3 根证书过期后的命令、请求与客户端兼容性问题

【免费下载链接】meteor Meteor, the JavaScript App Platform 项目地址: https://gitcode.com/gh_mirrors/me/meteor

Meteor 应用平台（包括 Galaxy 托管服务）使用 Let's Encrypt 颁发的证书。2021 年 9 月 30 日，Let's Encrypt 的旧根证书 DST Root CA X3 到期，导致运行旧版本 Meteor（低于 v1.9，即 Node.js 低于 v10）的环境出现证书校验失败。本篇指南以本仓库 v3-docs/docs/troubleshooting/expired-certificate.md 为基础，系统梳理"无法运行 Meteor 命令""服务端请求失败""客户端无法访问网站"三类故障的成因、临时规避方案与根治方案，并对照 SECURITY.md 与工具链源码给出升级路线，帮助你在不牺牲安全性的前提下恢复全部功能。

背景：DST Root CA X3 到期与 ISRG Root X1 的接管

Let's Encrypt 于 2021 年 5 月发布公告，说明其交叉签名的旧根证书 DST Root CA X3 将于 2021 年 9 月 30 日 过期。在此之前，Let's Encrypt 签发的证书同时带有 DST Root CA X3 与新的 ISRG Root X1 两条信任链；过期之后，任何依赖 DST Root CA X3 链完成验证的客户端都将失效，而信任库中已预装 ISRG Root X1 的系统（或能自动获取新链的客户端）不受影响。

需要特别强调的是：这不是 Meteor 或 Galaxy 的缺陷，而是使用 Let's Encrypt 证书时必然经历的证书生命周期更替。只要你的客户端（操作系统、Node.js 运行时、浏览器）信任库中缺少 ISRG Root X1，无论访问的是 Galaxy 域名还是任何使用 Let's Encrypt 证书的外部站点，都会出现证书校验失败。

为什么旧版本 Meteor 首当其冲

Meteor v1.9 之前的版本内置的 Node.js 低于 v10，而 Node.js v10 以下的版本依赖 OpenSSL < 1.0.2。OpenSSL 1.0.2 及更早版本在 DST Root CA X3 过期后，默认无法完成对 Let's Encrypt 新信任链的验证。

从当前仓库的代码可以看到 Meteor 对 Node 版本的门槛已经大幅提升：

• tools/cli/main.js 中定义 MIN_NODE_VERSION = 'v18.16.0'，CLI 启动时若低于该版本会直接报错退出；
• tools/static-assets/server/boot.js 中的服务器引导代码同样要求 v18.16.0 及以上。

也就是说，当前仓库的 Meteor 3.x 工具链要求 Node ≥ 18.16.0，其内置的 OpenSSL 版本早已包含 ISRG Root X1，不会遇到本文所述的旧证书信任链问题。真正受影响的，是仍停留在 v1.9 之前、内置 Node < 10 / OpenSSL < 1.0.2 的遗留版本。

下表（原文档引用，仓库内位于 v3-docs/docs/public/openssl-suport-table.png）直观展示了不同系统与 OpenSSL 版本在证书过期前后的兼容性差异：

从表中可以总结出三条关键判定规则：

1. 信任库已包含 ISRG Root X1 且 OpenSSL ≥ 1.1：默认兼容，无需任何操作；
2. OpenSSL 1.0.x 且信任库含 ISRG Root X1：默认不可用，需要额外配置；
3. 信任库不含 ISRG Root X1（无论 OpenSSL 版本）：默认不可用，DST Root CA X3 过期后信任链断裂。

故障一：无法运行 Meteor 命令

如果运行 meteor 系列命令时出现类似 Connection error (certificate has expired) 的错误，说明你正在使用 Meteor v1.9 之前的版本（内置 Node < 10、OpenSSL < 1.0.2）。此时 Meteor CLI 与 Meteor 官方资源服务器（以及 Galaxy 的 API）之间的 TLS 握手失败，命令无法继续执行。

临时规避：NODE_TLS_REJECT_UNAUTHORIZED=0

官方给出的临时 workaround 是设置环境变量 NODE_TLS_REJECT_UNAUTHORIZED=0，让 Node.js 跳过对证书的授权校验，例如：

NODE_TLS_REJECT_UNAUTHORIZED=0 meteor deploy

在需要多个命令的场景下，也可以先导出再执行：

export NODE_TLS_REJECT_UNAUTHORIZED=0
meteor deploy
meteor list

老发行版与 CI 管道的同类问题

如果你的本地开发机或 CI 流水线运行的是较老的发行版（如 Ubuntu 16 及更早版本），即使 Meteor 版本较新，操作系统自身的根证书信任库也可能缺少 ISRG Root X1，从而触发同样的 TLS 失败。这种情况下官方建议：

• 升级操作系统发行版，或
• 更新本地根证书信任库（具体方法因发行版而异，如 Debian/Ubuntu 系使用 update-ca-certificates，RHEL/CentOS 系使用 update-ca-trust）。

再次强调：这类问题源于所访问资源的 Let's Encrypt 证书信任链更替，并非 Meteor 或 Galaxy 自身的故障。

此 workaround 的安全代价

设置 NODE_TLS_REJECT_UNAUTHORIZED=0 意味着任意 SSL 证书都会被接受，中间人攻击可以轻易冒充目标服务器。因此它只能作为临时应急手段，绝不应长期保留在生产环境中。

故障二：服务端出站请求失败

如果 Meteor 应用在服务端访问外部资源，而目标主机使用 Let's Encrypt 证书、应用又运行在旧版 Meteor 上，那么出站 HTTPS 请求同样会因证书链问题失败。解决办法是把 NODE_TLS_REJECT_UNAUTHORIZED 注入服务端进程的环境变量，而不是仅作用于 CLI。

本地/自托管服务器

在启动应用前注入环境变量：

NODE_TLS_REJECT_UNAUTHORIZED=0 meteor run
# 或
export NODE_TLS_REJECT_UNAUTHORIZED=0
node main.js

从源码层面看，Meteor 工具链本身也支持通过环境变量向应用进程传递 Node 选项：tools/runners/run-app.js 中 getNodeOptionsFromEnvironment 会解析 SERVER_NODE_OPTIONS 环境变量，并以其作为启动应用进程的 Node 参数，对应解析器实现在 tools/runners/run-app.js。因此你还可以把 TLS 相关选项（若需兼容 Node 的 NODE_OPTIONS 形式）统一放进 SERVER_NODE_OPTIONS 传递给应用进程。

Galaxy 托管：通过 settings 文件配置

如果你使用 Galaxy，只需在部署 settings 文件中加入以下内容即可为服务端进程注入环境变量：

{
  "galaxy.meteor.com": {
    "env": {
      "NODE_TLS_REJECT_UNAUTHORIZED": "0"
    }
  }
}

安全警示与根治建议

原文档明确提示：官方不推荐长期使用该 workaround。关闭证书校验后，任何 SSL 证书都会被接受，你的应用将暴露于严重的安全风险之下。最佳做法是：

• 将 Meteor 升级到最新版本；
• 至少升级到 Meteor 1.9——它是首个内置 Node.js 12 的版本，Node.js 12 携带的 OpenSSL 已能正确处理 ISRG Root X1 信任链；
• 对照 SECURITY.md 的受支持版本列表确认你的版本仍在维护周期内。当前仓库的 SECURITY.md 显示：3.x 获得全部安全修复，2.x 仅重大安全问题（维护至 2025-07），1.12.x 及更早版本已不再支持。如果你的应用不在受支持列表中，应尽快迁移。

故障三：客户端无法访问你的网站

如前所述，Galaxy 会自动为所有客户（即访问你网站的终端用户）签发 Let's Encrypt 证书。如果依赖旧客户端访问你的网站，这部分用户将因为信任链问题无法建立 HTTPS 连接，这同样是证书生命周期更替的必然结果，而非 Meteor/Galaxy 的缺陷。

方案 A：更换证书提供商并上传自定义证书

如果 Let's Encrypt 证书对你的客户端群体不适用，可以从其他证书提供商购买证书，然后将自定义证书上传到 Galaxy。

方案 B：用 certbot 指定备用信任链手动签发

也可以继续使用 Let's Encrypt，但通过 certbot 手动生成证书，并显式指定首选信任链为 ISRG Root X1，同时使用 DNS 质询：

sudo certbot certonly --manual --preferred-chain "ISRG Root X1" --preferred-challenges dns

这样生成的证书链以 ISRG Root X1 为锚点，不依赖已过期的 DST Root CA X3。关于证书链更详细的信息，可查阅 Let's Encrypt 官方的证书链说明文档。

Galaxy 上传自定义证书的要求

使用 Galaxy 上传自定义证书时，需要遵循 Galaxy 官方加密文档中的要求与步骤。核心约束是：Galaxy 只接受 .pem 格式的证书，与 nginx 使用的证书格式一致（即包含完整证书链的 PEM 文本文件）。

已知无法正常工作的客户端清单

基于社区反馈与工程经验，以下是已知受影响的客户端（非穷尽列表，但具有代表性）：

客户端	影响情况
Mac OS X 10.12.1 之前的版本	除内置了根证书链的 Firefox 外，所有浏览器均无法访问
Node.js 10 之前的 HTTP 请求	覆盖所有 Meteor v1.9 之前的版本（1.9 之前内置 Node < 10）
使用 OpenSSL 1.0.2 及更早版本的任何客户端	证书校验默认失败

判定依据：上述客户端均不包含 ISRG Root X1 且无法完成对新信任链的自动获取，因此在 DST Root CA X3 过期后默认不可用。

建议的处置顺序与长期方案

综合原文档与仓库现状，推荐按以下顺序处理证书过期问题：

1. 立即止血：在 CLI、服务端进程（或 Galaxy settings）中临时设置 NODE_TLS_REJECT_UNAUTHORIZED=0，恢复构建、部署与运行能力；
2. 评估影响面：对照上文兼容性表格确认受影响的客户端范围，必要时用 certbot 的 --preferred-chain "ISRG Root X1" 重新签发证书，或更换证书提供商并上传 .pem 自定义证书到 Galaxy；
3. 根治升级：尽快将 Meteor 升级到受支持版本（参考 SECURITY.md，当前为 3.x 与维护中的 2.x），并同步升级操作系统根证书信任库，随后移除 NODE_TLS_REJECT_UNAUTHORIZED 环境变量，恢复完整的 TLS 证书校验。

需要再次重申：上述故障的根本原因是 Let's Encrypt 根证书的到期轮换，是证书生态的正常生命周期，而不是 Meteor 或 Galaxy 的缺陷。只要客户端信任库跟上 ISRG Root X1、运行时升级到包含新 OpenSSL 的版本，问题即可从根源上消除。

【免费下载链接】meteor Meteor, the JavaScript App Platform 项目地址: https://gitcode.com/gh_mirrors/me/meteor