starlette 本身不直接处理 tls 解密,配置 https 的标准做法是将其置于反向代理(如 nginx、caddy)或 asgi 服务器(如 uvicorn、hypercorn)之后。若需让应用感知到 https 连接以生成正确 url,应设置 append_slash 或使用 proxyheadersmiddleware 来解析代理传递的协议头。对于纯 asgi 环境,推荐使用支持 ssl 的服务器启动应用,并在代码中通过中间件确保请求对象标记为安全。

如何在 Starlette 应用中启用 ProxyHeadersMiddleware?
在 Starlette 中启用 ProxyHeadersMiddleware 可以让应用信任来自反向代理的 X-Forwarded-Proto 和 X-Forwarded-Port 头部,从而正确识别 HTTPS 请求。只需在实例化 Starlette 应用时将该中间件加入即可,这样 request.url.scheme 将返回 https。

from starlette.applications import Starlette
from starlette.middleware import Middleware
from starlette.middleware.httpsredirect import HTTPSRedirectMiddleware
from starlette.middleware.trustedhost import TrustedHostMiddleware
from starlette.middleware.proxy import ProxyHeadersMiddleware
# 定义中间件列表
middlewares = [
Middleware(ProxyHeadersMiddleware),
Middleware(TrustedHostMiddleware, allowed_hosts=['example.com', '*.example.com']),
]
app = Starlette(middleware=middlewares)
@app.route("/")
async def homepage(request):
# 如果配置了 ProxyHeadersMiddleware 且代理发送了正确头部
# request.url.scheme 将是 'https'
scheme = request.url.scheme
return {"scheme": scheme}
预期结果:当请求通过 Nginx 转发并携带 X-Forwarded-Proto: https 时,request.url.scheme 返回 'https'。若未配置该中间件,即使客户端使用 HTTPS,scheme 也可能显示为 'http'(取决于服务器监听端口)。
Starlette 1.5.1 是轻量级 Python ASGI 框架与工具集,提供路由、请求响应、中间件、WebSocket 和后台任务等组件,适合构建异步 Web 服务。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理依赖;运行应用时还需配置 ASGI 服务器。
如何强制重定向 HTTP 到 HTTPS?
若希望自动将所有 HTTP 请求重定向至 HTTPS,可使用 HTTPSRedirectMiddleware。该中间件会检查请求协议,若非 HTTPS 则返回 307 临时重定向响应。注意:此中间件通常与 ProxyHeadersMiddleware 配合使用,以便准确判断原始请求是否为 HTTPS。

from starlette.applications import Starlette
from starlette.middleware import Middleware
from starlette.middleware.httpsredirect import HTTPSRedirectMiddleware
from starlette.middleware.proxy import ProxyHeadersMiddleware
middlewares = [
Middleware(ProxyHeadersMiddleware),
Middleware(HTTPSRedirectMiddleware),
]
app = Starlette(middleware=middlewares)
@app.route("/secure")
async def secure_page(request):
return {"message": "This is served over HTTPS"}
预期结果:用户访问 http://example.com/secure 时,浏览器收到 307 响应并重定向至 https://example.com/secure。若请求已是 HTTPS,则正常处理路由。
当 X-Forwarded-Proto 缺失时 request.url.scheme 返回什么?
当 X-Forwarded-Proto 头部缺失或未配置 ProxyHeadersMiddleware 时,request.url.scheme 返回 ASGI 服务器实际监听的协议。例如,若 Uvicorn 监听 0.0.0.0:8000(HTTP),则 scheme 为 'http';若监听 0.0.0.0:8443 并启用 SSL,则 scheme 为 'https'。此时应用无法得知客户端原始协议,可能导致 URL 生成错误。

















