# 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**: 21
- **Forks**: 6
- **Created**: 2025-08-23
- **Last Updated**: 2025-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Pear Admin FastAPI

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

## 功能特点

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

## 系统截图

### 登录界面
![登录界面](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)

## 快速开始

### 本地开发

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 init.py init
     ```

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

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

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

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

6. **访问系统**
   - 后台地址: http://127.0.0.1:8005
   - 用户名: admin
   - 密码: 123456

7. **演示地址**
   - 后台地址: https://pear.freelyfast.top
   - 用户名: admin
   - 密码: 123456

## 项目结构

```
├── applications          # 应用核心代码
│   ├── common           # 通用工具类
│   ├── config.py        # 配置文件
│   ├── core             # 核心组件
│   │   ├── middlewares  # 中间件
│   │   ├── response     # 响应处理
│   │   └── ...
│   ├── log              # 日志系统
│   ├── models           # 数据模型
│   ├── schemas          # 数据校验模型
│   ├── utils            # 工具函数
│   └── view             # 路由视图
├── 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. 创建特性分支: `git checkout -b feature/feature-name`
3. 提交修改: `git commit -m 'Add some feature'`
4. 推送分支: `git push origin feature/feature-name`
5. 提交 Pull Request

## 致谢

感谢 [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)

## 许可证

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