FastApiAdmin 是一套 完全开源、高度模块化、技术先进的现代化快速开发平台，旨在帮助开发者高效搭建高质量的企业级中后台系统。该项目采用 前后端分离架构，融合 Python 后端框架 FastAPI 和前端主流框架 Vue3 实现多端统一开发，提供了一站式开箱即用的开发体验。

设计初心: 以模块化、松耦合为核心，追求丰富的功能模块、简洁易用的接口、详尽的开发文档和便捷的维护方式。通过统一框架和组件，降低技术选型成本，遵循开发规范和设计模式，构建强大的代码分层模型，搭配完善的本地中文化支持，专为团队和企业开发场景量身定制。

• 💻 网页端：https://service.fastapiadmin.com/web
• 📱 移动端：https://service.fastapiadmin.com/app
• 👤 登录账号：admin 密码：123456

FastapiAdmin
├─ backend               # 后端工程 (FastAPI + Python)
├─ frontend              # Web前端工程 (Vue3 + Element Plus)
├─ devops                # 部署配置
├─ docker-compose.yaml   # Docker编排文件
├─ deploy.sh             # 一键部署脚本
├─ LICENSE               # 开源协议
|─ README.en.md          # 英文文档
└─ README.md             # 中文文档

与仓库内 backend/env/.env.dev.example、frontend/.env.development.example 保持一致；若你本地已改 .env.dev / .env.development，以实际文件为准。

flowchart LR
  subgraph client[浏览器]
    U[用户]
  end
  subgraph fe[frontend 开发]
    V[Vue3 + Vite]
  end
  subgraph be[backend]
    A[FastAPI / Uvicorn]
  end
  subgraph data[数据层]
    DB[(数据库)]
    R[(Redis)]
  end
  U --> V
  V -->|REST 见 VITE_API_BASE_URL| A
  A --> DB
  A --> R

使用 Pydantic v2 与 PostgreSQL（asyncpg） 时：ORM 写入需要 Python 原生日期时间，JSON 输出需要可序列化字符串。项目通过 DateStr / TimeStr / DateTimeStr（backend/app/core/validator.py）的 PlainSerializer(..., when_used='json') 区分两种场景；统一响应见 backend/app/common/response.py 中的 jsonable_encoder；写入 Redis 时请使用 model_dump(mode='json') 再序列化。细节见 backend/README.md 中与根文档一致的说明。

模块名	截图
仪表盘
代码生成
智能助手

登录	首页	个人中心

1. 安装运行时：Python ≥ 3.10、Node.js ≥ 20、pnpm（前端包管理）、本机 MySQL 或 PostgreSQL（或改用 SQLite 需在 backend/env/.env.dev 中配置）、Redis（与 .env.dev 中一致）。
2. 获取代码：见下方「获取代码」。
3. 配置环境变量：将 backend/env/.env.dev.example 复制为 backend/env/.env.dev，将 frontend/.env.development.example 复制为 frontend/.env.development，按注释填写 数据库连接、Redis、JWT 密钥 等（须先在本机创建空数据库）。
4. 安装后端依赖：进入 backend，推荐使用 uv sync（见下「后端启动」）；或使用 pip install -r requirements.txt。
5. 启动后端：uv run main.py run --env=dev。首次启动会自动初始化数据库表结构及基础数据，一般无需事先执行 upgrade 迁移命令。
6. 安装前端依赖并启动：进入 frontend 执行 pnpm install 与 pnpm run dev。
7. 打开浏览器：按模板一般为 http://127.0.0.1:5180（VITE_APP_PORT=5180）；使用管理员账号登录（与 演示环境 一致，若你导入的是初始 SQL 则以后台为准）。

说明：若你修改了 ORM 模型并需用 Alembic 管理变更，再使用 python main.py revision / upgrade（见下文「常见问题」）。

# 克隆代码到本地
git clone https://gitee.com/fastapiadmin/FastapiAdmin.git
# 或者
git clone https://github.com/fastapiadmin/FastapiAdmin.git

后端注意：克隆下的代码需要修改 backend/env 目录下的 .env.dev.example 文件为 .env.dev，修改 backend/env 目录下的 .env.prod.example 文件为 .env.prod，然后根据实际情况修改数据库连接信息、Redis连接信息等。

前端注意：克隆下的代码需要修改 frontend 目录下的 .env.development.example 文件为 .env.development，修改 frontend 目录下的 .env.production.example 文件为 .env.production，然后根据实际情况修改接口地址等。

cd backend
uv sync
# 启动：请先保证已创建空数据库、Redis 已启动且与 .env.dev 一致
# 首次启动会自动初始化表与基础数据，无需先执行 upgrade
uv run main.py run --env=dev
# 生产环境示例
# uv run main.py run --env=prod

若未使用 uv：pip install -r requirements.txt 后直接 python main.py run --env=dev。模型变更需走 Alembic 时再执行 upgrade。

