# fasac

**Repository Path**: ccq/fasac

## Basic Information

- **Project Name**: fasac
- **Description**: 法萨克(fastapi-alembic-sqlmodel-async-cn缩写)基于现代高效的Fastapi Web开源脚手架的汉化版
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-15
- **Last Updated**: 2025-11-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 法萨克 FASAC

## 介绍
法萨克(fastapi-alembic-sqlmodel-async-cn缩写)基于现代高效的Fastapi Web开源脚手架的汉化版

- 基于开源项目`fastapi-alembic-sqlmodel-async`的`v.0.2.4`，这是一个用于构建可扩展、高性能 API 的现代 Web 应用程序模板，它结合了 FastAPI、异步数据库操作以及完善的身份验证机制。
- 对代码添加注释、汉化说明文档，添加部分学习笔记

### 项目目标

旨在为开发现代化 Python Web 应用提供可用于生产的模板。它展示了实现异步 API 端点、数据库操作、身份验证、后台任务处理和文件存储的最佳实践。该模板完全兼容 Python 3.10+，并集成了最新版本的 FastAPI、SQLModel 和 Pydantic V2。

### 系统架构

采用基于微服务的架构，各组件通过容器化部署，相互协作以提供完整的后端解决方案。
![架构图](./doc/high-level_architecture.jpg)

#### 组件角色

* **Caddy 反向代理**：负责将客户端请求路由至相应的后端服务，并提供静态文件服务
* **FastAPI 服务器**：核心应用服务器，处理 HTTP 与 WebSocket 请求，实现 API 端点与业务逻辑
* **PostgreSQL 数据库**：存储应用数据及 Celery 调度信息
* **Redis 服务器**：提供缓存、限流功能，并作为 Celery 任务队列的消息代理
* **Minio 服务器**：对象存储服务，用于处理文件上传（尤其是图片）
* **Celery Worker**：处理异步及后台任务，包括 ML/NLP 操作
* **Celery Beat**：调度周期性任务，由 Celery Worker 执行

#### 数据流
采用典型的请求-响应模式，并包含多层处理流程：
![数据流](./doc/data_flow.jpg)

#### 目录结构
主要代码库组织在 backend/app 目录中。应用程序结构遵循 FastAPI 项目的最佳实践：
* app/ - 包含主要应用程序代码
    * api/ - API 端点和路由器
    * core/ - 核心功能，如配置、安全性和 celery 设置
    * crud/ - 数据库模型的 CRUD 操作
    * db/ - 数据库初始化和会话管理
    * models/ - SQLModel 数据库模型
    * schemas/ - 用于请求/响应验证的 Pydantic 模式

其他重要目录包括：
* static/ - 由 Caddy 提供的静态文件
* minio/data/ - MinIO 存储卷
* caddy/ - Caddy 配置

### 主要功能
包含构建现代 Web 应用所需的一整套功能：

| 功能        | 描述                                            |
| --------- | --------------------------------------------- |
| 异步数据库操作   | 使用 SQLModel 结合 SQLAlchemy 2.0 实现完整的异步 CRUD 操作 |
| 身份验证与授权   | 基于 JWT 的身份验证，支持基于角色的访问控制                      |
| 后台任务处理    | 使用 Celery 实现异步任务执行与调度                         |
| 对象存储      | 集成 Minio 实现文件管理                               |
| API 文档    | 通过 FastAPI 自动生成可交互的 API 文档                    |
| 类型检查      | 完整的类型注解，兼容 Python 3.10+                       |
| 数据库迁移     | 由 Alembic 管理                                  |
| 限流        | 基于 Redis 的 API 限流                             |
| 缓存        | 使用 Redis 实现响应缓存                               |
| 异步并发      | 使用 asyncer 处理并发操作                             |
| WebSocket | 支持实时通信                                        |
| 自然语言处理    | 集成 HuggingFace Transformers 与 OpenAI          |

### 数据模型与关系
系统使用 SQLModel 进行数据建模，兼具 SQLAlchemy 与 Pydantic 的优点。以下是ER图：
![ER图](./doc/er.png)

