$ssl_client_verify 变量精确反映客户端证书的完整校验结果，取值为 success、failed:reason 或 none，分别表示校验通过、校验失败（含具体原因）及未提供证书，需在日志中明确区分以精准定位 mtls 问题。
在 Nginx 中，$ssl_client_verify 是一个内置变量，用于反映客户端证书在 SSL/TLS 握手阶段的校验结果。它不表示“是否发送了证书”，而是明确表达“证书是否通过了可信 CA 验证、是否过期、是否被吊销等完整校验流程”。正确使用该变量记录日志，能精准定位双向 TLS（mTLS）中证书失败的真实原因。
理解 $ssl_client_verify 的取值含义
该变量在每次请求中返回以下字符串之一（注意大小写和拼写）：
- SUCCESS：客户端提供了有效证书，且经配置的 CA 证书链验证通过（签名、有效期、用途、CRL/OCSP 等均合规）
-
FAILED:reason：证书存在可识别的错误，例如
FAILED:No client certificate received、FAILED:certificate revoked、FAILED:unable to get local issuer certificate - NONE：客户端未提供证书（此时不触发证书校验，也不等于校验失败）
⚠️ 注意：NONE 和 FAILED 语义不同。前者是“没交卷”，后者是“交了但不及格”。日志中必须区分二者，否则无法判断是客户端配置缺失还是服务端信任链/策略问题。
在 access_log 中记录真实校验状态
直接在 log_format 中引用该变量即可，无需额外模块或指令：
log_format cert_log '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent" '
'cert_status="$ssl_client_verify" '
'cert_subject="$ssl_client_s_dn" '
'cert_issuer="$ssl_client_i_dn"';
access_log /var/log/nginx/mtls_access.log cert_log;
这样每条日志都会带出校验结果和证书主体信息，便于按 cert_status 字段聚合分析。例如用 awk 或 Loki 查询：cert_status=~"FAILED.*revoked" 可快速发现吊销证书攻击尝试。
结合 if 判断做条件日志或拦截（谨慎使用）
若需对特定校验结果做差异化处理（如仅记录失败详情、或拒绝 FAILED 请求），可用 map 构建更清晰的状态码映射，避免在日志格式中嵌套复杂逻辑：
map $ssl_client_verify $cert_valid {
default 0;
"SUCCESS" 1;
~^FAILED: 0;
"NONE" 0;
}
<h1>拒绝非 SUCCESS 请求（启用 mTLS 强制模式）</h1><p>if ($cert_valid = 0) {
return 403 "Client certificate verification failed or missing";
}
</p>
⚠️ 注意：Nginx 官方不推荐在 location 中大量使用 if，建议优先通过 ssl_verify_client on; + 后端应用校验兜底；日志记录本身应始终开启，不依赖 if。
排查常见误判场景
即使配置看似正确，$ssl_client_verify 也可能返回意料之外的值，常见原因包括：
- CA 证书文件路径错误或权限不足（Nginx worker 进程无法读取
ssl_client_certificate指定的 PEM 文件） - 客户端证书链不完整（只发了终端证书，未附带中间 CA），导致
FAILED:unable to get issuer certificate - 启用了
ssl_crl但 CRL 文件过期或不可达，部分失败会归为FAILED:unable to get certificate CRL - 时间不同步：客户端或服务端系统时间偏差超过证书有效期容忍范围（通常 5 分钟），引发
FAILED:certificate has expired或FAILED:certificate is not yet valid
验证方法：用 openssl s_client -connect host:port -cert client.crt -key client.key -CAfile ca.crt 手动测试，并观察 OpenSSL 自身的 verify result 输出，与 Nginx 日志比对。
