labweb/web/ws/backend/README.md

FastAPI 后端项目

PBMDB (Plant Beneficial Microbe Database) 农业有益微生物综合信息数据库后端 API 服务。

📁 项目结构

backend/
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI 应用入口
│   ├── api/
│   │   ├── __init__.py
│   │   └── v1/
│   │       ├── __init__.py
│   │       ├── router.py    # API 路由汇总
│   │       └── endpoints/
│   │           ├── __init__.py
│   │           ├── strains.py      # 菌种资源 API
│   │           ├── genomes.py      # 基因组学数据 API
│   │           ├── genes.py        # 基因资源 API
│   │           ├── upload.py       # 数据汇交上传 API
│   │           └── analysis.py     # 智能分析 API
│   ├── core/
│   │   ├── __init__.py
│   │   ├── config.py        # 应用配置
│   │   └── security.py      # 认证安全
│   ├── models/              # SQLAlchemy 数据模型
│   │   └── __init__.py
│   ├── schemas/             # Pydantic 数据模式
│   │   └── __init__.py
│   └── services/            # 业务逻辑层
│       └── __init__.py
├── requirements.txt         # Python 依赖
├── Dockerfile              # Docker 构建文件
├── .env.example           # 环境变量示例
└── README.md              # 本文件

🚀 技术栈

• FastAPI: 现代、高性能 Python Web 框架
• Uvicorn: ASGI 服务器
• SQLAlchemy: ORM 数据库工具
• PostgreSQL: 关系型数据库
• Pydantic: 数据验证和设置管理

🎯 核心功能模块

1. 菌种资源 (/api/v1/strains)

• 菌种列表查询（分类、搜索、分页）
• 菌种详情展示
• 菌种分类树

2. 基因组学数据 (/api/v1/genomes)

• 基因组数据列表（基因组学/转录组学/其他组学）
• 基因组详情
• 物种分类树

3. 基因资源 (/api/v1/genes)

• 基因列表查询（功能分类）
• 基因详情
• 功能基因分类

4. 数据汇交 (/api/v1/upload)

• 基因组数据上传
• 宏基因组数据上传
• 原始测序数据上传
• 上传口令验证
• 上传状态查询

5. 智能分析 (/api/v1/analysis)

• 智能问答（基于知识图谱）
• 基因挖掘（序列比对）
• 菌株评估
• 知识图谱查询
• 分析任务状态查询

⚙️ 环境配置

1. 创建环境变量文件

cd /vol1/1000/docker_server/traefik/web/ws/backend
cp .env.example .env

编辑 .env 文件：

# 项目信息
PROJECT_NAME=PBMDB API
VERSION=1.0.0

# 数据库配置
DATABASE_URL=postgresql://webws_admin:your_password@postgres:5432/webws_database

# 安全配置
SECRET_KEY=your-secret-key-here-change-in-production

# CORS 配置
ALLOWED_ORIGINS=https://amiap.hzau.edu.cn,http://localhost:3000

# 文件上传配置
MAX_UPLOAD_SIZE=104857600
UPLOAD_DIR=/app/uploads

🏃 本地开发

使用虚拟环境

cd /vol1/1000/docker_server/traefik/web/ws/backend

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 运行开发服务器
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

访问：

• API 文档: http://localhost:8000/docs
• ReDoc 文档: http://localhost:8000/redoc
• 健康检查: http://localhost:8000/health

🐳 Docker 部署

1. 更新 docker-compose.yml

在 /vol1/1000/docker_server/traefik/web/ws/docker-compose.yml 中添加后端服务：