### 使用的技术
| 技术                       | 用途                                     |
| ------------------------ | -------------------------------------- |
| FastAPI                  | 用于构建 API 的 Web 框架，自带 OpenAPI 文档        |
| SQLModel                 | 将 SQLAlchemy Core 与 Pydantic 模型结合的 ORM |
| Alembic                  | 数据库迁移工具                                |
| PostgreSQL               | 关系型数据库，用于数据持久化                         |
| Redis                    | 内存数据存储，用于缓存、限流及任务队列                    |
| Minio                    | 兼容 Amazon S3 API 的对象存储服务               |
| Celery                   | 分布式任务队列，用于异步处理                         |
| Caddy                    | 现代 Web 服务器与反向代理，支持自动 HTTPS             |
| Docker                   | 容器化平台，确保开发与部署环境一致                      |
| Pydantic                 | 数据验证与配置管理                              |
| pytest                   | 测试框架                                   |
| HuggingFace Transformers | 自然语言处理模型                               |

### 开发和部署
通过 Docker Compose 支持开发环境和生产环境：
* 开发环境：使用 docker-compose-dev.yml，支持热重载与调试
* 生产环境：使用 docker-compose.yml，针对性能进行优化

Makefile 提供了常用操作的快捷命令，如启动容器、运行迁移、初始化数据库等。

### 参考

- 原版项目github: `https://github.com/jonra1993/fastapi-alembic-sqlmodel-async`
- [原版Readme](./doc/README_old.md)
- Web框架FastAPI的官方文档: `https://fastapi.tiangolo.com/zh/`
- 轻量级数据库迁移工具Alembic的官网: `https://alembic.sqlalchemy.org/en/latest/`
- ORM库SQLModel的官网: `https://sqlmodel.tiangolo.com/`
- Python依赖和打包工具Poetry的官网文档: `https://python-poetry.org/docs/`

## 入门指南

### 先决条件

* Docker 和 Docker Compose 来运行容器化服务
* 使用 Make 进行自动化
* Python: 需要版本 ">3.9,<3.12"
* Poetry: 用于依赖管理

### 安装流程

1. clone本项目
2. 通过创建 .env 文件来设置环境变量
3. 安装依赖项（如果在本地开发）：`make install`

### 环境配置
`.env`文件关键配置项：
| 类别      | 重要变量                                               | 描述            |
| ------- | -------------------------------------------------- | ------------- |
| FastAPI | PROJECT\_NAME, SECRET\_KEY                         | 核心 API 设置     |
| 数据库     | DATABASE\_HOST, DATABASE\_USER, DATABASE\_PASSWORD | PostgreSQL 连接 |
| Redis   | REDIS\_HOST, REDIS\_PORT                           | 用于缓存和 Celery  |
| Minio   | MINIO\_URL, MINIO\_ROOT\_USER                      | 对象存储配置        |
| 安全      | ENCRYPT\_KEY, SECRET\_KEY                          | 用于 JWT 令牌     |

### 项目运行
#### 开发模式

* `make run-dev-build` 强制重构后运行
* `make run-dev` 直接运行

可访问: 
* API 文档：http://fastapi.localhost/docs
* 静态文件：http://static.localhost
* Minio 控制台：http://stash.localhost

##### 数据库初始化

* `make init-db`

将创建三个示例用户：
* 管理员：admin@admin.com / 密码：admin
* 经理：manager@example.com / 密码：admin
* 用户：user@example.com / 密码：admin

##### 开发流程

![开发流程](./doc/development_workflow.png)

##### 代码结构概要

![代码结构](./doc/code_structure.png)

#### 生产部署

* `make run-prod`

生产 Docker Compose 配置，与开发环境在几个方面有所不同：
* 使用带有 Uvicorn 工作进程的 gunicorn 而不是开发服务器
* 使用持久的 PostgreSQL 数据库
* 针对性能而非开发便利性进行了优化

#### 常见故障排查

