# pear admin fastapi

**Repository Path**: YueXia_1/pear-admin-fastapi

## Basic Information

- **Project Name**: pear admin fastapi
- **Description**: pear admin fastapi 是一个基于 FastAPI + Tortoise ORM + Pear Admin Lay-UI的高效后台管理框架，旨在简化开发流程，提供安全、快速的API服务与管理界面。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 40
- **Forks**: 13
- **Created**: 2025-08-23
- **Last Updated**: 2026-06-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Pear Admin FastAPI

基于 FastAPI 的现代化后台管理系统，结合了 FastAPI 的高性能异步特性和 Pear Admin Layui 的美观界面，提供完整的权限管理、用户管理、部门管理等功能。

## 功能特点

- **高性能框架**：基于 FastAPI 构建，支持异步操作，性能出色
- **ORM 支持**：使用 Tortoise-ORM 进行数据库操作，简化数据访问层
- **认证与权限**：完整的用户认证和权限管理系统，支持基于角色的访问控制
- **RBAC权限模型**：实现了完整的RBAC（基于角色的访问控制）权限模型，支持用户-角色-权限三层权限管理体系
- **精细的数据权限**：支持五种数据权限范围控制（仅本人数据、本部门数据、本部门及以下数据、自定义数据、全部数据），可根据用户角色灵活控制数据访问范围
- **响应式界面**：基于 Pear Admin Layui 的响应式前端界面，适配各种设备
- **数据可视化**：集成 pyecharts 实现丰富的数据可视化，支持 3D 柱状图、饼图、折线图、地图等多种图表类型，提供交互式数据展示体验
- **模块化设计**：采用模块化架构，代码组织清晰，易于扩展
- **完整的日志系统**：记录系统操作日志和请求日志，便于调试和审计
- **邮件通知**：集成邮件发送功能，支持各种通知场景
- **文件上传**：支持文件上传和管理功能
- **接口文档**：自动生成 OpenAPI 接口文档，便于前后端协作，集成了 Scalar 和 Stoplight 两种现代接口文档管理工具，提供美观、易用的API浏览和测试体验

## 系统截图

### 登录界面
![登录界面](images/login.gif)

### 控制台
![控制台](images/index.png)

### 用户管理
![用户管理](images/user.png)

### 部门管理
![部门管理](images/dept.png)

### 菜单管理
![菜单管理](images/meun.png)

### 系统监控
![系统监控](images/monitor.png)

### 3D柱状图
![3D柱状图](images/3d_bar.gif)

### 基础图表
![基础图表](images/chart.png)

### 地图示例
![地图示例](images/map.png)

### Stoplight接口文档
![Stoplight接口文档](images/stoplight_img.png)

### Scalar接口文档
![Scalar接口文档](images/scalar_img.png)

## 快速开始

### 本地开发

1. **克隆项目**
   ```bash
   git clone https://gitee.com/YueXia_1/pear-admin-fastapi.git
   cd pear-admin-fastapi
   ```

2. **安装依赖并创建虚拟环境**
   项目使用uv和pyproject.toml进行依赖管理，推荐使用以下命令同步依赖：
   ```bash
   uv sync
   ```
   该命令会自动创建虚拟环境（位于.venv目录），并根据pyproject.toml和uv.lock文件安装依赖，确保依赖版本的一致性。无需手动创建和激活虚拟环境。

