TLS 协商组怎么验收：Node.js getEphemeralKeyInfo 与 ecdhCurve 的兼容边界

线上 HTTPS 服务升级 Node.js 版本后，哪怕 TLS 握手能正常走完，也不代表客户端和服务端实际协商出的 TLS 协商组就是你预期的配置。Node.js TLS API 把协商组结果暴露到了观测接口里，完全可以用来补全握手环节的验收记录，但是别用它直接替代证书、协议版本和密码套件的常规校验步骤。

最小验收路径是：让客户端完成一次真实 TLS 握手，读取 getEphemeralKeyInfo()，记录 type 和 name，再把结果与 ecdhCurve、协议版本和回滚版本一起对照。看到 TLSGroup 只能说明协商组信息可以被观测，不能单独证明整条连接的安全性符合要求。

先分清三个概念：TLSGroup、密码套件和证书

一次 TLS 连接流程里，证书负责做身份校验，密码套件描述对称加密算法和握手流程的组合，Supported Group 则专门参与握手阶段的密钥协商。三类信息都会出现在排障日志里，但各自代表的含义完全不同。Node.js 的协商组报告能力，解决的就是之前“最终选中了哪个密钥协商组”这条关键证据不够直观的问题。

官方发布说明把“report negotiated TLS groups”列为 26.5.0 的次版本兼容更新内容。TLS 官方文档进一步补充说明，当临时密钥对象可用时，getEphemeralKeyInfo() 可以返回 type: 'TLSGroup' 以及协商出的 name。

用 getEphemeralKeyInfo() 记录一次真实握手

别只在进程启动时打印 Node 版本号就完事。把观测逻辑放到客户端连接完全建立完成之后，连同协议版本和密码套件一起记录下来，才能精准确认这条连接实际使用的协商参数。

import tls from 'node:tls';

const socket = tls.connect({ host: 'example.com', port: 443, servername: 'example.com' }, () => {
  const group = socket.getEphemeralKeyInfo();
  console.log({
    protocol: socket.getProtocol(),
    cipher: socket.getCipher().standardName,
    groupType: group?.type,
    groupName: group?.name
  });
  socket.end();
});

socket.on('error', (error) => console.error('tls-check', error.code));

如果返回对象的 type 是 TLSGroup，name 就是协商出的 TLS Supported Group 名称。不同的 OpenSSL 构建版本、对端设备的支持能力和自定义配置，都可能返回不同的组名；所以日志字段要做好空值兼容，不要把某一个组名硬编码成唯一的成功判断条件。

ecdhCurve 怎么改：先看供给范围，再看实际结果

ecdhCurve 不是能强制指定最终组名的快捷开关。Node.js TLS 文档明确说明，它的作用是配置 TLS Supported Groups 的供给或接受范围，设置为 auto 时会交由底层 TLS 栈自动选择适配的组。生产环境做配置变更之前，先记录当前生效的默认值、协议版本和常见对端设备的类型。

const socket = tls.connect({
  host: 'example.com',
  port: 443,
  servername: 'example.com',
  ecdhCurve: 'X25519:P-256'
}, () => {
  const info = socket.getEphemeralKeyInfo();
  console.log('configured-groups', 'X25519:P-256');
  console.log('negotiated-group', info?.type, info?.name);
  socket.end();
});

这里要明确区分“配置允许的范围”和“握手最终选中的结果”。如果对端不支持你配置的首选组，连接会自动回落到列表里其他兼容的组；如果配置的可选范围过窄，还可能直接在握手阶段抛出异常。验收环节要覆盖默认配置、显式自定义配置和回滚配置三条路径。

把握手证据接入日志：哪些字段值得长期保留

建议在连接级别保留四类核心信息：getProtocol() 的协议版本、getCipher().standardName 的密码套件、getEphemeralKeyInfo() 的类型与名称，以及两端的运行时版本。这些信息完全足够排查“升级后协商逻辑是否出现变化”这类问题，又不会把证书全文和敏感握手数据直接写入普通业务日志。

日志里不要直接凭组名来判定安全等级高低。更稳妥的做法是：先按照团队内部的 TLS 基线判断结果是否在允许范围内，再检查新版本上线后结果有没有偏离基线；如果出现偏离，再依次从客户端参数、服务端配置和 OpenSSL 版本几个维度逐项排查定位。

升级验收表：看到结果后如何做决定

这类 TLS 观测能力建议先在测试集群或者灰度连接池里跑通验证。真正要上线的目标不是用某个听起来更安全的组名，而是当协商结果出现异常变化时，团队手里已经有基线、日志和可重复操作的回滚步骤。

常见问题

type: TLSGroup 代表什么？

它表示当前返回结果来自 TLS Supported Group 的协商过程，name 就是实际最终选中的组名。它既不等于证书名称，也不属于密码套件的属性。

getEphemeralKeyInfo() 返回空对象怎么办？

先确认当前操作的是客户端 TLS socket，同时记录对应的协议版本、对端类型和底层 OpenSSL 构建信息；服务端 socket 或者非临时密钥的业务场景下，不需要强行要求必须返回组名。

把 ecdhCurve 设成一个固定值就能锁定协商结果吗？

没法完全保证。对端支持能力、协议版本和底层 TLS 栈的版本都会影响最终结果；更稳妥的做法是先限制允许的组范围，再通过真实握手的日志结果做最终验收。

升级后只看 HTTPS 返回 200 够吗？

完全不够。至少同步记录协议版本、密码套件、协商组和失败路径四类信息，才能明确区分“连接本身能通”和“安全基线和之前保持一致”两种情况。

这项能力的价值就是补全了之前缺失的握手环节证据。先在测试环境记录 Node.js 下的协议、密码套件和 TLS 协商组结果，再和旧运行时及回滚配置的结果做对照，升级动作是否可以推进，就会从主观的“感觉没问题”变成可复核的明确结论。