FastSoyAdmin

July 9, 2026 · View on GitHub

FastSoyAdmin

English | 中文

FastAPI + Vue3 全栈后台管理模板，开箱即用

简介

开箱即用的全栈后台管理模板，可作为中后台脚手架，也可作为全栈开发参考。

后端 — FastAPI · Pydantic v2 · Tortoise ORM · Redis
前端 — Vue3 · Vite8 · TypeScript · Naive UI · UnoCSS · Pinia · Alova · Elegant Router
基础设施 — Docker Compose（Nginx + FastAPI + Redis）、多 worker 启动锁、fastapi-guard 限流、内置 Radar 监控面板
代码生成器 — cli-init 起骨架，编辑 models.py，cli-crud 一键产出前后端 CRUD

特性

AI Coding 友好 — 内置 CLAUDE.md 与完整项目规范
一键 CRUD — Tortoise 模型生成前后端 CRUD、类型与 i18n
可覆写路由工厂 — CRUDRouter 生成标准接口，@crud.override 按需定制
模块化业务 — app/business/<name>/ 自动发现，跨模块走事件总线
多数据库支持 — PostgreSQL / SQLite / MySQL / SQL Server / Oracle
RBAC 权限体系 — 菜单 / API / 按钮 + 行级 data_scope
IaC 初始化对账 — 菜单、角色、API 启动时可声明式同步
统一接口契约 — {code, msg, data}、camelCase、Sqid 对外 ID
全栈类型检查 — basedpyright + vue-tsc + 静态 i18n 校验
内置运维能力 — Radar 监控、Redis 缓存降级、限流与 IP 封禁
Docker 部署 — Nginx + FastAPI + Redis 开箱即用

交流群

欢迎扫码加入 FastSoyAdmin QQ 交流群，一起交流使用、二开和部署经验。

分支说明

分支	用途
`main`	纯净骨架，无业务示例（默认分支）

快速开始

环境要求

工具	版本
Python	>= 3.12
Node.js	>= 20.19
uv · pnpm · just	最新

Docker 部署（推荐）

git clone https://github.com/sleep1223/fast-soy-admin.git
cd fast-soy-admin
just docker-db-init  # 首次先启动依赖服务并初始化数据库
just up              # 启动完整栈并写入默认/业务种子数据

访问 http://localhost:1880。

initdb 只在全新数据库执行一次；启动不会自动迁移。默认用户、菜单、角色、API 与业务种子数据会在最后一步 app 正常启动时写入。详见部署文档。

本地开发

git clone https://github.com/sleep1223/fast-soy-admin.git
cd fast-soy-admin
just install          # 后端 uv sync + 前端 pnpm install
cp .env.example .env  # 复制环境变量模板，按需修改 SECRET_KEY / DB_URL / REDIS_URL 等
just db-init          # 首次建表 + 基础数据
just run              # 并行启动后端(:9999) + 前端(:9527)，Ctrl+C 一起停

常用命令

全部命令封装在 justfile，运行 just --list 查看完整列表。

命令	作用
`just install`	安装后端 + 前端依赖
`just run`	同时启动后端 + 前端开发服务器
`just run backend` / `just run frontend`	仅启动后端 / 前端
`just check`	跑完后端 + 前端所有质量检查（提交前必跑）
`just check backend` / `just check frontend`	仅检查后端 / 前端
`just mm`	`makemigrations` + `migrate`
`just cli-init xxx`	创建业务模块骨架
`just cli-gen xxx`	选择模型与模糊/精确查询字段，生成后端代码
`just cli-gen-web xxx 中文名`	选择模型与列表/搜索字段，生成前端代码
`just cli-gen-all xxx 中文名`	一次选择并生成前后端代码
`just cli-crud xxx 中文名`	同上，完整 CRUD 生成别名
`just up` / `just down` / `just logs`	Docker 启停与日志

完整清单参见命令参考。

新增业务模块

以 inventory（库存管理）为例：

just cli-init inventory                   # 1. 创建模块骨架
$EDITOR app/business/inventory/models.py  # 2. 定义 Tortoise 模型
just cli-crud inventory 库存管理          # 3. 生成前后端 CRUD（i18n 自动并入）
just mm                                   # 4. 迁移
just run                                  # 5. 启动验证
just check                                # 6. 提交前检查

完整流程与字段类型映射见开发指南。

架构

app/
├── core/           # 框架基础设施（CRUDBase / CRUDRouter / Schema / 鉴权 / 缓存 / 事件 / Sqids）
├── system/         # 系统模块（auth / user / role / menu / api / dictionary / radar）
├── business/       # 业务模块（autodiscover 自动加载）
├── cli/            # 代码生成器
└── utils/          # 业务模块对外统一 import 入口
web/src/
├── views/          # 页面（Elegant Router 源）
├── service/api/    # Alova HTTP 封装
├── typings/api/    # TS 类型
├── store/modules/  # Pinia
├── router/         # Elegant Router + 守卫
└── locales/        # vue-i18n

分层：api/ → services/ → controllers/ → models + schemas。业务模块禁止反向 import app.system.*（少数显式暴露的 service 除外），禁止互相 import；跨模块走事件总线。详见架构。

切换数据库

修改 .env 中的 DB_URL，运行 just db-init。支持 PostgreSQL / SQLite / MySQL / SQL Server / Oracle。

默认依赖已包含 PostgreSQL（tortoise-orm[asyncpg]）与 SQLite（aiosqlite，tortoise 自带），其他数据库按需安装：

uv sync --extra mysql   # MySQL (asyncmy)
uv sync --extra mssql   # SQL Server (asyncodbc)
uv sync --extra oracle  # Oracle (asyncodbc)

业务模块可在自己的 config.py 声明独立 DB_URL，autodiscover 会注册为 conn_<biz>；跨模型事务用 get_db_conn(Model) 取连接名。详见切换数据库。

响应码

所有接口返回 {"code": "xxxx", "msg": "...", "data": ...}，HTTP 状态恒 200。

段	含义	前端典型行为
`0000`	成功	正常处理
`1xxx`	系统内部错误 / 序列化失败	框架自动弹错
`21xx`	认证失败（token / session）	登出 / 弹窗 / 自动刷新
`22xx`	授权失败（RBAC / 按钮 / 角色）	显示错误消息
`23xx`	资源冲突（唯一键）	显示错误消息
`24xx`	通用业务失败	显示错误消息
`25xx`	限流 / 安全策略	显示错误消息
`26xx`	Schema 必填兜底	显示错误消息
`4000–9999`	用户自定义（业务模块从 `4000` 起）	业务自行处理