后端初始化结构
This commit is contained in:
zly
297
web/ws/backend/README.md
Normal file
297
web/ws/backend/README.md
Normal file
@@ -0,0 +1,297 @@
|
||||
# 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/)
|
||||
|
||||
## 📞 联系方式
|
||||
|
||||
如有问题，请联系项目维护团队。
|
||||
Reference in New Issue
Block a user