cd backend
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
python main.py run --env=dev

cd frontend
pnpm install
pnpm run dev
# 构建生产版本
pnpm run build

与 .env.dev.example / .env.development.example 对齐时：

# 1. 克隆代码到服务器
git clone https://gitee.com/fastapiadmin/FastapiAdmin.git
cd FastapiAdmin

# 2. 赋予执行权限并部署
chmod +x deploy.sh
./deploy.sh

# 查看容器日志
./deploy.sh logs

# 停止服务
./deploy.sh stop

# 重启服务
./deploy.sh restart

# 更新代码并重启（不重新构建镜像，适合后端代码热更新）
./deploy.sh update

# 1. 将部署脚本复制到服务器
cp deploy.sh /home/
cd /home
chmod +x deploy.sh

# 2. 执行一键部署（会自动克隆项目）
./deploy.sh

# 查看容器日志
./deploy.sh logs

# 停止服务
./deploy.sh stop

# 重启服务
./deploy.sh restart

# 更新代码并重启（不重新构建镜像，适合后端代码热更新）
./deploy.sh update

注意：

• 首次部署时会自动拉取代码并构建镜像
• 前端使用本地构建的 dist 目录，如需更新前端请先本地构建并提交到仓库
• 确保 devops/nginx/ssl/ 目录包含 SSL 证书文件（如使用 HTTPS）

项目采用插件化架构设计，二次开发建议在 backend/app/plugin 目录下进行，系统会自动发现并注册所有符合规范的路由，便于模块管理和升级维护。

• 自动路由发现：系统会自动扫描 backend/app/plugin/ 目录下所有 controller.py 文件
• 自动路由注册：所有路由会被自动注册到对应的前缀路径 (module_xxx -> /xxx)
• 模块化管理：按功能模块组织代码，便于维护和扩展
• 支持多层级嵌套：支持模块内部多层级嵌套结构

backend/app/plugin/
├── module_application/  # 应用模块（自动映射为 /application）
│   └── ai/              # AI子模块
│       ├── controller.py # 控制器文件
│       ├── model.py      # 数据模型文件
│       ├── schema.py     # 数据验证文件
│       ├── service.py    # 业务逻辑文件
│       └── crud.py       # 数据访问文件
├── module_example/      # 示例模块（自动映射为 /example）
│   └── demo/            # 子模块
│       ├── controller.py # 控制器文件
│       ├── model.py      # 数据模型文件
│       ├── schema.py     # 数据验证文件
│       ├── service.py    # 业务逻辑文件
│       └── crud.py       # 数据访问文件
├── module_generator/    # 代码生成模块（自动映射为 /generator）
└── init_app.py          # 插件初始化文件

系统会自动发现并注册所有符合以下条件的路由：

1. 控制器文件必须命名为 controller.py
2. 路由会自动映射：module_xxx -> /xxx
3. 支持多个 APIRouter 实例
4. 自动处理路由去重

1. 创建插件模块：在 backend/app/plugin/ 目录下创建新的模块目录，如 module_yourfeature
2. 编写数据模型：在 model.py 中定义数据库模型
3. 编写数据验证：在 schema.py 中定义数据验证模型
4. 编写数据访问层：在 crud.py 中编写数据库操作逻辑
5. 编写业务逻辑层：在 service.py 中编写业务逻辑
6. 编写控制器：在 controller.py 中定义路由和处理函数
7. 自动注册：系统会自动扫描并注册所有路由，无需手动配置

# backend/app/plugin/module_yourfeature/yourcontroller/controller.py
from fastapi import APIRouter, Depends, Path
from fastapi.responses import JSONResponse

from app.common.response import SuccessResponse
from app.core.router_class import OperationLogRoute
from app.core.dependencies import AuthPermission
from app.api.v1.module_system.auth.schema import AuthSchema
from .service import YourFeatureService

# 创建路由实例
YourFeatureRouter = APIRouter(
    route_class=OperationLogRoute, 
    prefix="/yourcontroller", 
    tags=["你的功能模块"]
)

@YourFeatureRouter.get("/detail/{id}", summary="获取详情")
async def get_detail(
    id: int = Path(..., description="功能ID"),
    auth: AuthSchema = Depends(AuthPermission(["module_yourfeature:yourcontroller:detail"]))
) -> JSONResponse:
    result = await YourFeatureService.detail_service(id=id, auth=auth)
    return SuccessResponse(data=result)

@YourFeatureRouter.get("/list", summary="获取列表")
async def get_list(
    auth: AuthSchema = Depends(AuthPermission(["module_yourfeature:yourcontroller:list"]))
) -> JSONResponse:
    result = await YourFeatureService.list_service(auth=auth)
    return SuccessResponse(data=result)

1. 命名规范：模块名采用 module_xxx 格式，控制器名采用驼峰命名法
2. 权限控制：所有API接口必须添加权限控制装饰器
3. 日志记录：使用 OperationLogRoute 类自动记录操作日志
4. 返回格式：统一使用 SuccessResponse 或 ErrorResponse 返回响应
5. 代码注释：为所有API接口添加详细的文档字符串

