# 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）管理服务生命周期。