# custom-fastapi-project

**Repository Path**: lizx126/custom-fastapi-project

## Basic Information

- **Project Name**: custom-fastapi-project
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-03
- **Last Updated**: 2026-08-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Custom FastAPI Admin

企业级 FastAPI 后台管理系统 —— 前后端分离的通用后台脚手架,集成了完整的认证授权、缓存、审计、任务队列、文件与报表能力。

## 技术栈

| 分类 | 技术 |
|---|---|
| Web 框架 | FastAPI 0.115+ · Pydantic 2 |
| 数据库 | MySQL 8 · SQLAlchemy 2.0 **异步** ORM · aiomysql · Alembic 迁移 |
| 缓存 | Redis 7(缓存封装:五数据结构、防穿透/击穿/雪崩、分布式锁) |
| 认证授权 | JWT 双 token(pyjwt)· bcrypt · RBAC 菜单+权限码 |
| 任务队列 | Celery 5.6(独立同步 engine 碰库)· Redis broker/backend |
| 定时任务 | APScheduler(AsyncIOScheduler,调度→Celery 组合) |
| 文件/报表 | openpyxl(Excel 导入导出)· 本地文件上传 |
| 工程化 | uv 依赖管理 · pytest · Docker(Redis)· Gitee |

## 核心功能

- **认证体系**:access/refresh 双 token,刷新轮换、滑动过期、登出拉黑、登录防爆破
- **RBAC 权限**:目录/菜单/按钮三级,权限码集中登记(`app/core/permissions.py`),`require_permission` 接口拦截,超管放行
- **操作日志**:`@log_operation` 装饰器审计写操作(独立会话、敏感字段脱敏、失败也记录)
- **缓存**:Redis 五种结构封装 + 防穿透四步 + 防击穿分布式锁 + 权限缓存
- **文件上传**:类型白名单、UUID 重命名(防路径穿越)、流式写入、落库可查
- **Excel 导入导出**:模板下载、逐行校验、批量入库,字段导入导出一致
- **任务队列**:Celery 异步任务(生产级同步 engine 碰库)、任务状态查询
- **定时任务**:APScheduler 每天定时清理(操作日志 + 过期 token,后者走 Celery 执行)

## 快速开始

### 环境要求

- Python 3.12+
- uv(依赖管理)
- MySQL 8(`127.0.0.1:3307`)
- Redis 7(Docker:`docker run -d --name my-redis -p 6379:6379 -v redis-data:/data redis:7-alpine`)

### 安装与启动

```bash
# 1. 安装依赖
uv sync

# 2. 配置(复制模板填真实值)
cp .env.example .env

# 3. 建表 + 初始化 admin + 权限字典
alembic upgrade head
python -m app.initial_data
python -m app.scripts.seed_rbac

# 4. 一键启动(FastAPI + Celery worker)
# Windows:
dev.bat
.\dev.bat

# Linux/Mac:
bash dev.sh

# 访问 http://127.0.0.1:8088/docs (Swagger UI)
```

默认管理员:`admin / admin123`(来自 `.env` 的 `FIRST_ADMIN_USERNAME/PASSWORD`)。

## 项目结构

```
app/
├── api/             路由层(v1 子目录,薄壳)
│   └── v1/          login / users / roles / menus / news / log / tasks / upload / excel
├── core/            核心: config · database · redis · security · cache · scheduler · celery_app · permissions
├── crud/            持久化层: user / token / role / menu / news / file / log_crud
├── models/          SQLAlchemy 模型
├── schemas/         Pydantic 模型
├── services/        业务层: auth / user / news / rbac / upload / excel / log_service
├── tasks/           Celery 任务: demo(示例) / cleanup(清过期token)
├── utils/           工具: response(统一响应) / exception / nanoid
└── scripts/         seed_rbac(权限字典种子)等
alembic/             数据库迁移
tests/               pytest 单元测试(零依赖,mock 缓存与 DB)
```

## API 一览(`/api/v1`)

| 模块 | 端点 | 说明 |
|---|---|---|
| **认证** | `POST /login` `/refresh` `/logout` · `GET /me` | 双 token 登录/刷新/登出 |
| **用户** | `POST /users/page` `/users/create` · `PUT /users/update/{id}` · `GET /users/{id}` | 分页(带关键字过滤)/增改查 |
| **角色** | `GET` `/POST /roles/` · `GET /roles/{id}/menus` | 角色管理 + 授权回显 |
| **菜单(RBAC)** | `GET /menus` `/menus/tree` `/menus/list` · `POST /menus/add` · `PUT/DELETE /menus/{id}` · `POST /menus/assign/{role_id}` | 权限字典 + 角色分配 |
| **新闻** | `GET /news/category` `/{category_id}` `/new/{id}` · `POST /news/page` `/create` · `PUT /news/update/{id}` · `DELETE /news/delete/{id}` | 新闻 CRUD + 分页 + 缓存 |
| **操作日志** | `POST /logs` | 审计日志分页查询 |
| **文件** | `POST /upload` · `GET /upload/{file_id}` `GET /upload` | 上传(落库)/按 id 查/列表 |
| **任务** | `POST /tasks/notify` · `GET /tasks/{task_id}` | 触发 Celery 任务/查状态 |
| **Excel** | `POST /excel/news/export` `/import` · `GET /excel/news/template` | 新闻导入导出(字段对齐) |

所有写操作与敏感查询接口均通过 `require_permission(Perm.XXX)` 做 RBAC 拦截;`/menus/list` 返回当前用户菜单树 + 权限码供前端控制显隐。

## 架构设计

### 分层
```
路由(HTTP) → services(业务) → crud(持久化) → model(表)
```
单向依赖,业务规则集中在 services,404/跨表校验等判断不裸露在路由。

### 认证流程
```
登录 → access_token(30min) + refresh_token(7d,存库)
每次请求: 验 access → 查缓存/库 → 滑动延长 refresh
刷新:     校验 refresh → 作废旧 → 签发新对(轮换)
登出:     吊销 refresh + 拉黑 access + 清用户缓存
```

### 缓存策略
- 带缓存查询统一"防穿透四步":读缓存 → 空值缓存命中 → 查库回填 → 未命中写空值
- 权限码缓存(`user:perms:{id}`),角色/菜单变更后自动失效
- 失败计数、分布式锁等基于 Redis 原子操作

### 任务队列(生产级)
- Celery worker 是同步进程,项目 ORM 是异步的 → 给 Celery 配**独立同步 engine**(pymysql),两套连接池各司其职
- APScheduler 在 Web 进程做轻量调度,重活投给 Celery worker 执行

### 安全
- 密码 SHA256+bcrypt;`SECRET_KEY`/`DEBUG_MODE` 环境化;`.env` 不提交 git
- 登录防爆破(账户锁)、权限码接口拦截、审计日志

## 部署

```bash
bash deploy.sh   # 一条命令: alembic 迁移 → 初始化 admin → upsert 权限字典
```

`deploy.sh` 幂等可反复执行;权限字典代码化,每次发版自动同步。

## 测试

```bash
pytest tests/   # 29 个用例,零依赖(mock 缓存与 DB)
```

覆盖:缓存防穿透 4 路径、认证登录、RBAC 校验、操作日志装饰器、用户/日志分页。

## 默认配置

- MySQL:`127.0.0.1:3307`(非默认端口)
- Redis:业务缓存 db5,Celery db1
- 上传目录:`uploads/`(已 gitignore,静态挂载 `/uploads`)