| 问题          | 解决方案                                         |
| ----------- | -------------------------------------------- |
| 数据库连接错误     | 检查 .env 文件中的 DATABASE\_\* 变量，并确保数据库容器正在运行    |
| 容器构建失败      | 尝试 `docker system prune` 清理 Docker 缓存，然后重新构建 |
| Make 权限问题   | 使用 `chmod +x Makefile` 确保正确的权限               |
| Poetry 依赖冲突 | 尝试删除 poetry.lock 并运行 `poetry update`         |
| docker服务无法停止 | 有可能是Linux启用的apparmor，关掉它再重启docker服务         |


## 核心系统

本应用程序构建在几个关键子系统之上，这些子系统相互作用，创建完整的后端解决方案。核心系统包括：
1. FastAPI 应用程序 - 处理 HTTP 和 WebSocket 请求的主要 Web 框架
2. 数据库管理 - 使用 SQLModel 和 Alembic 实现异步 PostgreSQL 集成
3. 身份验证系统 - 基于 JWT 的身份验证，使用 Redis 进行令牌管理
4. 异步任务 - 用于后台处理的 Celery worker 和 beat 调度器
5. 文件存储 - 用于媒体文件的 MinIO 对象存储

这些系统使用 Docker 进行容器化，并使用 Docker Compose 进行编排，使应用程序高度模块化且可部署。
核心系统示意图：
![核心系统示意图](./doc/core_system.png)

### FastAPI 应用程序
系统的核心是 FastAPI 应用程序，它作为所有客户端交互的主要入口点。FastAPI 处理 HTTP 请求、WebSocket 连接，并与所有其他子系统集成。
关键组件：
* 应用程序实例：在 main.py 中定义为 core FastAPI 应用程序
* 中间件配置：包括 SQLAlchemy 中间件、CORS 和自定义全局中间件
* 请求路由：将请求路由到相应的 API 端点
* WebSocket 支持：用于实时通信，特别是聊天功能
* 生命周期管理：处理资源的初始化和清理

FastAPI 初始化流程：
![FastAPI 初始化流程](./doc/fastapi-init.png)

### 数据库管理
数据库操作通过使用 SQLModel（结合 SQLAlchemy 和 Pydantic）和用于迁移的 Alembic 与 PostgreSQL 建立异步连接来处理。
关键组件：
* 数据库连接池：可配置的异步连接池，用于高效的数据库使用
* SQLModel 集成：提供具有 Pydantic 验证功能的 ORM 功能
* 会话管理：通过 FastAPI 中间件和依赖注入处理
* Alembic 迁移：用于模式版本控制和数据库演进

#### 数据库session配置
根据应用程序模式（开发、测试、生产）而有所不同，并相应地使用不同的池策略：
![数据库session配置](./doc/db-session-config.png)

### 身份验证流程
实现了基于 JWT 的身份验证系统，使用 Redis 进行令牌管理和验证。

关键组件：
* JWT 令牌：用于身份验证的访问令牌和刷新令牌
* Redis 存储：用于令牌验证和撤销
* 基于角色的访问控制：基于用户角色的授权
* 令牌验证中间件：验证受保护端点上的令牌

身份验证流程：
![身份认证流程](./doc/authentication_flow.png)

### 异步任务处理
使用 Celery 和 Redis 作为消息代理来处理异步和计划任务，特别是用于 NLP 处理等资源密集型操作。
关键组件：
* Celery Worker：处理异步任务
* Celery Beat：调度周期性任务
* Redis 代理：用于任务队列管理
* 数据库后端：用于存储任务结果和 beat 计划

异步任务处理流程：
![异步任务处理流程](./doc/async-task-processing-flow.png)

### 文件存储
使用 MinIO（与 S3 兼容的对象存储系统）来存储和提供媒体文件，例如用户个人资料图像。
关键组件：
* MinIO 服务器：核心存储服务
* 存储桶管理：按类型组织文件
* 预签名 URL：用于对存储文件的安全临时访问
* 与用户个人资料集成：用于存储个人资料图像

文件存储流程：
![文件存储流程](./doc/file-storage-flow.png)

### 核心系统的集成
所有核心系统都通过 FastAPI 应用程序集成，以提供一致且可扩展的后端解决方案。以下是它们的交互方式：
![系统集成图](./doc/system-integration.png)

> 进一步文档请参考： [核心系统详解](./doc/core-system.md)