labweb/README.md

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
• 功能描述：检查用户邮箱是否在白名单中
• 请求体：

  {
    "email": "user@example.com"
  }
  

• 成功响应：

  {
    "status": "success",
    "message": "继续操作"
  }
  

• 错误响应：

  {
    "detail": "邮箱不在白名单中，请联系管理员"
  }
  

2. 提交操作记录

• 端点：POST /api/v1/submit-record
• 功能描述：记录用户的数据上传或删除操作
• 请求体：

  {
    "user_email": "user@example.com",
    "operation_type": "upload",
    "storage_path": "/data/user/example/"
  }
  

• 成功响应：

  {
    "status": "success",
    "message": "操作记录已保存"
  }
  

• 错误响应：

  {
    "detail": "操作类型必须是 'upload' 或 'delete'"
  }
  

工作流程

数据提交流程

用户访问数据提交页面时，前端首先调用邮箱验证接口确认用户身份。系统查询数据库中的白名单表，验证用户邮箱是否具有提交权限。验证通过后，用户可以上传数据文件，上传完成后前端调用提交记录接口将操作信息写入数据库。整个流程采用同步方式处理，每个步骤的结果都会实时反馈给用户，确保操作的可控性和可追溯性。

权限控制机制

权限控制采用白名单模式实现，所有能够访问数据提交功能的用户邮箱必须预先录入系统数据库。白名单验证在用户首次访问提交页面时触发，通过后即可进行后续操作。这种设计简化了权限管理的复杂度，同时保证了数据访问的安全性。白名单数据存储在专用的数据库表中，管理员可以通过直接操作数据库的方式管理用户权限。

操作审计机制

系统自动记录所有数据操作行为，包括上传和删除两类操作。每条记录包含操作者的邮箱地址、操作发生的时间戳、操作的具体类型以及相关数据的存储位置。时间戳采用中国标准时间，确保审计日志的时间信息与实际业务操作一致。所有操作记录持久化存储到 PostgreSQL 数据库中，支持按时间范围、用户邮箱、操作类型等条件进行查询和筛选，便于事后审计和问题追溯。

数据库配置

连接信息

当前数据库配置指向远程 PostgreSQL 服务器，连接信息如下：

• 主机：122.205.95.244
• 端口：5433
• 数据库名称：ABM_DB
• 用户名：ABM_DB_user

数据表结构

系统依赖以下核心数据表：

• submit_user：存储允许访问系统的用户邮箱白名单
• submit_record：存储用户的数据操作记录，包括操作时间、类型和存储路径

环境配置

Conda 环境

使用 Conda 管理 Python 环境，可以通过 environment.yml 文件创建相同的运行环境：

conda env create -f environment.yml
conda activate pbmdb_backend

依赖安装

如果使用 pip 安装依赖，可以执行以下命令：

pip install -r app/requirements.txt

启动服务

开发模式启动

cd backend
python start_server.py

服务启动后，默认监听 0.0.0.0:8000 端口。开发模式下启用热重载功能，代码修改后服务会自动重启。

生产模式启动

uvicorn app.main:app --host 0.0.0.0 --port 8000

生产模式下建议关闭热重载，并配置进程管理器（如 systemd）管理服务生命周期。