1. FastAPI 生产环境偶发 500 的真实排查现场FastAPI 项目跑起来很爽类型提示、自动文档、异步支持都到位但一旦上了生产最让人头皮发麻的不是那种必现的崩溃而是偶发的 500 Internal Server Error。你刷新一下好了过一会儿又冒出来一条日志里只有一行500 Internal Server Error连个像样的堆栈都没有。这种问题如果只靠猜基本等于大海捞针。我先把结论摆出来FastAPI 的 500 大致分三类根因——代码层异常Pydantic 校验、空值、索引越界、上游依赖异常数据库连接、Redis、第三方 API 超时、鉴权与配置异常Token 解析失败、环境变量缺失、中间件拦截后处理出错。这三类的排查路径完全不同混在一起看日志只会越看越乱。这篇就按「先能看见错误 → 再分层定位 → 最后复现验证」的顺序把每一步都写成你可以直接抄的配置和脚本。适合谁看已经在用 FastAPI 写接口、准备或已经上生产、被偶发 500 折磨过的后端同学。你不需要很深的运维背景但得能改main.py、能看 uvicorn 日志、能跑一条 curl。先说一个我踩过的坑。之前有个项目接口偶尔 500日志里啥都没有最后发现是 Pydantic 模型里多了一个必传字段而调用方根本没传校验直接抛异常被全局异常处理器吞掉了。这类问题如果日志采集没配好你永远看不到真正的异常栈。所以第一步不是改代码是让错误「现形」。排查偶发 500 的核心思路是把「看不见的异常」变成「看得见的堆栈」再把堆栈按来源分类。下面从日志采集开始一层层往下拆。整个过程我会结合统一的 API 通道来复现请求链路因为很多 500 其实是上游调用超时或鉴权失败引起的把请求链路固定下来复现会稳定很多。2. 让 uvicorn 日志与异常栈完整落盘FastAPI 500 排查的日志采集配置FastAPI 500 排查第一步是确保异常栈不被吞。默认情况下uvicorn 会把未捕获异常打到 stderr但如果你加了全局异常处理器app.exception_handler(Exception)又没在里面logger.exception(...)那异常就真的消失了。这是偶发 500「无日志」最常见的原因。先看一个反面例子很多人是这么写的app.exception_handler(Exception) async def global_exception_handler(request: Request, exc: Exception): return JSONResponse(status_code500, content{detail: Internal Server Error})这段代码把异常吞得干干净净你只知道 500不知道为啥。正确做法是把异常栈完整记录同时保留对外的统一响应import logging from fastapi import FastAPI, Request from fastapi.responses import JSONResponse logger logging.getLogger(app.errors) app FastAPI() app.exception_handler(Exception) async def global_exception_handler(request: Request, exc: Exception): logger.exception( unhandled error path%s method%s, request.url.path, request.method, ) return JSONResponse(status_code500, content{detail: Internal Server Error})logger.exception会自动带上exc_infoTrue把完整堆栈写进日志。这一步做完你至少能看到异常类型和出错行号。接下来配置日志格式让每条日志都带时间、级别、模块和堆栈。用dictConfig统一管理避免到处basicConfigimport logging.config LOGGING_CONFIG { version: 1, disable_existing_loggers: False, formatters: { default: { format: %(asctime)s | %(levelname)s | %(name)s | %(message)s, }, }, handlers: { console: { class: logging.StreamHandler, formatter: default, }, file: { class: logging.handlers.RotatingFileHandler, filename: logs/app.log, maxBytes: 10 * 1024 * 1024, backupCount: 5, formatter: default, encoding: utf-8, }, }, root: { level: INFO, handlers: [console, file], }, } logging.config.dictConfig(LOGGING_CONFIG)注意RotatingFileHandler要保证logs/目录存在否则启动就报错。生产环境建议把日志同时输出到 stdout方便容器采集。uvicorn 启动时也要打开访问日志和错误日志uvicorn main:app --host 0.0.0.0 --port 8000 --log-level info --access-log如果你用 gunicorn uvicorn worker配置要写在 gunicorn 的--access-logfile和--error-logfile里别指望 uvicorn 参数生效。日志落盘后用grep快速定位异常类型grep -E ValidationError|IntegrityError|OperationalError|TimeoutError|ConnectionError logs/app.log | tail -n 50这一步能帮你把 500 按异常类型分堆。数据库类、业务逻辑类、外部依赖类堆栈长得完全不一样。分完堆再决定往哪个方向查。提示日志里如果只有500 Internal Server Error而没有堆栈八成是异常处理器吞了异常或者异常发生在中间件里、还没进到路由就被拦截了。中间件的异常要单独处理见下一节。3. 可复制的中间件与依赖注入配置定位鉴权失败与上游超时FastAPI 的中间件和依赖注入是 500 的高发区因为它们在请求进入路由前后执行异常容易被吞。尤其是鉴权中间件Token 解析失败后如果处理不当会直接抛 500 而不是 401。先看一个典型的鉴权中间件写法问题出在decode_token抛异常后没有捕获from fastapi import Request from starlette.middleware.base import BaseHTTPMiddleware class AuthMiddleware(BaseHTTPMiddleware): async def dispatch(self, request: Request, call_next): token request.headers.get(Authorization, ).replace(Bearer , ) payload decode_token(token) # 这里可能抛异常 request.state.user payload return await call_next(request)decode_token遇到过期或格式错误的 Token 会抛JWTError中间件没捕获直接 500。正确做法是捕获后返回 401from jose import JWTError class AuthMiddleware(BaseHTTPMiddleware): async def dispatch(self, request: Request, call_next): token request.headers.get(Authorization, ).replace(Bearer , ) try: payload decode_token(token) except JWTError as e: logger.warning(token decode failed: %s, e) return JSONResponse(status_code401, content{detail: Invalid token}) request.state.user payload return await call_next(request)这样鉴权失败会返回 401而不是混进 500 里。区分开之后你的 500 日志就干净多了。再说依赖注入。FastAPI 的Depends里如果抛异常同样会变成 500。比如数据库会话依赖from fastapi import Depends from sqlalchemy.orm import Session def get_db(): db SessionLocal() try: yield db finally: db.close()如果SessionLocal()连接数据库失败异常会在依赖里抛出变成 500。建议在依赖里加超时和重试并把连接错误单独记录def get_db(): try: db SessionLocal() except OperationalError as e: logger.error(db connect failed: %s, e) raise HTTPException(status_code503, detailDatabase unavailable) try: yield db finally: db.close()把数据库不可用映射成 503而不是 500这样监控告警也能区分开。现在说上游调用。很多 FastAPI 项目会调用外部 API如果用的是统一通道配置集中管理会省很多事。下面是一份可复制的配置片段把 Base URL、Key、Model ID 三件套放在环境变量里避免硬编码{ api: { base_url: https://taotoken.net/api, api_key: ${TAOTOKEN_API_KEY}, model_id: ${TAOTOKEN_MODEL_ID}, timeout: 30, max_retries: 2 } }对应的 Python 调用封装重点是超时和异常分类import httpx from tenacity import retry, stop_after_attempt, wait_exponential retry(stopstop_after_attempt(2), waitwait_exponential(multiplier1, max8)) async def call_upstream(payload: dict): async with httpx.AsyncClient(timeout30) as client: resp await client.post( f{settings.api.base_url}/v1/chat/completions, headers{Authorization: fBearer {settings.api.api_key}}, jsonpayload, ) if resp.status_code 401: logger.error(upstream auth failed: %s, resp.text) raise HTTPException(status_code502, detailUpstream auth failed) if resp.status_code 500: logger.error(upstream 5xx: %s, resp.text) raise HTTPException(status_code502, detailUpstream error) return resp.json()这样上游超时、鉴权失败、5xx 都会被分类记录不会和本地代码异常混在一起。实测下来把上游异常映射成 502本地异常保留 500排查效率会高很多。注意httpx.AsyncClient一定要设timeout默认没有超时上游卡住会拖垮整个请求。生产环境建议 10 到 30 秒按业务定。4. 最小复现脚本与验证请求确认 500 根因的三步动作定位到可疑点后别急着改代码先写一个最小复现脚本把问题稳定复现出来。偶发 500 最怕的就是「改完不知道好没好」能稳定复现问题就解决了一半。第一步用 curl 直接打接口带上完整请求头看返回码和响应体curl -i -X POST http://127.0.0.1:8000/api/v1/items \ -H Authorization: Bearer $TOKEN \ -H Content-Type: application/json \ -d {name: test, scope: read}如果返回 500立刻去看logs/app.log最后几行对照时间戳找堆栈。这一步能确认是请求本身触发的还是环境问题。第二步写一个 pytest 最小复现把出错的请求固定下来from fastapi.testclient import TestClient from main import app client TestClient(app, raise_server_exceptionsTrue) def test_reproduce_500(): resp client.post( /api/v1/items, headers{Authorization: Bearer test-token}, json{name: test, scope: read}, ) assert resp.status_code 200, resp.text关键在raise_server_exceptionsTrue这样异常会直接抛出来而不是被转成 500 响应。你能在 pytest 输出里看到完整堆栈比翻日志快得多。第三步如果怀疑是上游调用问题单独写一个脚本验证上游连通性和鉴权import asyncio import httpx async def check_upstream(): async with httpx.AsyncClient(timeout15) as client: resp await client.get( https://taotoken.net/api/v1/models, headers{Authorization: fBearer {API_KEY}}, ) print(status:, resp.status_code) print(body:, resp.text[:500]) asyncio.run(check_upstream())返回 200 说明 Key 和通道正常返回 401 说明鉴权有问题返回超时说明网络或上游不稳定。这一步能把「上游问题」和「本地代码问题」彻底分开。验证成功的标志很明确本地复现脚本从 500 变成 200日志里不再出现对应异常栈上游检查脚本返回 200。三个都满足才算真正修好。如果你需要长期跑这类上游调用建议用 Coding Plan 把调用额度集中管理避免 Key 散落在各个服务里。模型对话入口可以用来快速验证某个模型 ID 是否可用省得在代码里反复试。5. 本篇常见错排查401、local proxy failed、reading choices 与 OAuth 报错对照这一节把排查过程中最常撞见的几个报错列出来对照着看能省不少时间。401 Unauthorized先分清是本地鉴权还是上游鉴权。本地 401 看中间件日志token decode failed上游 401 看upstream auth failed。上游 401 通常是 Key 失效、Key 写错、或者 Base URL 配错。检查三件套是否齐全Base URL 用https://taotoken.net/apiKey 从 API Keys 页面获取Model ID 要和请求体里的model字段一致。三者缺一不可。local proxy failed这个报错一般出现在本地调试时请求发不出去。先确认base_url没有多余斜杠https://taotoken.net/api后面拼/v1/...时不要写成//v1。再确认本地网络能正常访问外网curl -v看握手是否成功。如果用了自定义 DNS 或 hosts检查有没有把域名解析错。Error reading choices / reading choices这类报错通常出现在解析上游响应时响应体不是预期的 JSON 结构。原因可能是上游返回了错误页、超时返回空体、或者流式响应被中途截断。排查方法是在调用封装里打印resp.status_code和resp.text[:500]先看原始响应长什么样再决定是加重试还是改解析逻辑。流式场景要确认streamTrue时逐块读取别一次性resp.json()。OAuth 相关报错如果项目接了 OAuth 登录回调阶段 500 多半是state校验失败或code换 token 时上游报错。检查回调 URL 是否和注册时一致client_id、client_secret是否配对。OAuth 的异常也要单独捕获映射成 401 或 400别让它变成 500。Pydantic ValidationError这是最常见的 500 来源。表现是请求体字段缺失、类型不符、或者模型里定义了必传字段但调用方没传。排查时看堆栈里的字段名对照 Pydantic 模型定义。如果是数据库字段和模型字段不一致比如模型里多了个access_scope但数据库没这列要么删字段要么给默认值。建议在模型里对可选字段用Optional加默认值避免校验直接炸。sqlalchemy IntegrityError / OperationalErrorIntegrityError 多是唯一约束冲突或非空约束看堆栈里的约束名OperationalError 多是连接问题看数据库是否可达、连接池是否耗尽。连接池耗尽的表现是偶发 500且日志里有QueuePool limit字样调大pool_size和max_overflow能缓解。AttributeError: NoneType object has no attribute典型的空值问题。查询返回 None 后直接取属性。排查时看堆栈行号加if x is None判断或者用getattr带默认值。把这几类报错和日志里的关键字对应起来你基本能在几分钟内判断根因方向。剩下的就是改代码和验证。6. 把请求链路固定下来FastAPI 500 排查的长期实践偶发 500 排查完之后更重要的是别让它再悄悄发生。我的做法是把请求链路固定下来所有上游调用走统一通道Base URL、Key、Model ID 集中配置超时和重试统一封装异常分类记录。这样下次再出 500日志里直接能看到是本地异常还是上游异常不用再从头猜。具体落地三件事。第一把配置抽到环境变量或配置文件代码里只读不写死。第二所有外部调用加超时和重试异常映射成明确的 HTTP 状态码。第三日志里带上请求 ID方便串联一次请求的所有日志。请求 ID 可以用中间件生成import uuid class RequestIDMiddleware(BaseHTTPMiddleware): async def dispatch(self, request: Request, call_next): request_id request.headers.get(X-Request-ID, str(uuid.uuid4())) request.state.request_id request_id response await call_next(request) response.headers[X-Request-ID] request_id return response然后在日志格式里加上%(request_id)s一次请求的所有日志就能串起来。排查偶发问题时按请求 ID 过滤比按时间翻日志快得多。如果你还在用散落的 Key 和硬编码的 URL建议先把接入文档过一遍把三件套配齐。需要长期跑编码类任务的话Coding Plan 能把额度集中管理省得每个服务单独配 Key。验证模型是否可用直接用模型对话试一下最快。最后留一个实用技巧给 500 加个告警日志里出现unhandled error就触发通知别等用户反馈。偶发问题最怕的就是「发生了但没人知道」有了告警你至少能在它变成大问题之前介入。