企业官网建设流程全解析

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_code=500, 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_code=500, content={"detail": "Internal Server Error"})

logger.exception会自动带上exc_info=True，把完整堆栈写进日志。这一步做完，你至少能看到异常类型和出错行号。

接下来配置日志格式，让每条日志都带时间、级别、模块和堆栈。用dictConfig统一管理，避免到处basicConfig：

import 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。正确做法是捕获后返回 401：

from 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_code=401, 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_code=503, detail="Database 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(stop=stop_after_attempt(2), wait=wait_exponential(multiplier=1, max=8)) async def call_upstream(payload: dict): async with httpx.AsyncClient(timeout=30) as client: resp = await client.post( f"{settings.api.base_url}/v1/chat/completions", headers={"Authorization": f"Bearer {settings.api.api_key}"}, json=payload, ) if resp.status_code == 401: logger.error("upstream auth failed: %s", resp.text) raise HTTPException(status_code=502, detail="Upstream auth failed") if resp.status_code >= 500: logger.error("upstream 5xx: %s", resp.text) raise HTTPException(status_code=502, detail="Upstream 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_exceptions=True) 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_exceptions=True，这样异常会直接抛出来，而不是被转成 500 响应。你能在 pytest 输出里看到完整堆栈，比翻日志快得多。

第三步，如果怀疑是上游调用问题，单独写一个脚本验证上游连通性和鉴权：

import asyncio import httpx async def check_upstream(): async with httpx.AsyncClient(timeout=15) as client: resp = await client.get( "https://taotoken.net/api/v1/models", headers={"Authorization": f"Bearer {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/api，Key 从 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]，先看原始响应长什么样，再决定是加重试还是改解析逻辑。流式场景要确认stream=True时逐块读取，别一次性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 / OperationalError：IntegrityError 多是唯一约束冲突或非空约束，看堆栈里的约束名；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就触发通知，别等用户反馈。偶发问题最怕的就是「发生了但没人知道」，有了告警，你至少能在它变成大问题之前介入。