Uvicorn直接支持HTTPS,但必须同时提供--ssl-certfile和--ssl-keyfile,路径需正确可读;私钥带密码须加--ssl-keyfile-password;推荐用uvicorn而非fastapi run启动;生产环境建议Nginx终止SSL。

Uvicorn 直接支持 HTTPS,不需要 Nginx 或其他反向代理就能跑起来,但必须同时提供 ssl_certfile 和 ssl_keyfile,缺一不可。
证书和私钥文件路径必须正确且可读
Uvicorn 启动时会尝试加载这两个文件,路径错误、权限不足或格式不对都会直接报错退出,常见现象是:
-
OSError: [Errno 2] No such file or directory: 'cert.pem'—— 路径写错,建议用绝对路径,比如/home/user/app/cert.pem -
ssl.SSLError: PEM lib—— 私钥文件被加密但没传--ssl-keyfile-password,或证书/私钥内容损坏(比如复制时多空行、混入 Windows 换行符) -
PermissionError: [Errno 13] Permission denied—— 私钥文件权限太宽松(Linux/macOS 下不能是 644,得是 600)
验证方式:用 openssl x509 -in cert.pem -text -noout 和 openssl rsa -in key.pem -check -noout 分别检查证书和私钥是否合法。
命令行启动时参数名不能写错
Uvicorn 的 SSL 参数名是固定且区分大小写的,容易手误写成 --ssl-cert 或 --cert-file 这类不存在的参数,结果被忽略,服务仍走 HTTP。
- 正确写法只有:
--ssl-certfile和--ssl-keyfile - 私钥带密码时,必须加:
--ssl-keyfile-password(值不加引号也行,但含空格或特殊字符时需引起来) - 不推荐用
fastapi run命令配 SSL,它底层调的是 Uvicorn,但参数透传不稳定;直接用uvicorn更可控
最小可行命令示例:
uvicorn main:app --host 0.0.0.0 --port 443 --ssl-certfile ./fullchain.pem --ssl-keyfile ./privkey.pem
TLS 版本和加密套件影响兼容性
默认情况下 Uvicorn 使用系统 OpenSSL 支持的最高 TLS 版本(2026 年主流是 TLS 1.3),但某些旧客户端(如部分嵌入式设备或老 Android App)可能只支持 TLS 1.2,这时需要显式降级:
- 强制 TLS 1.2:
--ssl-version 2(注意:这里的2对应 TLS 1.2,3才是 TLS 1.3) - 指定加密套件可提升安全性或绕过某些握手失败:
--ssl-ciphers "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256" - 不建议禁用 TLS 1.3,除非明确有兼容性问题;也不要保留
SSLv3、TLSv1这类已废弃协议
如果用 Let's Encrypt 证书,fullchain.pem 必须包含完整证书链(域名证书 + 中间 CA),否则 iOS 或 Java 客户端可能校验失败。
生产环境别裸跑 Uvicorn HTTPS
Uvicorn 自带 SSL 能力适合快速验证或低流量场景,但它不处理连接缓冲、HTTP/2 多路复用、TLS 会话复用优化等,高并发下性能不如 Nginx 终止 SSL。
- 真实生产部署中,更常见的是 Nginx 做 TLS 终止,Uvicorn 只监听本地 HTTP(如
127.0.0.1:8000) - 若坚持用 Uvicorn 直连 HTTPS,务必加
--workers N(N ≥ CPU 核数),否则单进程无法充分利用多核 -
--reload和--workers互斥,开发时用--reload,上线必须关掉并启用多进程
最容易被忽略的一点:Uvicorn 的 SSL 不支持 OCSP Stapling 和 ALPN 协议协商(如 HTTP/3),这些需要上层代理或专用 QUIC 服务器支持。


















