Uvicorn怎么配置SSL证书-Python教程-PHP中文网

Uvicorn配置SSL只需--ssl-keyfile和--ssl-certfile两个参数，端口需设为443，私钥带密码须加--ssl-keyfile-password，生产环境推荐Nginx终止HTTPS。

uvicorn怎么配置ssl证书

Uvicorn 配置 SSL 证书只需传入两个关键文件路径：私钥（ssl_keyfile）和证书（ssl_certfile），其余参数按需补充，不填也能跑 HTTPS。

命令行启动时直接加参数最简单

开发或轻量部署时，用 uvicorn 命令行加 --ssl-keyfile 和 --ssl-certfile 就能启用 HTTPS：

uvicorn main:app --ssl-keyfile=./key.pem --ssl-certfile=./cert.pem --port 443

注意点：

--port 必须设为 443（或其他非 80 端口），否则浏览器默认走 HTTP，不会触发 TLS 握手
路径必须是相对当前工作目录的可读路径，不能是 Python 包内路径（比如 from pkg import cert 这种方式无效）
如果私钥有密码，必须加 --ssl-keyfile-password=xxx，否则启动失败并报错 ValueError: Could not deserialize key data
证书文件（.pem 或 .crt）必须包含完整证书链（尤其 Let's Encrypt 的 fullchain.pem），只放域名证书会触发浏览器“NET::ERR_CERT_AUTHORITY_INVALID”

代码中调用 `uvicorn.run()` 时传参要注意顺序和条件

在 if __name__ == "__main__": 块里写配置更灵活，但容易漏掉关键约束：

import uvicorn
if __name__ == "__main__":
    uvicorn.run(
        "main:app",
        host="0.0.0.0",
        port=443,
        ssl_keyfile="./key.pem",
        ssl_certfile="./cert.pem",
        # 注意：reload=True 和 workers > 1 不能同时用，否则报错 OSError: Cannot run reloadable server with multiple workers
    )

常见坑：

ssl_keyfile 和 ssl_certfile 是关键字参数名，不是 ssl-keyfile（带横线的是命令行写法）
若启用了 reload=True，就不能设 workers；反之亦然——这是 Uvicorn 的进程模型限制，不是 FastAPI 的问题
Windows 下路径反斜杠要转义或用原始字符串，比如 r"C:\certs\key.pem"，否则可能报 FileNotFoundError

生产环境别裸跑 Uvicorn SSL，该交棒给 Nginx

Uvicorn 自带 SSL 能力，但只适合单机、无反向代理、低并发场景。真实生产中：

Uvicorn 0.52.1

Uvicorn 0.52.1 是 Python ASGI Web 服务器，提供异步应用服务及 WebSocket 支持，常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包，可使用 pip 安装，并由包管理器处理所需依赖。

下载

证书续期（如 Let's Encrypt）很难热更新，Uvicorn 不支持运行时重载证书，每次都要重启服务
不支持 SNI（Server Name Indication），一个 IP 只能绑一个域名的证书
无法做客户端证书校验（双向 SSL）后把信息透传给 FastAPI —— Uvicorn 会终止 TLS，但不提供 request.client.cert 接口
性能上，Nginx 的 SSL 卸载 + 连接复用 + 缓存能力远强于纯 Python 实现

典型做法是让 Nginx 终止 HTTPS，再以 HTTP 明文转发到 Uvicorn（比如 http://127.0.0.1:8000），所有 SSL 相关逻辑（包括 OCSP Stapling、HSTS、ALPN）都由 Nginx 管理。

自签名证书调试时怎么生成才不被浏览器拦

开发阶段用自签名证书，但 Chrome/Firefox 默认拒绝 localhost 以外的域名，且要求 SAN（Subject Alternative Name）字段：

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 \
  -subj "/CN=localhost" -addext "subjectAltName = DNS:localhost,IP:127.0.0.1"

关键点：

必须加 -addext "subjectAltName = ..."，否则现代浏览器直接显示 NET::ERR_CERT_COMMON_NAME_INVALID
CN 设为 localhost，配合 127.0.0.1 的 SAN 才能绕过大部分警告
证书生成后，需手动导入系统或浏览器信任库（macOS 在钥匙串、Windows 在“受信任的根证书颁发机构”），否则仍会提示不安全

真正上线前，别依赖自签名；Let's Encrypt 的 certbot 一条命令就能搞定可信证书，Uvicorn 只需换两个文件路径。