# Docker容器化部署

<cite>
**本文档引用的文件**
- [docker-compose.yml](file://docker-compose.yml)
- [backend/Dockerfile](file://backend/Dockerfile)
- [frontend/Dockerfile](file://frontend/Dockerfile)
- [backend/requirements.txt](file://backend/requirements.txt)
- [frontend/package.json](file://frontend/package.json)
- [backend/app/config.py](file://backend/app/config.py)
- [backend/app/main.py](file://backend/app/main.py)
- [backend/app/database.py](file://backend/app/database.py)
- [backend/app/workers/scheduler.py](file://backend/app/workers/scheduler.py)
- [backend/alembic.ini](file://backend/alembic.ini)
- [frontend/next.config.mjs](file://frontend/next.config.mjs)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介

GEO项目是一个基于FastAPI和Next.js的引文检索平台，采用Docker容器化部署方案。该部署方案提供了完整的微服务架构，包括PostgreSQL数据库、Redis缓存、后端API服务和前端Web应用。

本项目的核心目标是通过容器化技术实现开发环境的一致性和生产环境的可移植性，同时确保各服务之间的可靠通信和数据持久化。

## 项目结构

项目采用多容器架构，包含四个主要服务：

```mermaid
graph TB
subgraph "Docker Compose编排"
DC[docker-compose.yml]
subgraph "数据库层"
DB[PostgreSQL 15]
RD[Redis 7]
end
subgraph "应用层"
BE[FastAPI 后端]
FE[Next.js 前端]
end
subgraph "存储卷"
PV[postgres_data]
RV[redis_data]
end
end
DC --> DB
DC --> RD
DC --> BE
DC --> FE
DB --> PV
RD --> RV
```

**图表来源**
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)

**章节来源**
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)

## 核心组件

### 数据库服务 (PostgreSQL)

数据库服务使用PostgreSQL 15-alpine镜像，配置了完整的环境变量和健康检查机制：

- **镜像版本**: postgres:15-alpine
- **容器名称**: geo_db
- **端口映射**: 5432:5432
- **数据持久化**: 使用postgres_data命名卷
- **环境变量**: 用户名、密码、数据库名
- **健康检查**: 每5秒检查一次数据库连接

### 缓存服务 (Redis)

Redis服务提供高性能的键值存储和任务队列功能：

- **镜像版本**: redis:7-alpine
- **容器名称**: geo_redis
- **端口映射**: 6379:6379
- **数据持久化**: 使用redis_data命名卷
- **健康检查**: PING命令测试

### 后端服务 (FastAPI)

后端服务基于Python 3.11-slim，提供RESTful API接口：

- **基础镜像**: python:3.11-slim
- **容器名称**: geo_backend
- **端口映射**: 8000:8000
- **开发模式**: 支持代码热重载
- **依赖安装**: Playwright浏览器支持

### 前端服务 (Next.js)

前端服务提供现代化的用户界面：

- **基础镜像**: node:20-alpine
- **容器名称**: geo_frontend
- **端口映射**: 3000:3000
- **开发模式**: Next.js开发服务器
- **依赖管理**: npm包管理器

**章节来源**
- [docker-compose.yml:3-71](file://docker-compose.yml#L3-L71)

## 架构概览

系统采用分层架构设计，确保服务间的松耦合和高内聚：

```mermaid
graph TB
subgraph "客户端层"
Browser[Web浏览器]
Mobile[移动应用]
end
subgraph "API网关层"
Nginx[Nginx反向代理]
end
subgraph "应用服务层"
subgraph "后端服务"
Auth[认证服务]
Query[查询服务]
Citation[引文服务]
Report[报告服务]
end
subgraph "任务处理层"
Scheduler[调度器]
Worker[工作进程]
end
end
subgraph "数据存储层"
subgraph "数据库"
PostgreSQL[PostgreSQL]
Redis[Redis缓存]
end
subgraph "文件存储"
MinIO[S3兼容存储]
end
end
Browser --> Nginx
Mobile --> Nginx
Nginx --> Auth
Nginx --> Query
Nginx --> Citation
Nginx --> Report
Auth --> PostgreSQL
Query --> PostgreSQL
Citation --> PostgreSQL
Report --> PostgreSQL
Query --> Redis
Citation --> Redis
Report --> Redis
Scheduler --> PostgreSQL
Scheduler --> Redis
Worker --> PostgreSQL
Worker --> Redis
```

**图表来源**
- [backend/app/main.py:24-48](file://backend/app/main.py#L24-L48)
- [backend/app/config.py:7-8](file://backend/app/config.py#L7-L8)

## 详细组件分析

### Docker Compose配置详解

#### 服务依赖关系

```mermaid
sequenceDiagram
participant DB as "PostgreSQL"
participant Redis as "Redis"
participant Backend as "FastAPI"
participant Frontend as "Next.js"
Note over DB,Redis : 服务启动顺序
DB->>DB : 初始化数据库
Redis->>Redis : 启动缓存服务
Backend->>DB : 等待数据库就绪
Backend->>Redis : 等待缓存就绪
Backend->>Backend : 启动Uvicorn服务
Frontend->>Backend : 发起API请求
Frontend->>Frontend : 启动开发服务器
```

**图表来源**
- [docker-compose.yml:46-66](file://docker-compose.yml#L46-L66)

#### 网络配置

Docker Compose自动创建隔离的网络环境，各服务通过服务名进行内部通信：

- **内部DNS**: 服务间通过服务名访问
- **端口映射**: 开发环境暴露必要端口
- **卷挂载**: 数据持久化和代码热重载

#### 数据卷配置

```mermaid
graph LR
subgraph "宿主机"
Host[宿主机文件系统]
end
subgraph "Docker卷"
PV[postgres_data]
RV[redis_data]
FV[node_modules]
end
subgraph "容器内"
ContainerDB[数据库数据]
ContainerRedis[Redis数据]
ContainerFE[前端模块]
end
Host --> PV
Host --> RV
Host --> FV
PV --> ContainerDB
RV --> ContainerRedis
FV --> ContainerFE
```

**图表来源**
- [docker-compose.yml:14-15](file://docker-compose.yml#L14-L15)
- [docker-compose.yml:28-29](file://docker-compose.yml#L28-L29)
- [docker-compose.yml:61-63](file://docker-compose.yml#L61-L63)

**章节来源**
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)

### 后端Dockerfile构建流程

后端服务采用多阶段构建策略，优化镜像大小和构建效率：

```mermaid
flowchart TD
Start([开始构建]) --> BaseImage["基础镜像<br/>python:3.11-slim"]
BaseImage --> InstallDeps["安装系统依赖<br/>apt-get更新"]
InstallDeps --> CopyReq["复制依赖文件<br/>requirements.txt"]
CopyReq --> InstallPy["安装Python依赖<br/>pip安装"]
InstallPy --> InstallPW["安装Playwright<br/>chromium浏览器"]
InstallPW --> CopyCode["复制应用代码"]
CopyCode --> ExposePort["暴露端口<br/>8000"]
ExposePort --> CMD["启动命令<br/>uvicorn"]
CMD --> End([构建完成])
InstallDeps -.-> SysDeps["系统依赖:<br/>curl, wget, libglib2.0-0,<br/>libnss3, libatk1.0-0,<br/>libcairo2, libasound2"]
InstallPy -.-> PyDeps["Python依赖:<br/>FastAPI, SQLAlchemy,<br/>Redis, APScheduler,<br/>Playwright"]
```

**图表来源**
- [backend/Dockerfile:1-41](file://backend/Dockerfile#L1-L41)
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)

#### 关键构建步骤

1. **系统依赖安装**: 安装Playwright运行所需的系统库
2. **Python环境配置**: 设置工作目录和依赖管理
3. **应用代码部署**: 复制业务逻辑代码
4. **运行时优化**: 配置Uvicorn ASGI服务器

**章节来源**
- [backend/Dockerfile:1-41](file://backend/Dockerfile#L1-L41)
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)

### 前端Dockerfile构建流程

前端服务构建流程相对简洁，专注于开发环境优化：

```mermaid
flowchart TD
Start([开始构建]) --> BaseImage["基础镜像<br/>node:20-alpine"]
BaseImage --> WorkDir["设置工作目录<br/>/app"]
WorkDir --> CopyPkg["复制包文件<br/>package.json, lock.json"]
CopyPkg --> InstallDeps["安装依赖<br/>npm ci"]
InstallDeps --> CopyCode["复制应用代码"]
CopyCode --> ExposePort["暴露端口<br/>3000"]
ExposePort --> CMD["启动命令<br/>npm run dev"]
CMD --> End([构建完成])
```

**图表来源**
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)
- [frontend/package.json:1-40](file://frontend/package.json#L1-L40)

#### 依赖管理策略

- **生产依赖**: Next.js 14.2.35，React 18
- **开发依赖**: TypeScript，ESLint，Tailwind CSS
- **UI组件**: Radix UI，Lucide React图标库

**章节来源**
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)
- [frontend/package.json:1-40](file://frontend/package.json#L1-L40)

### 环境变量配置

系统使用统一的环境变量配置机制，支持不同环境的灵活切换：

```mermaid
classDiagram
class Settings {
+string DATABASE_URL
+string REDIS_URL
+string JWT_SECRET
+int JWT_EXPIRE_HOURS
+string PLAYWRIGHT_BROWSERS_PATH
+string ZHIPU_API_KEY
+string TONGYI_API_KEY
}
class ConfigFile {
+string env_file
+string extra
}
class Environment {
+Development
+Production
+Testing
}
Settings --> ConfigFile : "读取配置"
Settings --> Environment : "根据环境变化"
```

**图表来源**
- [backend/app/config.py:4-16](file://backend/app/config.py#L4-L16)

#### 核心配置参数

| 参数名称 | 默认值 | 用途描述 |
|---------|--------|----------|
| DATABASE_URL | postgresql+asyncpg://postgres:postgres123@db:5432/geo_platform | 数据库连接字符串 |
| REDIS_URL | redis://redis:6379/0 | Redis缓存连接地址 |
| JWT_SECRET | your-secret-key-change-in-production | JWT令牌密钥 |
| JWT_EXPIRE_HOURS | 24 | JWT过期时间(小时) |
| PLAYWRIGHT_BROWSERS_PATH | /ms-playwright | Playwright浏览器路径 |

**章节来源**
- [backend/app/config.py:7-13](file://backend/app/config.py#L7-L13)

### 健康检查机制

系统实现了多层次的健康检查，确保服务可用性：

```mermaid
graph TB
subgraph "健康检查层次"
HC[健康检查总览]
subgraph "数据库健康"
DBHC[PostgreSQL健康]
DBTest["pg_isready -U postgres -d geo_platform"]
end
subgraph "缓存健康"
RHC[Redis健康]
RTest["redis-cli ping"]
end
subgraph "应用健康"
BHC[后端健康]
BTest["HTTP GET /health"]
FHC[前端健康]
FTest["HTTP GET /"]
end
end
HC --> DBHC
HC --> RHC
HC --> BHC
HC --> FHC
DBHC --> DBTest
RHC --> RTest
BHC --> BTest
FHC --> FTest
```

**图表来源**
- [docker-compose.yml:16-20](file://docker-compose.yml#L16-L20)
- [docker-compose.yml:30-34](file://docker-compose.yml#L30-L34)
- [backend/app/main.py:45-47](file://backend/app/main.py#L45-L47)

#### 健康检查配置

- **检查间隔**: 5秒
- **超时时间**: 5秒  
- **重试次数**: 5次
- **检查方式**: 
  - PostgreSQL: 数据库连接测试
  - Redis: PING命令响应
  - 应用: HTTP端点响应

**章节来源**
- [docker-compose.yml:16-34](file://docker-compose.yml#L16-L34)
- [backend/app/main.py:45-47](file://backend/app/main.py#L45-L47)

## 依赖关系分析

### 服务间依赖图

```mermaid
graph TD
subgraph "外部依赖"
PG[PostgreSQL]
RD[Redis]
PW[Playwright]
end
subgraph "后端服务"
FA[FastAPI]
SQ[SQLAlchemy]
AP[APScheduler]
RE[Redis Client]
end
subgraph "前端服务"
NX[Next.js]
RC[React]
TW[Tailwind CSS]
end
subgraph "开发工具"
UV[Uvicorn]
NP[npm]
PY[Python]
end
FA --> SQ
FA --> AP
FA --> RE
FA --> PW
NX --> RC
NX --> TW
FA --> UV
NX --> NP
FA --> PY
```

**图表来源**
- [backend/requirements.txt:2-35](file://backend/requirements.txt#L2-L35)
- [frontend/package.json:11-38](file://frontend/package.json#L11-L38)

### 数据库连接分析

后端服务通过异步数据库连接池与PostgreSQL交互：

```mermaid
sequenceDiagram
participant App as "FastAPI应用"
participant Engine as "SQLAlchemy引擎"
participant Pool as "连接池"
participant DB as "PostgreSQL"
App->>Engine : 创建异步引擎
Engine->>Pool : 初始化连接池
Pool->>DB : 建立数据库连接
DB-->>Pool : 连接确认
Pool-->>Engine : 连接可用
Engine-->>App : 引擎就绪
App->>Engine : 获取数据库会话
Engine->>Pool : 从池中获取连接
Pool->>DB : 执行SQL查询
DB-->>Pool : 返回查询结果
Pool-->>Engine : 释放连接
Engine-->>App : 会话完成
```

**图表来源**
- [backend/app/database.py:6-28](file://backend/app/database.py#L6-L28)
- [backend/app/config.py:7](file://backend/app/config.py#L7)

**章节来源**
- [backend/requirements.txt:5-8](file://backend/requirements.txt#L5-L8)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)

### 任务调度系统

系统实现了基于APScheduler的异步任务调度机制：

```mermaid
flowchart TD
Start([应用启动]) --> InitScheduler["初始化调度器"]
InitScheduler --> AddJob["添加定时任务<br/>check_queries"]
AddJob --> StartJobs["启动所有任务"]
StartJobs --> Timer["1小时定时器"]
Timer --> CheckQueries["检查到期查询"]
CheckQueries --> ExecuteQuery["执行查询任务"]
ExecuteQuery --> UpdateSchedule["更新下次执行时间"]
UpdateSchedule --> Timer
CheckQueries --> ErrorHandle["错误处理"]
ErrorHandle --> Continue["继续下一个查询"]
subgraph "查询执行流程"
ExecuteQuery --> GetPlatform["获取平台列表"]
GetPlatform --> ExecutePlatform["执行平台查询"]
ExecutePlatform --> CreateRecord["创建引文记录"]
CreateRecord --> UpdateQuery["更新查询状态"]
end
```

**图表来源**
- [backend/app/workers/scheduler.py:30-95](file://backend/app/workers/scheduler.py#L30-L95)

**章节来源**
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)

## 性能考虑

### 容器资源优化

1. **镜像大小控制**: 使用alpine基础镜像减少体积
2. **多阶段构建**: 分离构建和运行时环境
3. **依赖精简**: 只安装必要的系统和Python依赖
4. **缓存利用**: npm和pip缓存提高构建速度

### 数据库性能优化

- **连接池管理**: SQLAlchemy异步连接池
- **索引优化**: 查询表的关键字段建立索引
- **查询优化**: 使用异步查询避免阻塞
- **事务管理**: 合理的事务边界控制

### 缓存策略

- **Redis缓存**: 高速数据缓存
- **浏览器缓存**: 前端静态资源缓存
- **CDN加速**: 生产环境静态资源分发

## 故障排查指南

### 常见问题诊断

#### 1. 数据库连接问题

**症状**: 后端服务启动失败，显示数据库连接错误

**排查步骤**:
1. 检查PostgreSQL容器状态
2. 验证数据库凭据配置
3. 确认网络连通性
4. 查看数据库日志

**解决方案**:
- 确保PostgreSQL服务先于后端启动
- 检查DATABASE_URL格式正确性
- 验证数据库用户权限

#### 2. 前端开发服务器问题

**症状**: 前端无法访问，页面加载失败

**排查步骤**:
1. 检查Node.js版本兼容性
2. 验证npm依赖安装
3. 确认端口占用情况
4. 查看浏览器控制台错误

**解决方案**:
- 清理node_modules缓存
- 重新安装npm依赖
- 检查防火墙设置

#### 3. 任务调度异常

**症状**: 引文查询任务未按时执行

**排查步骤**:
1. 检查调度器状态
2. 验证查询表数据
3. 查看任务执行日志
4. 确认Redis连接正常

**解决方案**:
- 重启调度器服务
- 检查查询状态字段
- 验证平台API密钥

### 日志监控

系统提供了多层级的日志输出：

```mermaid
graph TB
subgraph "日志级别"
Debug[调试日志]
Info[信息日志]
Warn[警告日志]
Error[错误日志]
end
subgraph "日志来源"
DBLog[数据库日志]
TaskLog[任务日志]
AppLog[应用日志]
SysLog[系统日志]
end
Debug --> DBLog
Debug --> TaskLog
Debug --> AppLog
Debug --> SysLog
Info --> DBLog
Info --> TaskLog
Info --> AppLog
Info --> SysLog
Warn --> DBLog
Warn --> TaskLog
Warn --> AppLog
Warn --> SysLog
Error --> DBLog
Error --> TaskLog
Error --> AppLog
Error --> SysLog
```

**章节来源**
- [backend/app/workers/scheduler.py:22](file://backend/app/workers/scheduler.py#L22)
- [backend/app/main.py:45-47](file://backend/app/main.py#L45-L47)

### 环境变量验证

建议在启动前验证关键环境变量：

```bash
# 检查数据库连接
docker exec geo_db pg_isready -U postgres -d geo_platform

# 检查Redis连接
docker exec geo_redis redis-cli ping

# 检查后端API
curl http://localhost:8000/health

# 检查前端应用
curl http://localhost:3000
```

## 结论

GEO项目的Docker容器化部署方案提供了完整的微服务架构实现，具有以下优势：

1. **开发友好**: 支持代码热重载和快速迭代
2. **环境一致**: 容器化确保开发和生产环境一致性
3. **扩展性强**: 模块化设计便于功能扩展
4. **运维简便**: 健康检查和日志监控提升可维护性

该部署方案为GEO平台的稳定运行和未来发展奠定了坚实的技术基础。

## 附录

### 完整部署流程

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant Docker as "Docker引擎"
participant Compose as "Docker Compose"
participant Registry as "镜像仓库"
Dev->>Compose : docker-compose up -d
Compose->>Registry : 拉取基础镜像
Registry-->>Compose : 返回镜像
Compose->>Docker : 构建自定义镜像
Docker-->>Compose : 镜像构建完成
Compose->>Docker : 启动数据库容器
Compose->>Docker : 启动缓存容器
Compose->>Docker : 启动后端容器
Compose->>Docker : 启动前端容器
Docker-->>Dev : 服务启动完成
```

### 最佳实践建议

1. **生产环境优化**
   - 使用生产级数据库和缓存
   - 配置负载均衡和反向代理
   - 实施监控和告警系统

2. **安全加固**
   - 使用HTTPS证书
   - 配置防火墙规则
   - 定期更新依赖包

3. **性能调优**
   - 监控容器资源使用
   - 优化数据库查询
   - 实施缓存策略

**章节来源**
- [docker-compose.yml:36-66](file://docker-compose.yml#L36-L66)
- [backend/app/config.py:9](file://backend/app/config.py#L9)