services:
  # ... 现有服务 ...
  
  backend:
    build: ./backend
    container_name: webws-backend
    restart: unless-stopped
    environment:
      - DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
    volumes:
      - ./backend/uploads:/app/uploads
    networks:
      - frontend
    depends_on:
      - postgres
    labels:
      - "traefik.enable=true"
      
      # HTTP 路由 - 重定向到 HTTPS
      - "traefik.http.routers.webws-api-http.rule=Host(`amiap.hzau.edu.cn`) && PathPrefix(`/ABM/api`)"
      - "traefik.http.routers.webws-api-http.entrypoints=web"
      - "traefik.http.routers.webws-api-http.priority=100"
      - "traefik.http.routers.webws-api-http.middlewares=redirect-to-https"
      
      # HTTPS 路由
      - "traefik.http.routers.webws-api-https.rule=Host(`amiap.hzau.edu.cn`) && PathPrefix(`/ABM/api`)"
      - "traefik.http.routers.webws-api-https.entrypoints=websecure"
      - "traefik.http.routers.webws-api-https.priority=100"
      - "traefik.http.routers.webws-api-https.tls.certresolver=myresolver"
      
      # StripPrefix 中间件（移除 /ABM/api 前缀）
      - "traefik.http.routers.webws-api-https.middlewares=api-stripprefix"
      - "traefik.http.middlewares.api-stripprefix.stripprefix.prefixes=/ABM/api"
      
      - "traefik.http.services.webws-api.loadbalancer.server.port=8000"

2. 构建并启动

cd /vol1/1000/docker_server/traefik/web/ws

# 构建镜像
docker compose build backend

# 启动服务
docker compose up -d backend

# 查看日志
docker compose logs -f backend

📡 API 访问地址

部署后，API 通过以下地址访问：

• 外部访问: https://amiap.hzau.edu.cn/ABM/api/
• API 文档: https://amiap.hzau.edu.cn/ABM/api/docs
• 容器间访问: http://webws-backend:8000/

🔧 路由说明

URL 路径处理

由于使用了 Traefik StripPrefix 中间件，路径会自动处理：

用户访问: https://amiap.hzau.edu.cn/ABM/api/strains/ FastAPI 接收: /api/v1/strains/ (已移除 /ABM/api)

路由优先级

Priority 100: /ABM/api/** → 后端 API 服务
Priority 47:  /ABM/**     → Nginx 静态文件服务

不会产生冲突，Traefik 优先匹配更高优先级和更具体的路径。

📊 数据库迁移

使用 Alembic

# 进入容器
docker compose exec backend bash

# 初始化迁移（首次）
alembic init alembic

# 创建迁移
alembic revision --autogenerate -m "Initial migration"

# 执行迁移
alembic upgrade head

🧪 测试 API

使用 curl

# 健康检查
curl https://amiap.hzau.edu.cn/ABM/api/health

# 获取菌种列表
curl https://amiap.hzau.edu.cn/ABM/api/api/v1/strains/

# 获取基因组数据
curl https://amiap.hzau.edu.cn/ABM/api/api/v1/genomes/

使用 Swagger UI

访问 https://amiap.hzau.edu.cn/ABM/api/docs 进行交互式测试。

📝 开发指南

添加新的 API 端点

1. 在 app/api/v1/endpoints/ 下创建新文件
2. 定义路由和处理函数
3. 在 app/api/v1/router.py 中注册路由

添加数据模型

1. 在 app/models/ 下创建 SQLAlchemy 模型
2. 在 app/schemas/ 下创建 Pydantic 模式
3. 运行数据库迁移

添加业务逻辑

在 app/services/ 下创建服务层代码，保持控制器简洁。

🔒 安全注意事项

1. 生产环境必须修改 SECRET_KEY
2. 使用环境变量管理敏感信息
3. 启用 HTTPS（已配置）
4. 实现完整的认证系统（待实现）
5. 添加请求频率限制

🚀 性能优化

1. 使用数据库连接池
2. 启用查询缓存（Redis）
3. 异步文件处理
4. 压缩响应数据
5. CDN 加速静态资源

📚 相关文档

• FastAPI 官方文档
• Pydantic 文档
• SQLAlchemy 文档
• Uvicorn 文档

📞 联系方式

如有问题，请联系项目维护团队。