FastAPI+Uvicorn环境下mTLS配置失败求助

一、Uvicorn启动参数检查 #

mTLS要求服务器强制验证客户端证书，且指定用于验证的CA根证书：

• 必须添加--ssl-verify-mode require参数，否则服务器不会主动要求客户端提供证书，浏览器自然不会弹出选择窗口
• 必须通过--ssl-ca-certs指定签发客户端证书的CA根证书文件路径
• 完整启动命令示例（开启debug日志便于排查）：

uvicorn main:app --host 0.0.0.0 --port 443 --ssl-keyfile ./server.key --ssl-certfile ./server.crt --ssl-ca-certs ./ca.crt --ssl-verify-mode require --log-level debug

二、CFSSL证书生成配置检查 #

Postman的NO_START_LINE错误大多和证书格式或用途不匹配有关：

1. 证书格式验证：
   • 用cat命令查看client.crt、client.key、ca.crt，确认是标准PEM格式，必须包含-----BEGIN CERTIFICATE-----和-----END CERTIFICATE-----（密钥文件对应-----BEGIN PRIVATE KEY-----）
   • 排除文件被意外编辑、换行符损坏或编码错误的情况
2. 客户端证书用途配置：
   • 确保CFSSL配置文件的client profile包含client auth用途，示例配置：

   {
     "signing": {
       "default": {
         "expiry": "8760h"
       },
       "profiles": {
         "server": {
           "usages": ["signing", "key encipherment", "server auth"],
           "expiry": "8760h"
         },
         "client": {
           "usages": ["signing", "key encipherment", "client auth"],
           "expiry": "8760h"
         }
       }
     }
   }
   

   • 生成客户端证书时必须指定client profile，比如：

   cfssl gencert -ca ca.crt -ca-key ca.key -config config.json -profile=client client.json | cfssljson -bare client
   

三、Chrome证书选择窗口不弹出的解决 #

1. 导入CA根证书到Chrome信任列表：
   打开Chrome设置 → 隐私和安全 → 安全 → 管理证书 → 受信任的根证书颁发机构 → 导入ca.crt，完成后重启Chrome
2. 确保服务器证书域名匹配：
   服务器证书（server.crt）的CN或SAN必须和访问的域名一致，否则Chrome会先提示证书不可信，无法触发mTLS证书选择流程

四、Postman调用错误排查 #

1. Error: error:0900006e:PEM routines:OPENSSL_internal:NO_START_LINE：
   • 检查Postman证书配置：设置 → Certificates → 添加客户端证书，确认CRT文件选client.crt、KEY文件选client.key，不要混淆
   • 如果生成证书时设置了密码，必须在Passphrase字段填写对应密码
2. Error: socket hang up：
   • 查看Uvicorn debug日志，确认是否有证书验证失败提示（比如客户端证书非指定CA签发、证书过期等）
   • 确保Postman使用的客户端证书由启动命令中--ssl-ca-certs指定的CA签发，且证书未过期

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