187 lines
7.9 KiB
Markdown
187 lines
7.9 KiB
Markdown
# PBMDB 后端服务
|
||
|
||
## 项目概述
|
||
|
||
PBMDB（微生物数据库）后端服务基于 FastAPI 框架构建，提供 RESTful API 接口，用于支撑前端数据提交系统的核心业务逻辑。后端服务采用 PostgreSQL 数据库存储用户信息和操作记录，通过白名单机制控制数据提交权限，确保只有授权用户才能进行数据操作。
|
||
|
||
## 技术栈
|
||
|
||
- **编程语言**：Python 3.10+
|
||
- **Web 框架**：FastAPI
|
||
- **ASGI 服务器**：Uvicorn
|
||
- **数据库**：PostgreSQL
|
||
- **ORM 框架**：SQLAlchemy
|
||
- **时区处理**：Pytz
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
backend/
|
||
├── app/
|
||
│ ├── __pycache__/ # Python 缓存文件目录
|
||
│ ├── api/ # API 路由模块
|
||
│ │ ├── __pycache__/ # 缓存文件目录
|
||
│ │ ├── db.py # 数据库连接和会话管理
|
||
│ │ ├── login.py # 登录验证相关接口
|
||
│ │ └── submit_record.py # 提交记录相关接口
|
||
│ ├── main.py # FastAPI 应用主入口
|
||
│ ├── settings.py # 配置文件
|
||
│ ├── base_packages.txt # 基础依赖包列表
|
||
│ └── requirements.txt # Python 依赖包列表
|
||
├── environment.yml # Conda 环境配置文件
|
||
└── start_server.py # 服务启动脚本
|
||
```
|
||
|
||
## 核心模块详解
|
||
|
||
### 1. 应用入口（main.py）
|
||
|
||
main.py 是整个后端应用的入口文件，负责初始化 FastAPI 应用实例并配置中间件和路由。应用在启动时会自动创建数据库表结构，确保所有必要的表和字段都已存在。该模块还配置了 CORS（跨源资源共享）中间件，允许前端应用跨域调用 API 接口。路由模块通过前缀 `/api/v1` 组织所有 API 端点，这种设计方式便于后期版本升级和接口扩展。
|
||
|
||
### 2. 配置模块（settings.py）
|
||
|
||
settings.py 集中管理后端服务的所有配置信息。数据库连接字符串采用标准的 PostgreSQL 格式，包含主机地址、端口、数据库名称以及认证凭据。白名单配置指定了用于验证用户邮箱的数据表和字段名称，确保只有特定的用户群体能够访问数据提交功能。提交记录表名配置用于记录用户的操作历史，包括上传和删除操作的时间、类型和存储路径。这些配置信息统一管理，便于在不同环境（开发、测试、生产）之间切换。
|
||
|
||
### 3. 数据库模块（db.py）
|
||
|
||
db.py 封装了所有与数据库交互的底层逻辑。SQLAlchemy 引擎负责建立与 PostgreSQL 数据库的连接池，连接池技术能够有效管理数据库连接资源，提高并发访问性能。会话工厂 SessionLocal 创建独立的数据库会话，每个请求使用独立的会话对象，确保数据操作的隔离性和线程安全。get_db 是一个生成器函数，作为 FastAPI 的依赖项注入到各个路由处理函数中，自动管理数据库会话的创建和关闭，避免资源泄漏。
|
||
|
||
### 4. 登录验证模块（login.py）
|
||
|
||
login.py 实现了用户邮箱白名单验证功能，是数据提交系统的第一道安全屏障。当用户尝试访问数据提交功能时，系统会调用 `/api/v1/check-email` 接口验证用户邮箱是否在白名单中。该接口从 PostgreSQL 数据库的指定表中查询用户邮箱记录，如果邮箱存在于白名单中，则允许用户继续操作；否则返回 403 错误，拒绝用户请求。这种设计确保了数据提交权限的严格控制，只有经过授权的用户才能使用系统功能。
|
||
|
||
### 5. 提交记录模块（submit_record.py）
|
||
|
||
submit_record.py 负责记录用户在系统中的所有数据操作行为，包括数据上传和数据删除两类操作。每当用户执行这些操作时，系统会调用 `/api/v1/submit-record` 接口，将操作信息持久化存储到数据库中。记录内容包括用户邮箱、操作时间、操作类型和数据存储路径。操作时间采用中国时区（Asia/Shanghai）记录，确保时间信息的准确性和一致性。所有操作记录都存储在专用的提交记录表中，便于后续审计追溯和数据管理。系统通过事务机制确保记录插入的原子性，任何失败的操作都会触发回滚，保证数据完整性。
|
||
|
||
## API 接口文档
|
||
|
||
### 基础信息
|
||
|
||
- **基础路径**：`/api/v1`
|
||
- **数据格式**：JSON
|
||
- **字符编码**：UTF-8
|
||
|
||
### 接口列表
|
||
|
||
#### 1. 邮箱白名单验证
|
||
|
||
- **端点**：`POST /api/v1/check-email`
|
||
- **功能描述**：检查用户邮箱是否在白名单中
|
||
- **请求体**：
|
||
```json
|
||
{
|
||
"email": "user@example.com"
|
||
}
|
||
```
|
||
- **成功响应**：
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"message": "继续操作"
|
||
}
|
||
```
|
||
- **错误响应**：
|
||
```json
|
||
{
|
||
"detail": "邮箱不在白名单中，请联系管理员"
|
||
}
|
||
```
|
||
|
||
#### 2. 提交操作记录
|
||
|
||
- **端点**：`POST /api/v1/submit-record`
|
||
- **功能描述**：记录用户的数据上传或删除操作
|
||
- **请求体**：
|
||
```json
|
||
{
|
||
"user_email": "user@example.com",
|
||
"operation_type": "upload",
|
||
"storage_path": "/data/user/example/"
|
||
}
|
||
```
|
||
- **成功响应**：
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"message": "操作记录已保存"
|
||
}
|
||
```
|
||
- **错误响应**：
|
||
```json
|
||
{
|
||
"detail": "操作类型必须是 'upload' 或 'delete'"
|
||
}
|
||
```
|
||
|
||
## 工作流程
|
||
|
||
### 数据提交流程
|
||
|
||
用户访问数据提交页面时，前端首先调用邮箱验证接口确认用户身份。系统查询数据库中的白名单表，验证用户邮箱是否具有提交权限。验证通过后，用户可以上传数据文件，上传完成后前端调用提交记录接口将操作信息写入数据库。整个流程采用同步方式处理，每个步骤的结果都会实时反馈给用户，确保操作的可控性和可追溯性。
|
||
|
||
### 权限控制机制
|
||
|
||
权限控制采用白名单模式实现，所有能够访问数据提交功能的用户邮箱必须预先录入系统数据库。白名单验证在用户首次访问提交页面时触发，通过后即可进行后续操作。这种设计简化了权限管理的复杂度，同时保证了数据访问的安全性。白名单数据存储在专用的数据库表中，管理员可以通过直接操作数据库的方式管理用户权限。
|
||
|
||
### 操作审计机制
|
||
|
||
系统自动记录所有数据操作行为，包括上传和删除两类操作。每条记录包含操作者的邮箱地址、操作发生的时间戳、操作的具体类型以及相关数据的存储位置。时间戳采用中国标准时间，确保审计日志的时间信息与实际业务操作一致。所有操作记录持久化存储到 PostgreSQL 数据库中，支持按时间范围、用户邮箱、操作类型等条件进行查询和筛选，便于事后审计和问题追溯。
|
||
|
||
## 数据库配置
|
||
|
||
### 连接信息
|
||
|
||
当前数据库配置指向远程 PostgreSQL 服务器，连接信息如下：
|
||
|
||
- **主机**：`122.205.95.244`
|
||
- **端口**：`5433`
|
||
- **数据库名称**：`ABM_DB`
|
||
- **用户名**：`ABM_DB_user`
|
||
|
||
### 数据表结构
|
||
|
||
系统依赖以下核心数据表：
|
||
|
||
- **submit_user**：存储允许访问系统的用户邮箱白名单
|
||
- **submit_record**：存储用户的数据操作记录，包括操作时间、类型和存储路径
|
||
|
||
## 环境配置
|
||
|
||
### Conda 环境
|
||
|
||
使用 Conda 管理 Python 环境，可以通过 environment.yml 文件创建相同的运行环境：
|
||
|
||
```bash
|
||
conda env create -f environment.yml
|
||
conda activate pbmdb_backend
|
||
```
|
||
|
||
### 依赖安装
|
||
|
||
如果使用 pip 安装依赖，可以执行以下命令：
|
||
|
||
```bash
|
||
pip install -r app/requirements.txt
|
||
```
|
||
|
||
## 启动服务
|
||
|
||
### 开发模式启动
|
||
|
||
```bash
|
||
cd backend
|
||
python start_server.py
|
||
```
|
||
|
||
服务启动后，默认监听 `0.0.0.0:8000` 端口。开发模式下启用热重载功能，代码修改后服务会自动重启。
|
||
|
||
### 生产模式启动
|
||
|
||
```bash
|
||
uvicorn app.main:app --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
生产模式下建议关闭热重载，并配置进程管理器（如 systemd）管理服务生命周期。
|
||
|