做 AI 应用总在重复造轮子？我开源了一个 FastAPI 后端脚手架，开箱即用

项目地址：github.com/NotBeBarnon... 觉得有用的话，欢迎点个 ⭐ Star，这是对我最大的鼓励！

一、先说为什么做这个东西

最近半年，我陆陆续续做了五六个 AI 相关的后端项目------有 RAG 知识库、有 Agent 编排平台、有企业内部 AI 助手、有 SaaS 类 AI 产品。每次启动新项目，第一件事不是写业务，而是：

搭用户注册登录
写 JWT 鉴权中间件
做分页查询
配 LLM 接口对接
搞流式响应（SSE）
接消息队列做异步
写健康检查和监控指标
配 Docker 和 CI/CD

这些东西每次都要重新写一遍，或者从上个项目里 copy-paste 然后改改。烦不烦？真的烦。

市面上 FastAPI 的脚手架不是没有，但问题很明显：

太通用 ------ 就是一个 CRUD 架子，做 AI 应用需要的 LLM 网关、流式输出、MCP 工具生态一个没有
太重 ------ full-stack-fastapi-postgresql 那种，前后端一把梭，但我只要后端
玩具级 ------ 看起来功能齐全，一上生产就崩，数据库挂了全瘫、Redis 连不上直接 500
依赖臃肿 ------ 装一堆 SDK，langchain 这个包那个包，最后打个镜像 1 个 G

我想要的是一个：拿过来就能写 AI 业务、上生产不出事、不想用的模块能直接删掉不影响其他模块 的脚手架。

于是就有了 fastapi-ai-starter。

二、它有什么？一句话说清楚

面向 AI 应用的生产级 FastAPI 后端脚手架 ------ 用户鉴权 / 资源 CRUD / LLM 多模型网关 / MCP 工具 / SSE 流式 / Kafka 消息 / 任务调度 / 可观测性，全部开箱即用。

3 分钟启动，直接写业务。

一张图看全貌：

具体来说，有这 10 个模块：

🔀 LLM 多模型网关

不用装 OpenAI SDK、Anthropic SDK，直接用 httpx 走 OpenAI 兼容协议。支持：

多 provider 配置（DeepSeek / OpenAI / Claude / Ollama / 本地模型）
优先级降级（DeepSeek 挂了自动切 OpenAI）
指数退避重试
Token 用量统计 + 成本估算
同步对话 + 流式对话统一接口

python 复制代码

# 三行代码接入对话
from my_tools.llm_tools.gateway import llm_gateway
response = await llm_gateway.chat([{"role":"user","content":"你好"}])

🔧 MCP 工具生态

内置 MCP（Model Context Protocol）注册中心 + JSON-RPC Server，支持 SSE 和 stdio 两种传输方式。Claude Desktop、Cline 等 AI 客户端可以直接连进来调用你的工具。

简单说：你写的后端工具，AI 可以直接调用。

🌊 SSE 流式响应

不是简单的 yield，而是封装了两种模式：

SSEStream：队列模式 + 生成器模式，适用于推送进度、通知
LLMStreamer：OpenAI 兼容的流式输出格式，前端可以直接用 EventSource 对接

python 复制代码

@router.get("/sse/chat")
async def stream_chat(req: ChatRequest):
    return llm_gateway.stream(req.messages)
# 前端：new EventSource('/sse/chat') 直接拿流式数据

📨 Kafka 消息链路

启动时自动建 topic（不用手动去 Kafka 创建）
断线自动重连（生产环境 Kafka 重启是常态）
EventPublisher 封装发布逻辑，注入 app.state
回调式后台消费 worker，继承基类注册回调就行

⏰ 后台任务调度

TaskManager 注册中心，支持 interval 和 cron 两种模式。亮点是：

SSE 实时订阅任务进度（长任务做进度推送很有用）
可以手动触发、暂停、恢复
状态持久跟踪

📊 可观测性

三类健康探针 + Prometheus 指标 + trace_id 链路追踪：

/monitor/healthz------存活探针（进程活着就 200）
/monitor/readyz------就绪探针（DB/Redis/Kafka/LLM 全链路检查）
/monitor/metrics------Prometheus 指标（P50/P95/P99 延迟、Token 用量、请求成本）

每个请求自动注入 X-Request-ID，日志全链路 trace_id 贯穿，排查问题不再大海捞针。

🔐 安全与限流

零依赖 JWT：HS256 自己实现，不装 python-jose 那些重包
API Key 鉴权：多 key 管理 + 角色校验
Redis Lua 滑动窗口限流：内存兜底，Redis 挂了限流不失效
全部依赖注入，用 Depends(require_jwt_role("admin")) 一行搞定权限

👤 用户体系

PBKDF2-SHA256 密码哈希（stdlib 实现，零依赖），注册/登录/改密/JWT Bearer 鉴权/admin 角色控制。关键设计：

DB 不可用优雅降级：数据库挂了，应用照启动，用户接口返回 503，其他模块正常工作
字段零泄露：所有响应模型不含 password_hash
防时序攻击：常量时间比较密码哈希

📦 资源 CRUD 模板

这是我觉得最实用的部分------一个标准的 CRUD 样板，包含：

统一分页工具 PageResult[T] + PaginationParams + OrderByParams
Owner 权限隔离（普通用户只能看自己的数据，越权返回 404 防枚举）
管理员全量查询（/resource/admin/beams，支持 owner_id 过滤）
部分更新（PUT 只改传入字段）
DB 优雅降级（所有 ORM 调用走 _safe() 包装）

