fastapi-react-admin 是什么
fastapi-react-admin 是一个开源(MIT)的中后台底座:后端 FastAPI,前端 React 19 + shadcn/ui,内部系统迟早要做的那些东西都已经做好了——用户、角色、部门、行级数据权限、审批、文件、消息通知、定时任务、AI 助手。拿去之后在上面写自己的业务页面。
为什么在 AI 时代还要做一个后台底座?
Section titled “为什么在 AI 时代还要做一个后台底座?”因为 AI 让要做的系统变多了,而每个新系统开头都在重复同一批活。排不上队的小工具值得做了,跑了多年的老系统也该换了——可登录、权限、组织架构、审批、文件、通知,每次都得从头再来。
这个项目起步于公司里几套 Java + Vue 2 小系统的重构。我们没有在旧架构上修补,而是用 FastAPI + React 19 从头搭了一遍,再把每次都要重做的部分沉淀成底座:下一个系统,从写业务开始。
一个仓库里有什么?
Section titled “一个仓库里有什么?”后端、Web 管理后台、桌面端模板、移动端模板和文档站,都在同一个 pnpm + turbo monorepo 里:pnpm install:all 一次装好,pnpm dev 一条命令起前后端。
apps/├── api 后端 · FastAPI + Celery├── web Web 管理后台 · React 19├── desktop 桌面端模板 · Electron├── mobile 移动端模板 · Expo / React Native└── docs 文档站 · Astropackages/ 依赖单向:i18n / api ← ui ← platform ← web├── api 前后端类型契约,由 OpenAPI 生成├── i18n 中英文案├── ui 组件库,不含业务,可整包带走└── platform 权限、多页签、业务页面- Web 管理后台是主体,开箱即用。
- 桌面端模板直接加载 Web 的构建产物,只补浏览器做不到的事:静默打印、本地硬件、自动更新。见桌面端与移动端。
- 移动端模板是原生界面,和 Web 共用接口类型(
@admin/api)与语言包(@admin/i18n)。 - 分层有约束。 依赖严格单向,写在各包的
package.json里,pnpm arch:check在 CI 里把关。
为什么说它适合和 AI 一起写代码?
Section titled “为什么说它适合和 AI 一起写代码?”因为 AI 改代码很快,而这里每一处改动都有东西兜底:
- 测试兜底。 AI 一次改十几个文件很常见,人工点一遍点不过来。后端 1400+ 条 pytest 连真实数据库和 Redis,前端 150+ 条 Playwright 跑真实浏览器,不用 mock,CI 每次全量跑;失败的用例带截图和录像,E2E 报告公开。
- 类型兜底。 前后端契约由后端的 OpenAPI 生成(
packages/api/src/schema.d.ts)。移动端的每个请求都从它推断类型,接口改了而页面没跟上,pnpm typecheck直接报错;网页端还在迁移,请求的返回类型目前在各调用点手写(见开发者工具)。 - 规矩写给 AI 看。 仓库里 50 多份按目录拆分的
CLAUDE.md/AGENTS.md记着实测踩过的坑和硬纪律,编码助手改到哪个目录,就读到哪一份。 - 后端就在 AI 生态里。 Python + FastAPI,内置的 AI 助手基于 pydantic-ai。
- 要做企业内部系统(OA、ERP 式后台、运营管理台),后端想用 Python、前端想用 React 的团队。
- 已经在用微软技术栈的团队:SQL Server 在这里是一等公民,每次 CI 都和 PostgreSQL 一起跑全量测试。
- 权限要求不止「这个角色能打开哪些菜单」的团队——比如部门经理只能看到本部门的数据。
- 除了 Web 还要出桌面端或手机端的团队:两个模板已经接好登录、接口类型和语言包,从模板起步,不用从零搭。
- 在用 AI 编码助手、又担心它把东西改坏的团队。
和常见的后台模板有什么不同
Section titled “和常见的后台模板有什么不同”| 常见模板 | fastapi-react-admin | |
|---|---|---|
| 权限粒度 | 菜单 + 按钮 | 菜单 + 按钮 + 数据范围——角色决定一个人能看到哪几行 |
| 多页签 | Vue 有 keep-alive 天然支持;React 模板大多没有,或者切走就丢状态 | React 19 <Activity>:打开的页签一直挂载,DOM 和状态切换后都还在 |
| 组件底座 | 多数还停在 shadcn 旧的 Radix 版本 | 已经是 shadcn 现在默认的 Base UI(零 @radix-ui 引用),另有一个能直接复制代码的组件沙箱 |
| 数据库 | 通常只支持一种 | 三选一:PostgreSQL(默认)· SQL Server · MySQL |
| 业务功能 | 用户 / 角色 / 菜单 | 另有审批流、AI 助手、开放平台、文件与存储、消息通知、定时任务 |
| 测试 | 大多没有,或者只有带 mock 的组件单测 | 后端 1400+ 条、端到端浏览器 150+ 条,连真实依赖,不用 mock |
用了哪些技术
Section titled “用了哪些技术”| 前端 | React 19 · TypeScript 6 · Vite 8 · TanStack Router / Query / Table v9 · Tailwind CSS 4 · shadcn/ui(Base UI)· zustand · Tiptap 3 · i18next |
| 后端 | FastAPI · Pydantic 2 · SQLAlchemy 2(异步)· Alembic · Redis · Celery · Socket.IO · Apache OpenDAL · pydantic-ai |
| 数据库 | PostgreSQL · SQL Server · MySQL |
| 客户端 | Electron 桌面端 · Expo / React Native 移动端 |
| 工程 | pnpm + turbo monorepo · uv · ruff · pytest · Playwright · GitHub Actions |
- 不是低代码平台。 业务页面用 React 写,接口用 FastAPI 写;底座提供的是外壳、权限模型和公共组件。
- 不是托管服务。 需要自己部署,见部署。
- 不是一次性的脚手架。 1.0 起按 semver 发版,开放接口、Webhook、数据库迁移链、插件接口、配置键都有兼容承诺;升级前先看更新记录。
后端最初 fork 自 fastapi-best-architecture(FBA)。三层结构(api → service → crud)、插件机制、RBAC 与数据权限模型都是 FBA 的设计,FBA 的版权声明保留在 apps/api/LICENSE。SQL Server 支持是本项目加的,上游明确不合并这部分,所以是永久分叉,只 cherry-pick 上游的安全补丁。
前端、桌面端和移动端,以及大部分业务功能(审批、AI 助手、开放平台、文件存储、消息渠道路由)是本项目自己写的。
-
DeepWiki 项目解析 —— 通过 AI 对话快速了解仓库结构和代码。
-
快速开始——五条命令在本地跑起来。
-
功能总览——按领域列出所有功能。
-
在线演示——
admin/123456。