Repository navigation
第一个正式版：权限、审批、文件、消息、AI 助手、开放接口一套做齐，三种数据库、三端 🎉
fastapi-react-admin 是一套开箱即用的中后台底座（FastAPI + React 19）。1.0.0 是第一个正式版：功能范围定型，开放接口、Webhook、数据库迁移链、插件接口和配置键从这一版起按 semver 承诺不随手破坏。从 2026 年 8 月第一行代码到今天，经过 147 个 PR、21 个 0.x 版本。
在线演示 https://fra.wubunan.com/sign-in · 文档 https://yilecoding.github.io/fastapi-react-admin/ · 快速开始：docker compose up
简要
- 权限与组织： 菜单 / 按钮 / 数据范围三层 RBAC，加上对每个查询生效的行级数据权限。
- 登录与安全： 手机验证码登录、二次验证（TOTP + 恢复码）、OAuth2；会话按端限数、空闲与绝对超时、被踢下线说明原因。
- 工作区： 可编辑布局的工作台、切换不丢状态的多页签、⌘K 命令面板、深色模式、中英双语、每人自己的时区。
- 审批流： 表单设计器 + 流程树，同意 / 驳回 / 转交 / 退回 / 加签 / 超时自动处理，还有 AI 预审和帮填表单。
- AI 助手： 工具调用受当前用户的权限和数据范围约束，写操作先预演再确认，全程审计；MCP 网关对外开放只读能力。
- 文件、消息与开放： S3 兼容存储与断点续传、公告与通知渠道路由（邮件 / 短信 / 群机器人）、AK/SK 开放接口 + 三语言 SDK + Webhook 事件订阅。
- 三种数据库、三端： PostgreSQL / SQL Server / MySQL 同一条迁移链；Web、桌面端（三平台安装包 + 自动更新）、移动端（预览版）。
- 测试兜底： 后端 1492 条测试（PostgreSQL 与 SQL Server 各一整套）、浏览器端到端 160 条、前端单元 175 条，全部是 CI 必过闸门。
兼容与升级说明
- 从 0.13.0 升级： 没有数据库迁移，不用改配置。这一版的改动只有 README 功能表补齐、移动端标成预览版、夏令时结论写成测试和版本号。
- 从更早的 0.x 升级： 照常
pnpm db:upgrade，任何已发布版本都能直接升到 1.0.0。 - 兼容承诺正式生效： 破坏开放接口 / Webhook / 迁移链 / 插件接口 / 配置键任何一条都会升主版本号，细则见下方「兼容承诺」。
- 移动端是预览版： 不在兼容承诺内；审批和绑定手机号排在 1.0 之后（#224）。
整体功能
权限与组织
- RBAC：菜单 / 按钮 / 数据范围三层权限，前后端用同一套权限码，没有权限的按钮直接不出现
- 行级数据权限：数据范围 + 数据规则（按部门、本人、自定义条件），对每个查询生效；41 个测试账号逐一验证过
- 部门树 · 用户 · 角色 · 权限矩阵（一屏勾完一个角色的全部菜单与按钮）
登录与安全
- 图形验证码 · 失败锁定 · 密码策略（历史密码、过期）· 手机验证码登录 · 二次验证（TOTP + 恢复码）· OAuth2（GitHub / Google）
- 会话管理：会话 ID 稳定、空闲超时 + 绝对上限、按端（Web / 桌面 / 移动）限制会话数、被踢下线时说明原因、管理员强制下线
- access token 只放内存、页面加载静默恢复；日志自动脱敏
工作区
- 可编辑的工作台：以待办为中心，卡片按权限出现，布局按人存在服务端、换设备也在
- 多页签：切换不丢状态（筛选、滚动、表单都保留）、固定 / 拖拽 / 重新加载，刷新后恢复
- 命令面板 ⌘K · 快捷键 · 功能引导 · 主题色 / 圆角 / 页签外观 · 深色模式 · 每人自己的时区 · 中英双语
- 统一的页面规范（1.0 前做过一轮全站整改）：表格单元格、工具栏顺序、行操作 ⋯ 菜单、卡片页、报错与重试、窄屏 / 手机适配
导入导出
- 服务端导出 xlsx / csv：按当前筛选或勾选的行，大批量转后台、完成发站内消息，防公式注入
- 通用导入：带下拉的模板 · 预览校验 · 只新增 / 新增并更新 / 只更新 · 错误报告 · 全部成功才落库；一份文件建整棵部门树
文件与存储
- 文件管理器 + 在线预览（PDF / Word / Excel / PPT / 图片 / 音视频 / 压缩包）
- 本地磁盘 + S3 兼容存储（Apache OpenDAL）· 预签名直连下载 · 秒传 · 分片上传与断点续传 · 回收站
- 可以嵌进任何业务页面的附件面板
审批流
- 表单设计器 · 流程树（审批 / 抄送 / 条件分支）· 发起前预览会走到哪些人
- 同意 / 驳回 / 转交 / 退回 / 拿回 / 加签 · 超时提醒与自动处理 · 草稿 · 加急 · 离职交接 · 流程监控
- AI 能力：AI 预审（给出建议与依据）· 上传材料帮填表单 · AI 审批节点 · AI 生成流程
AI 助手
- 整页对话 + 任意页面的侧滑抽屉，接 OpenAI 兼容的模型供应商
- 工具调用受权限和数据范围约束：AI 看不到、改不了当前用户本来就没权限的东西
- 写操作先预演、再由人确认；全部调用留审计日志
- MCP 网关（只读）：外部 AI 客户端（Claude Desktop、Cursor 等）凭 MCP 凭据接入，查询能力同样受该用户的权限与数据范围约束
消息与通知
- 站内消息（实时推送）· 消息中心
- 通知公告：富文本 + 附件 · 发布范围 · 定时发布 · 置顶 / 级别 / 有效期 · 登录后弹窗与必须确认 · 顶部横幅 · 登录页公告 · 阅读统计
- 通知渠道路由：邮件 / 短信 / 飞书·钉钉·企业微信群机器人，按事件配策略，每次投递有记录
- 短信：阿里云 / 腾讯云
能力开放
- AK/SK 签名的开放接口
/api/open/v1/*：scope · IP 白名单 · 防重放 · 限流 · 调用日志 · 增量同步 - Python / Node / Java 三语言 SDK
- Webhook 事件订阅：Standard Webhooks 签名 · 失败重试 · 投递记录 · 批量重发 · 密钥轮换期间新旧双签
定时任务与运维
- 在线调度（cron 预览）· 执行记录 · 参数配置 · 数据字典 · 登录 / 操作日志
- 服务器与 Redis 监控 · 在线用户 · 统一健康检查
/api/health/status（api / 数据库 / Redis / 调度器 / worker）· 发新版提示 - 插件机制：AI、审批、公告、通知、短信、邮件、开放接口、OAuth2 等都是插件，可以按需装卸
多端
- 桌面端（Electron）：Windows / macOS / Linux 安装包 · 自动更新 · 静默打印 · 本地硬件 · 凭据托管；后端地址是运行期配置，同一个安装包可以连不同环境
- 移动端（Expo 原生 App，不是 WebView 套壳）：1.0 里是预览版，见下方「已知限制」
开发者
- 组件沙箱：每个组件可调、可抄 · 调色盘
- 由 OpenAPI 生成的类型安全前后端契约
- 每个模块一份踩坑记录（
AGENTS.md/CLAUDE.md），并有ctx:check校验文档不腐烂；arch:check守住分层方向
技术栈
| 前端 | React 19 · TypeScript · Vite · TanStack Router / Query / Table · Tailwind CSS 4 · shadcn/ui（Base UI）· Tiptap 3 · i18next |
| 后端 | FastAPI · Pydantic 2 · SQLAlchemy 2（async）· 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 |
后端 fork 自 fastapi-best-architecture（三层结构、插件机制、RBAC 与数据权限模型来自上游），本仓库加了 SQL Server 支持和上面绝大多数业务能力。
质量
1.0.0 这一次提交上的 CI：
- 后端 1492 条测试，PostgreSQL 和 SQL Server 各跑一整套
- 浏览器端到端测试（Playwright）160 条，跑在 SQL Server 上
- 前端单元测试 175 条；typecheck · eslint · ruff · 多语言 · 架构分层 · 文档引用 全部是必过闸门
- MySQL 不在 CI 里，本地整套跑过；从 v0.0.1 建的库一路迁移到最新，表结构与模型差异为 0
兼容承诺（1.0 起正式执行）
按 semver：破坏下表任何一条都要升主版本号。
| 对外的面 | 承诺 |
|---|---|
开放接口 /api/open/v1/* 和三语言 SDK |
路径、参数、响应字段、错误码、签名算法不删、不改语义；只加可选参数和新字段。真要破坏就开 v2，v1 保留 |
| Webhook 事件 | 事件名不改，载荷字段不删不改名，签名方式不变 |
| 数据库迁移链 | 从任何一个已发布的版本都能 pnpm db:upgrade 升到最新；进过 tag 的迁移不再改 |
| 插件接口 | plugin.toml 字段、安装流程、扩展点保持可用 |
| 配置键 | .env 和参数配置的键不改名；真要改，新旧并存一个次版本 |
内部接口 /api/v1/* |
不是公共 API，但照顾已装出去的桌面端 / 移动端：删改前新旧并存一个次版本 |
页面、组件、packages/* 的内部导出不在承诺范围内。
已知限制
- 移动端是预览版：已有首页、公告、消息、用户、个人中心、服务器监控、手机验证码登录；还没有审批和绑定手机号（排在 1.0 之后，#224），没有自动化测试（#137）。不在兼容承诺范围内
- MySQL 秋季回拨那一小时：MySQL 的
DATETIME不存时区偏移，夏令时地区秋季回拨时重复的那一小时，第二次的记录读回来会早一小时（PostgreSQL / SQL Server 不受影响，已用测试钉住） - 桌面端安装包没有代码签名：Windows 会弹 SmartScreen，macOS 要右键打开
明确不在 1.0
写在这里，免得被当成漏做：审批委托 / 评论 / 打印 · 数据变更前后对比 · OIDC / LDAP / 企微钉钉飞书登录 · 代码生成器 · 水印 · Webhook 二期。
刻意不做：多租户 · 通用低代码 · PWA · 扫码登录。
桌面客户端
fastapi-react-admin 的桌面客户端 —— 把 web 后台装进 Electron 外壳，
提供浏览器给不了的四件事：静默打印、本地硬件、凭据托管、自动更新。
后台本身（页面、权限、多页签）和浏览器版是同一份代码。
下哪个
| 平台 | 文件 | 说明 |
|---|---|---|
| Windows 10/11 x64 | admin-desktop-<版本>-setup.exe |
NSIS 安装向导，装到当前用户（%LOCALAPPDATA%\Programs），不需要管理员 |
| macOS Apple Silicon | ...-arm64.dmg |
M1 及以后 |
| macOS Intel | ...-x64.dmg（文件名不带 arm64） |
|
| Linux x64 | ...-x86_64.AppImage |
chmod +x 后直接运行，不用装 |
.blockmap 与 latest*.yml 是自动更新用的，人不需要下载。
装完第一件事：填后端地址
首次启动会让你填服务器地址（如 https://admin.example.com）。它是运行期配置，
存在用户目录里 —— 所以同一个安装包可以连不同环境，不用为每个环境各打一版。
桌面端的取舍（刻意的，不是漏做）
- 🔴 所有平台的包都没有代码签名。
- Windows：SmartScreen 会拦一次 →「更多信息」→「仍要运行」
- macOS：Gatekeeper 会说**「已损坏，应移到废纸篓」**。这不是包坏了，是没有公证：
右键 →「打开」，或者xattr -dr com.apple.quarantine /Applications/Admin\ Desktop.app - Linux：AppImage 不需要签名
- 想去掉这些提示：Windows 侧有面向开源项目的免费证书方案（SignPath Foundation），
macOS 侧没有免费路，需要 Apple Developer Program（$99/年）
- 🔴 macOS 上的自动更新不工作（未签名）。electron-updater 要校验运行中应用的代码签名，
拿不到就拒绝安装更新。Windows 与 Linux(AppImage) 的自动更新正常 - 读卡器等本地硬件是桩模式：厂商的原生助手不在仓库里（那是现场的东西），
所以这个包里没有。界面上相关功能会走模拟数据 - 打印：Windows 上是真的静默打印；macOS/Linux 上打印链路能跑，但没有在真机标签机上验过
更新从哪来
默认读这个仓库的 Release。内网部署（客户出不去公网）可以在客户机的 config.json 里
填 updateUrl，指向自己的静态目录 —— 不用为内网单独打一版。
What's Changed
- chore(release): v1.0.0 by @yilecoding in #223
Full Changelog: v0.13.0...v1.0.0
Contributors
yilecoding