新增业务模块时，复制 resource 目录，替换 Model/Schema/路由前缀即可，分页和降级模式直接复用。

🚀 DevOps

多阶段 Dockerfile（依赖层缓存，改代码不重装依赖）
docker-compose 一键编排（MySQL + Redis + 可选 Kafka）
GitHub Actions：每次 push 自动 ruff lint + 74 项单元测试

三、零侵入设计，想删就删

这是我最在意的设计原则：模块之间零耦合，不用就删。

所有工具类都在 src/my_tools/ 下，每个目录一个独立能力：

bash 复制代码

src/my_tools/
├── llm_tools/       # LLM 网关（不需要 LLM？直接删）
├── mcp_tools/       # MCP 协议（不需要 MCP？直接删）
├── sse_tools/       # SSE 流式（不需要流式？直接删）
├── kafka_tools/     # Kafka（用 RabbitMQ？删掉换成自己的）
├── security_tools/  # JWT / API Key / 限流
├── redis_tools/     # Redis 客户端（单连接/哨兵双模式）
├── observability/   # 健康探针 / 指标 / 追踪
├── schedule_tasks/  # 任务调度
└── tortoise_tools/  # 分页 / 自定义字段

不需要 Kafka？删掉 kafka_tools/ 目录，Kafka 相关配置不填，lifespan 自动跳过初始化，完全不影响其他模块。

同理，不需要 MCP？删目录就行。不需要 LLM 网关？删目录就行。

四、快速开始

Docker 一键启动（30 秒）

shell 复制代码

git clone https://github.com/NotBeBarnon/fastapi-ai-starter.git
cd fastapi-ai-starter
docker compose up -d

启动后访问：

你想看什么	地址
📖 Swagger API 文档	http://localhost:8080/api/sample/docs
❤️ 存活检查	http://localhost:8080/api/sample/monitor/healthz
✅ 就绪探针	http://localhost:8080/api/sample/monitor/readyz
📊 Prometheus 指标	http://localhost:8080/api/sample/metrics

本地开发

shell 复制代码

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
python main.py run --reload

试一下 LLM 对话

shell 复制代码

# 修改 pyproject.toml 里的 [myproject.llm.providers] 配上 API Key
curl -X POST http://localhost:8080/api/sample/llm/chat \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"用一句话介绍 FastAPI"}]}'

试一下流式输出

shell 复制代码

curl http://localhost:8080/api/sample/sse/chat?message=hello
# 会看到 data: 开头的流式 chunk，前端 EventSource 直接消费

五、技术选型

领域	选型	为什么
Python	3.12	asyncio.timeout、tomllib 内置，性能更好
Web 框架	FastAPI ≥ 0.115	lifespan 管理、自动文档、异步原生支持
序列化	Pydantic v2	性能比 v1 快 5-50 倍，pydantic-settings 配置管理
ORM	tortoise-orm + aerich	Django 风格的 async ORM，迁移工具 aerich 够用
缓存	redis-py ≥ 5.1	官方 asyncio 支持，哨兵模式原生
消息	aiokafka	异步 Kafka 客户端，社区维护活跃
LLM	httpx 直连	零 SDK 依赖，任何 OpenAI 兼容协议直接打

全程不装 langchain、不装 llama-index、不装 openai SDK------这些东西在生产环境都是累赘，我只要最薄的一层 HTTP 调用。

六、生产级细节（这部分是真踩过坑的）

脚手架里很多细节看起来不起眼，但都是线上踩过坑之后加上去的：

DB 不可用优雅降级：数据库挂了不 crash，用户接口返回 503，健康接口照样 200，K8s 不会误杀 pod
Redis 哨兵自动重连：Redis 主从切换时客户端自动感知，不丢请求
Kafka 自动建 topic + 自动重连：Kafka 重启或 topic 不存在不会导致应用启动失败
限流 Lua 脚本 + 内存兜底：Redis 挂了限流降级到本地内存，不会被打穿
JWT 密钥必须改：默认密钥启动时打 WARNING，生产环境忘记改会有提示
CORS 安全配置：生产环境默认不放开跨域，需要显式配置
请求 ID 全链路追踪：每个请求生成 X-Request-ID，日志、错误响应、下游调用全部携带
74 项单元测试：每个模块都有 SQLite 内存库单元测试，CI 自动跑

七、适合谁用？

✅ 适合：

想做 AI 应用后端（RAG / Agent / AI SaaS / 内部 AI 工具）但不想从零搭基建的开发者
需要一个能直接上生产的 FastAPI 项目模板
讨厌框架"帮你做太多"，想要可裁剪、可控的脚手架
团队要统一后端规范（分页/鉴权/错误处理/监控）

❌ 不适合：

要前后端一体全栈方案的（出门左转 full-stack-fastapi）
不打算自己写代码，想拿过来直接部署一个成品的（这是脚手架，不是产品）
Python 版本低于 3.12 的（强依赖 3.12 特性）

八、最后

我之前也用过很多脚手架，有的功能齐全但太重，有的精简但生产级特性缺东少西。做这个项目的初衷就是：让做 AI 应用的开发者，打开 IDE 就能直接写业务逻辑，不用再花一周搭基建。

如果你也在做 AI 应用后端，希望这个脚手架能帮你省点时间。

GitHub 地址 ：github.com/NotBeBarnon...

欢迎 Star ⭐、提 Issue、提 PR！有问题评论区交流~

如果你对某个模块的实现细节感兴趣，我可以单独写文章展开讲------比如零依赖 JWT 怎么实现、LLM 网关的降级策略怎么写、DB 优雅降级的模式怎么设计。想看哪个，评论区告诉我。