3. **配置环境变量**
   复制 `.env.example` 文件为 `.env`，并根据需要修改配置：
   ```bash
   cp .env.example .env
   ```
   
   数据库支持多种类型，可根据需要配置不同的数据库连接：
   - SQLite（默认）：`sqlite:///./pear.db` 或 `sqlite://:memory:`（内存数据库）
   - MySQL：`mysql://user:pass@127.0.0.1:3306/pear_fastapi?charset=utf8mb4&minsize=1&maxsize=5`
   - PostgreSQL：`postgres://user:pass@127.0.0.1:5432/pear_fastapi?min_size=1&max_size=5&timeout=10`
   - Microsoft SQL Server：`sqlserver+pyodbc://user:pass@127.0.0.1:1433/pear_fastapi?driver=ODBC Driver 17 for SQL Server`
   
   注意：使用不同数据库需要安装对应的数据库驱动，参考[Tortoise ORM官方文档](https://tortoise.org.cn/getting_started.html)：
   - MySQL: `uv add tortoise-orm[asyncmy]` 或 `uv add tortoise-orm[aiomysql]`
   - PostgreSQL: `uv add tortoise-orm[asyncpg]` 或 `uv add tortoise-orm[psycopg]`
   - Microsoft SQL Server/Oracle: `uv add tortoise-orm[asyncodbc]`
   - SQLite: 默认已包含(aiosqlite)

4. **初始化数据库**
   `init.py` 是数据库初始化工具，用于将 `data` 目录下的 JSON 数据导入到数据库中。提供以下命令：

   - **初始化数据库（保留现有数据）**
     ```bash
     python cli.py init
     ```

   - **初始化数据库（先清空现有数据）**
     ```bash
     python cli.py init --clear
     # 或使用简写形式
     python cli.py init -c
     ```

   - **重置数据库（等价于先清空再初始化）**
     ```bash
     python cli.py reset
     ```

   初始化完成后，系统会创建默认管理员账户：`admin`，密码：`123456`

5. **运行项目**
   ```bash
   python main.py
   ```

6. **访问系统**
   - 后台地址: http://127.0.0.1:8005
   - 用户名: admin
   - 密码: 123456
   - Stoplight接口文档: http://127.0.0.1:8005/docs/stoplight
   - Scalar接口文档: http://127.0.0.1:8005/docs/scalar

7. **演示地址**
   - 后台地址: https://pear.freelyfast.top
   - 用户名: admin
   - 密码: 123456
   - Stoplight接口文档: https://pear.freelyfast.top/docs/stoplight
   - Scalar接口文档: https://pear.freelyfast.top/docs/scalar

## 开发规范

### 依赖管理

本项目使用 [uv](https://docs.astral.sh/uv/) 管理依赖，`pyproject.toml` 作为单一配置来源，`uv.lock` 锁定精确版本：

```bash
uv sync           # 同步依赖到虚拟环境
uv add <package>  # 添加新依赖
uv lock --upgrade # 升级依赖版本
```

### 代码风格

使用 [Ruff](https://docs.astral.sh/ruff/) 统一代码质量和格式，规则配置在 `.ruff.toml`：

```bash
ruff check .       # 代码检查
ruff check --fix . # 自动修复
ruff format .      # 代码格式化
```

Ruff 整合了 Flake8、isort、pyupgrade、Bugbear 等工具，覆盖格式、导入排序、安全检查等 40+ 条规则。

### Pre-commit 钩子

项目配置了 `.pre-commit-config.yaml`，提交前自动执行代码检查和格式化：

```bash
uv add --dev pre-commit       # 安装 pre-commit
pre-commit install            # 启用 Git 钩子
pre-commit run --all-files    # 手动对所有文件执行
```

提交时会自动运行以下检查：

| 检查项 | 说明 |
|---|---|
| 行尾空白 / 文件末尾换行 | 统一代码格式 |
| YAML / JSON / TOML 语法 | 校验配置文件正确性 |
| 合并冲突标记 | 阻止残留冲突提交 |
| 私钥 / 大文件 | 安全防护 |
| Ruff lint + format | 代码质量门禁 |

> 建议在 `git commit` 之前确保 `pre-commit install` 已执行，避免 CI 中因格式问题被拦截。

### 类视图 (CBV) 开发规范

所有路由使用 `fastapi_cbv.py` 提供的 `@cbv()` 装饰器实现类视图，并继承 `BaseController` 使用其工具方法。

#### 路由文件结构

每个模块包含两个文件，均在 `applications/view/system/<module>/` 目录下：

| 文件 | 用途 | 路由变量 |
|------|------|----------|
| `api.py` | JSON API 接口（自动生成 OpenAPI 文档） | `api = APIRouter(prefix="/<module>", tags=[...])` |
| `page.py` | HTML 页面渲染（`include_in_schema=False`） | `page = APIRouter(prefix="/<module>", include_in_schema=False)` |

#### BaseController 工具方法

所有控制器继承 `BaseController`，使用以下统一响应方法：

```python
# API 响应
self.success(*, msg="成功", data=None)      # 成功响应 → {success, msg, data}
self.fail(*, msg="失败")                      # 失败响应 → {success, msg}
self.table_response(data, count, limit=10, msg="成功")  # LayUI 表格响应 → {code, msg, data, count, limit}

# 页面渲染
self.render(template_name, **context)         # 渲染 HTML 模板（自动注入 request）
```

#### 基本用法 — API 控制器

```python
from fastapi import APIRouter, Depends, Query
from applications.utils.fastapi_cbv import cbv
from applications.core.response.base_controller import BaseController, AuthController

api = APIRouter(prefix="/example", tags=["示例模块"])

@cbv(api)
class ExampleApi(BaseController):
    """示例 API 控制器"""

    @api.get("/list", summary="获取列表")
    async def get_list(self, page: int = Query(1), limit: int = Query(10)):
        data = await some_service.get_list(page=page, limit=limit)
        return self.table_response(data=data, count=len(data))

    @api.post("/save", summary="新增", dependencies=[Depends(permission_depends("system:example:add"))])
    async def save(self, data: ExampleSchema):
        await some_service.create(data)
        return self.success(msg="新增成功")
```

#### 需要登录认证 — AuthController

```python
@cbv(api)
class ExampleApi(AuthController):
    """需要登录的控制器"""

    @api.get("/info", summary="获取当前用户信息")
    async def get_info(self):
        # self.current_user 由 AuthController 自动注入
        return self.success(data=self.current_user)
```

#### 页面渲染控制器

```python
page = APIRouter(prefix="/example", include_in_schema=False)

@cbv(page)
class ExamplePage(BaseController):
    """示例页面控制器"""

    @page.get("/", dependencies=[Depends(permission_depends("system:example:main"))], response_class=HTMLResponse)
    async def main(self):
        return self.render("system/example/main.html")
```

#### 命名路由

当模板中需要 `url_for('xxx')` 引用路由时，在装饰器中指定 `name` 参数：

```python
@page.get("/", name="system.example.main", response_class=HTMLResponse)
async def main(self):
    return self.render("system/example/main.html")
```

路由名遵循命名空间风格：`system.<module>.<action>`。

#### 注意事项

1. **`self.request` 自动注入**：`BaseController` 的 `request: Request` 字段由 CBV 框架自动注入，无需在方法参数中声明
2. **`self.current_user` 自动注入**：`AuthController` 提供 `current_user` 字段（来源 `Depends(manager)`），需认证的控制器继承此类
3. **装饰器参数保留**：`summary`、`response_model`、`dependencies` 等依然写在 `@router.get/post/...` 装饰器中
4. **`Depends(manager.optional)`**：如果使用可选认证，请保留显式 `Depends(manager.optional)`，不要使用 `AuthController`
5. **响应格式不变**：`self.success/fail/table_response` 底层委托 `applications/utils/http.py` 的工具函数，保持与 LayUI 前端兼容的 JSON 格式

## 项目结构

```
├── applications          # 应用核心代码
│   ├── common           # 通用工具类（包含权限管理和数据权限控制）
│   │   ├── user_manager.py  # 用户认证和权限管理
│   │   ├── data_scope.py    # 基于部门的数据权限过滤
│   │   └── ...
│   ├── config.py        # 配置文件
│   ├── core             # 核心组件
│   │   ├── middlewares  # 中间件
│   │   ├── response     # 响应处理
│   │   │   ├── base_controller.py  # BaseController / AuthController 基类
│   │   │   ├── response_schema.py  # 响应模型 & ResultResponse 工厂
│   │   └── ...
│   ├── log              # 日志系统
│   ├── models           # 数据模型
│   │   ├── admin_user.py    # 用户模型
│   │   ├── admin_role.py    # 角色模型
│   │   ├── admin_power.py   # 权限模型
│   │   ├── admin_dept.py    # 部门模型
│   │   └── ...
│   ├── schemas          # 数据校验模型
│   ├── utils            # 工具函数
│   │   ├── fastapi_cbv.py   # CBV 类视图装饰器 @cbv()
│   │   ├── api_model.py     # APIModel 基类（snake_case/camelCase 自动转换）
│   │   ├── camelcase.py     # 命名转换工具
│   │   ├── http.py          # 统一响应格式（ResultResponse, success_api, table_api）
│   │   └── ...
│   ├── view             # 路由视图（CBV 类视图模式）
│   │   └── system       # 系统管理模块
│   │       ├── user     # 用户管理
│   │       │   ├── api.py     # JSON API 接口
│   │       │   └── page.py    # HTML 页面路由
│   │       ├── role     # 角色管理
│   │       │   ├── api.py
│   │       │   └── page.py
│   │       ├── dept     # 部门管理（同上）
│   │       ├── power    # 权限/菜单管理
│   │       ├── passport # 登录认证
│   │       ├── dict     # 字典管理
│   │       ├── config   # 系统配置
│   │       ├── log      # 日志管理
│   │       ├── mail     # 邮件管理
│   │       ├── file     # 文件管理
│   │       ├── monitor  # 系统监控
│   │       ├── notification # 通知管理
│   │       ├── rights   # 权限信息
│   │       ├── upload   # 文件上传
│   │       ├── chart    # 数据图表
│   │       ├── health   # 健康检查
│   │       ├── index    # 首页
│   │       └── __init__.py   # 路由注册入口
├── data                 # 初始化数据
├── images               # 系统截图
├── logs                 # 日志文件
├── migrations           # 数据库迁移文件
├── static               # 静态资源文件
├── templates            # 模板文件
├── test                 # 测试文件
├── .env                 # 环境变量配置
├── .env.example         # 环境变量示例
├── docker-compose.yml   # Docker Compose 配置
├── Dockerfile           # Docker 镜像构建文件
├── main.py              # 应用入口文件
├── nginx.conf           # Nginx 配置文件
├── pyproject.toml       # 项目依赖配置
└── requirements.txt     # 依赖列表
```

## 部署

### Docker 部署

1. **构建镜像**
   ```bash
   docker build -t pear-admin-fastapi .
   ```

2. **运行容器**
   ```bash
   docker-compose up -d
   ```

### Nginx 部署

参考 `nginx.conf` 文件配置 Nginx 反向代理。

## 贡献指南

1. Fork 本项目
2. 克隆并安装开发依赖：
   ```bash
   git clone <your-fork-url>
   cd pear-admin-fastapi
   uv sync
   pre-commit install
   ```
3. 创建特性分支: `git checkout -b feature/feature-name`
4. 提交前确保代码通过检查: `ruff check . && ruff format --check .`
5. 提交修改: `git commit -m 'feat: 新增XXX功能'`
6. 推送分支: `git push origin feature/feature-name`
7. 提交 Pull Request

## 权限系统说明

### RBAC权限模型
本系统实现了完整的RBAC（基于角色的访问控制）权限模型，包含以下核心概念：

- **用户（User）**：系统中的操作人员，可分配多个角色
- **角色（Role）**：权限的集合，连接用户和权限的桥梁
- **权限（Power）**：具体的操作权限，控制用户可以访问的接口和功能
- **部门（Dept）**：组织结构，用于数据权限的控制

### 数据权限控制
系统支持五种细粒度的数据权限范围控制：

1. **仅本人数据权限（0）**：用户只能查看和操作自己的数据
2. **本部门数据权限（1）**：用户可以查看和操作所属部门的数据
3. **本部门及以下数据权限（2）**：用户可以查看和操作所属部门及其所有子部门的数据
4. **自定义数据权限（3）**：用户可以查看和操作指定部门的数据
5. **全部数据权限（4）**：用户可以查看和操作系统中的所有数据

数据权限通过 `applications/common/data_scope.py` 中的 `DataScopeFilter` 类实现，提供了灵活的依赖注入方式，可以轻松集成到任何需要数据权限控制的接口中。

## 入群交流

![入群交流二维码](images/qrcode_1763560612295.jpg)

扫码加入我们的技术交流群，获取最新项目动态和开发支持。

## 致谢

感谢 [pear-admin-flask](https://gitee.com/pear-admin/pear-admin-flask) 开源项目提供的灵感和参考。该项目的设计理念和架构对本项目的开发产生了重要影响。

## 参考文档

- [pyecharts 开发文档](https://05x-docs.pyecharts.org/#/zh-cn/prepare)
- [pyecharts 示例库](https://gallery.pyecharts.org/#/README)
- [FastAPI 官方文档](https://fastapi.tiangolo.com/)
- [Tortoise ORM 文档](https://tortoise.org.cn/)
- [Stoplight Elements 文档](https://stoplight.io/open-source/elements)
- [Scalar API Reference 文档](https://guides.scalar.com/scalar/scalar-api-references/integrations/fastify)

## 许可证

本项目使用 MIT 许可证，详情请查看 [LICENSE](https://opensource.org/licenses/MIT)。