• 插件模块名必须以 module_ 开头
• 控制器文件必须命名为 controller.py
• 路由会自动映射到对应的前缀路径
• 无需手动注册路由，系统会自动发现并注册

1. 配置前端API：在 frontend/src/api/ 目录下创建对应的API文件
2. 编写页面组件：在 frontend/src/views/ 目录下创建页面组件
3. 注册路由：在 frontend/src/router/index.ts 中注册路由

项目内置代码生成器，可以根据数据库表结构自动生成前后端代码，大幅提升开发效率。

1. 登录系统：使用管理员账号登录系统
2. 进入代码生成模块：在左侧菜单中点击"代码生成"
3. 导入表结构：选择要生成代码的数据库表
4. 配置生成参数：填写模块名称、功能名称等
5. 生成代码：点击"生成代码"按钮
6. 下载或写入：选择下载代码包或直接写入项目目录

# 后端文件
backend/app/plugin/module_yourmodule/
└── yourfeature/
    ├── controller.py # 控制器文件
    ├── model.py      # 数据模型文件
    ├── schema.py     # 数据验证文件
    ├── service.py    # 业务逻辑文件
    └── crud.py       # 数据访问文件

# 前端文件
frontend/src/
├── api/module_yourmodule/
│   └── yourfeature.ts # API调用文件
└── views/module_yourmodule/
    └── yourfeature/
        └── index.vue # 页面组件

# 生成的控制器代码示例
from fastapi import APIRouter, Depends
from fastapi.responses import JSONResponse

from app.common.response import SuccessResponse
from app.core.router_class import OperationLogRoute
from app.core.dependencies import AuthPermission
from app.api.v1.module_system.auth.schema import AuthSchema
from .service import YourFeatureService
from .schema import (
    YourFeatureCreateSchema,
    YourFeatureUpdateSchema,
    YourFeatureQueryParam
)

YourFeatureRouter = APIRouter(
    route_class=OperationLogRoute, 
    prefix="/yourfeature", 
    tags=["你的功能模块"]
)

@YourFeatureRouter.get("/detail/{id}")
async def get_detail(
    id: int, 
    auth: AuthSchema = Depends(AuthPermission(["module_yourmodule:yourfeature:detail"]))
) -> JSONResponse:
    result = await YourFeatureService.detail_service(id=id, auth=auth)
    return SuccessResponse(data=result)

• 代码生成器：自动生成前后端CRUD代码
• API文档：自动生成Swagger/Redoc API文档
• 数据库：首次启动自动初始化表与基础数据；结构演进可配合 Alembic
• 日志系统：内置日志记录和查询功能
• 监控系统：内置服务器监控和缓存监控功能

1. 需求分析：明确功能需求和业务逻辑
2. 数据库设计：设计数据库表结构
3. 代码生成：使用代码生成器生成基础代码
4. 业务逻辑开发：完善业务逻辑和接口
5. 前端开发：开发前端页面和交互
6. 测试：进行单元测试和集成测试
7. 部署：部署到生产环境

1. 权限控制：所有API接口必须添加权限控制
2. 数据验证：所有输入数据必须进行验证
3. 异常处理：统一处理API异常
4. 日志记录：关键操作必须记录日志
5. 性能优化：注意API性能优化，避免慢查询
6. 代码规范：遵循PEP8和项目代码规范

A：按照二次开发步骤，在 backend/app/plugin/ 目录下创建新的模块目录，编写相关代码即可。

A：在 backend/env/.env.dev 或 backend/env/.env.prod 文件中配置数据库连接信息。

A：在 backend/env/.env.dev 或 backend/env/.env.prod 文件中配置Redis连接信息。

A：使用 python main.py revision --env=dev 命令生成迁移文件。

A：在需要执行 Alembic 迁移时使用 python main.py upgrade --env=dev（或 uv run ...）。首次启动一般不必先执行，由应用自动初始化。

A：在 backend 目录执行 uv run main.py run --env=dev（或 python main.py run --env=dev）。首次启动会自动初始化数据库与基础数据，无需先手动执行 upgrade。

A：一般不需要。首次启动后端会自动完成库表与初始数据；仅在你自行修改模型并需用 Alembic 时再使用 revision / upgrade。

A：使用 pnpm run build 命令构建前端生产版本。

A：使用 ./deploy.sh 脚本一键部署到生产环境。

更多详情请查看 官方文档

感谢以下开源项目的贡献和支持：

• FastAPI
• Pydantic
• SQLAlchemy
• APScheduler
• Vue3
• TypeScript
• Vite
• Element Plus
• UniApp
• Wot-Design-UI

群组二维码	微信支付二维码

如果你喜欢这个项目，请给我一个 ⭐️ Star 支持一下吧！非常感谢！