Nginx反向代理需显式配置proxy_set_header透传mTLS证书信息，关键变量包括$ssl_client_cert、$ssl_client_s_dn、$ssl_client_verify等，且仅在ssl_verify_client on且验证成功时有效。
当 Nginx 作为反向代理，后端服务需要验证客户端证书（mTLS）时，Nginx 默认不会自动把原始客户端证书信息透传给上游。必须显式配置 proxy_set_header，将相关证书字段以 HTTP 头形式转发过去。
关键 Header：传递证书核心信息
Nginx 提供一组内置变量，可直接用于 proxy_set_header，对应 TLS 握手阶段获取的客户端证书内容：
- $ssl_client_cert：Base64 编码的 PEM 格式完整证书（含 BEGIN/END 块），适合后端直接解析；
-
$ssl_client_s_dn：证书主题 DN（Distinguished Name），如
CN=alice,OU=dev,O=example； - $ssl_client_i_dn：证书颁发者 DN；
- $ssl_client_serial：证书序列号（十六进制字符串）；
-
$ssl_client_verify：校验结果，值为
SUCCESS、FAILED:xxx或NONE。
典型配置示例
在 location 或 server 块中添加如下设置：
WebChat Voice Proxy
下载
⚠️ 已弃用 — 该技能已拆分为两个独立技能，以提升模块化程度：**webchat-https-proxy**（HTTPS/WSS 反向代理）和 **webchat-voi...**
location /api/ {
proxy_pass https://backend;
proxy_set_header X-SSL-Client-Cert $ssl_client_cert;
proxy_set_header X-SSL-Client-DN $ssl_client_s_dn;
proxy_set_header X-SSL-Client-Verify $ssl_client_verify;
proxy_set_header X-Forwarded-For $remote_addr;
}
注意：$ssl_client_cert 变量仅在启用 ssl_verify_client on; 且客户端成功提供并验证证书后才有效。若未启用双向认证或验证失败，该变量为空字符串。
后端接收与使用建议
后端服务（如 Spring Boot、Node.js、Go）需主动读取这些自定义 Header：
- 若用
X-SSL-Client-Cert，注意其值含换行符和空格，需做 URL 安全处理（如 Base64Url 编码）或换行转义（如替换\n为\r\n）再还原为 PEM； - 推荐优先使用
X-SSL-Client-DN做身份初筛，配合X-SSL-Client-Verify判断是否可信； - 避免仅依赖 DN 字段做权限控制——应结合证书链校验、OCSP/CRL 状态及白名单指纹（如
$ssl_client_fingerprint）增强安全性。
调试与验证技巧
快速确认证书信息是否正确透传：
- 临时 upstream 设为 echo 服务（如
proxy_pass http://127.0.0.1:8000，后端打印所有 headers）； - 用 curl 携带证书发起请求：
curl -k --cert client.pem --key client.key https://your-domain/api/test； - 检查 Nginx error log 是否出现
client SSL certificate verify error，定位验证失败环节。
