Python gRPC客户端SSL证书验证CERTIFICATE_VERIFY_FAILED报错求解

该错误不是gRPC Python客户端的原生缺陷，属于证书配置与gRPC TLS校验规则不匹配导致的常见问题，大量开发者在grpcio 1.37及以上版本升级后都遇到过同类问题。

核心触发原因 #

• 你使用的openssl 1.1.1版本默认生成的自签名证书仅填充了Common Name(CN)字段，从grpcio 1.37版本开始，gRPC底层TLS栈完全遵循RFC 2818规范，不再将Common Name作为服务端身份校验的依据，必须在证书的Subject Alternative Name(SAN)字段中配置客户端连接时使用的服务端域名/IP
• 你生成证书的命令未追加SAN配置，导致客户端校验证书时无法匹配目标服务地址，直接抛出证书验证失败错误

修复步骤 #

1. 生成带SAN字段的自签名证书 #

首先创建san.cnf配置文件，按照实际场景替换配置值：

[req]
default_bits = 4096
prompt = no
default_md = sha512
distinguished_name = dn
x509_extensions = v3_req

[dn]
C = CN
ST = 你的省份
L = 你的城市
O = 你的组织名称
OU = 你的部门名称
CN = 客户端连接时使用的服务端地址，例如192.168.1.100、grpc.example.com

[v3_req]
subjectAltName = @alt_names
extendedKeyUsage = serverAuth

[alt_names]
DNS.1 = 用域名连接时填对应域名，例如grpc.example.com
IP.1 = 用IP连接时填对应IP，例如192.168.1.100

使用该配置文件生成证书，替换原有生成命令：
openssl req -newkey rsa:4096 -nodes -sha512 -x509 -days 3650 -config san.cnf -out server.crt -keyout server.key

生成完成后可以用命令验证SAN是否生效：
openssl x509 -in server.crt -text -noout | grep -A 1 "Subject Alternative Name"
输出内容包含你配置的IP/域名即为配置正常。

2. 核对服务端与客户端配置 #

• 服务端参考配置：

import grpc
from concurrent import futures

# 加载服务端证书密钥
with open("server.key", "rb") as f:
    server_key = f.read()
with open("server.crt", "rb") as f:
    server_cert = f.read()

server_creds = grpc.ssl_server_credentials(((server_key, server_cert),))
server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))
# 注意监听地址要放通外部访问，不要仅绑定127.0.0.1
server.add_secure_port("0.0.0.0:50051", server_creds)
server.start()
server.wait_for_termination()

• 客户端参考配置：

import grpc

# 加载服务端根证书
with open("server.crt", "rb") as f:
    root_cert = f.read()

creds = grpc.ssl_channel_credentials(root_certificates=root_cert)
# 连接地址必须和证书SAN中配置的IP/域名完全一致，不能混用IP和域名
channel = grpc.secure_channel("192.168.1.100:50051", creds)

# 临时测试可添加以下选项跳过SAN校验，生产环境禁止使用
# channel = grpc.secure_channel("192.168.1.100:50051", creds, options=[("grpc.ssl_target_name_override", "证书中配置的CN值")])

其他排查点 #

• 用telnet或nc命令先验证服务端端口连通性，排除防火墙拦截问题
• 确认客户端加载的server.crt和服务端使用的是同一文件，无路径错误或文件篡改问题
• 若配置双向TLS，需确认客户端证书的CA已被服务端信任，客户端证书的字段也符合校验规则

内容的提问来源于stack exchange，提问作者Gaurav Garg