如何修复Python Uvicorn服务器返回“426 Upgrade Required”的问题？

问题场景 #

本地运行Python Uvicorn应用时，服务器能正常启动并连接数据库，但所有请求均返回“Upgrade Required”，同事本地运行则完全正常。

启动日志：

INFO | uvicorn.server:serve:75 - Started server process [49720]
INFO | uvicorn.lifespan.on:startup:47 - Waiting for application startup.
INFO | databases.core:connect:83 - Connected to database postgresql+asyncpg://localhost:5432/faethm_core
INFO | uvicorn.lifespan.on:startup:61 - Application startup complete.
INFO | uvicorn.server:_log_started_message:209 - Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

测试请求（curl）：

curl --request GET \
  --url http://0.0.0.0:8000/health \
  --header 'Content-Type: application/json'

返回结果：

Upgrade Required

已尝试重启服务器/电脑、更换请求工具、添加HTTP/2升级头、改用HTTPS，均无效。

核心原因 #

问题本质是Uvicorn的HTTP协议配置与客户端请求协议不兼容，常见两种触发场景：

1. 应用被强制配置为仅支持HTTP/2（无TLS时要求h2c协议），但客户端默认用HTTP/1.1发起请求，服务器要求升级协议，因此返回“Upgrade Required”。
2. 本地Uvicorn及依赖版本与同事不一致，新版本的默认配置或依赖（如httptools）导致协议处理逻辑变化。

解决方案 #

1. 检查并修正Uvicorn启动配置 #

查看src/main.py中的启动代码，确认是否存在强制指定HTTP/2的配置：

• 错误示例（强制仅用HTTP/2）：

  uvicorn.run(app, host="0.0.0.0", port=8000, http="h2")
  

• 修改为兼容HTTP/1.1的配置（默认兼容模式）：

  # 自动适配HTTP/1.1和HTTP/2
  uvicorn.run(app, host="0.0.0.0", port=8000, http="auto")
  # 或明确指定使用HTTP/1.1
  uvicorn.run(app, host="0.0.0.0", port=8000, http="httptools")
  

2. 对齐Uvicorn及依赖版本 #

和同事对比本地依赖版本，消除版本差异：

1. 查看当前Uvicorn版本：

   pip show uvicorn
   

2. 安装与同事一致的版本：

   pip install uvicorn==<同事的版本号>
   

3. 同步相关依赖版本：

   pip freeze | grep -E "uvicorn|httptools|uvloop"
   

   安装与同事相同版本的httptools、uvloop等依赖。

3. 若需强制HTTP/2，调整客户端请求方式 #

如果应用确实需要仅支持HTTP/2，客户端需发送符合要求的请求：

• 无TLS的h2c协议：curl添加--http2-prior-knowledge参数

  curl --request GET \
    --url http://0.0.0.0:8000/health \
    --header 'Content-Type: application/json' \
    --http2-prior-knowledge
  

• 带TLS的HTTP/2：配置SSL证书后，客户端会自动协商HTTP/2协议。

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