298 lines
7.5 KiB
Markdown
298 lines
7.5 KiB
Markdown
# 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. 创建环境变量文件
|
||
|
||
```bash
|
||
cd /vol1/1000/docker_server/traefik/web/ws/backend
|
||
cp .env.example .env
|
||
```
|
||
|
||
编辑 `.env` 文件：
|
||
|
||
```bash
|
||
# 项目信息
|
||
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
|
||
```
|
||
|
||
## 🏃 本地开发
|
||
|
||
### 使用虚拟环境
|
||
|
||
```bash
|
||
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` 中添加后端服务：
|
||
|
||
```yaml
|
||
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. 构建并启动
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
# 进入容器
|
||
docker compose exec backend bash
|
||
|
||
# 初始化迁移（首次）
|
||
alembic init alembic
|
||
|
||
# 创建迁移
|
||
alembic revision --autogenerate -m "Initial migration"
|
||
|
||
# 执行迁移
|
||
alembic upgrade head
|
||
```
|
||
|
||
## 🧪 测试 API
|
||
|
||
### 使用 curl
|
||
|
||
```bash
|
||
# 健康检查
|
||
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 官方文档](https://fastapi.tiangolo.com/)
|
||
- [Pydantic 文档](https://docs.pydantic.dev/)
|
||
- [SQLAlchemy 文档](https://docs.sqlalchemy.org/)
|
||
- [Uvicorn 文档](https://www.uvicorn.org/)
|
||
|
||
## 📞 联系方式
|
||
|
||
如有问题，请联系项目维护团队。
|