# 部署与运维

<cite>
**本文引用的文件**
- [docker-compose.yml](file://docker-compose.yml)
- [backend/Dockerfile](file://backend/Dockerfile)
- [frontend/Dockerfile](file://frontend/Dockerfile)
- [backend/app/main.py](file://backend/app/main.py)
- [backend/app/config.py](file://backend/app/config.py)
- [backend/requirements.txt](file://backend/requirements.txt)
- [frontend/package.json](file://frontend/package.json)
- [backend/app/workers/scheduler.py](file://backend/app/workers/scheduler.py)
- [backend/app/api/auth.py](file://backend/app/api/auth.py)
- [backend/app/database.py](file://backend/app/database.py)
- [backend/app/models/query.py](file://backend/app/models/query.py)
- [backend/alembic.ini](file://backend/alembic.ini)
- [backend/alembic/env.py](file://backend/alembic/env.py)
- [backend/app/middleware/logging_middleware.py](file://backend/app/middleware/logging_middleware.py)
- [backend/app/middleware/rate_limit.py](file://backend/app/middleware/rate_limit.py)
- [tests/test_auth.py](file://tests/test_auth.py)
</cite>

## 更新摘要
**所做更改**
- 新增完整的Docker容器化部署配置说明
- 补充生产环境部署策略与最佳实践
- 完善监控日志管理方案与运维指南
- 增加CI/CD流水线与自动化部署配置
- 更新环境配置与安全加固措施

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [Docker容器化部署](#docker容器化部署)
7. [生产环境部署策略](#生产环境部署策略)
8. [监控与日志管理](#监控与日志管理)
9. [运维最佳实践](#运维最佳实践)
10. [CI/CD流水线配置](#cicd流水线配置)
11. [依赖分析](#依赖分析)
12. [性能考虑](#性能考虑)
13. [故障排查指南](#故障排查指南)
14. [结论](#结论)
15. [附录](#附录)

## 简介
本文件面向GEO项目的部署与运维团队，提供从开发到生产的完整落地指南。内容覆盖Docker容器化部署、镜像构建、服务编排与环境配置；生产部署策略（Nginx反向代理、SSL证书、负载均衡）；监控与日志管理（健康检查、错误追踪、性能监控）；运维最佳实践（备份、安全、故障恢复）以及CI/CD流水线与自动化部署建议。文档严格基于仓库现有配置与实现进行说明，避免臆测。

## 项目结构
GEO采用前后端分离架构，后端为FastAPI应用，前端为Next.js应用，数据库使用PostgreSQL，缓存使用Redis。通过Docker Compose进行本地开发与演示环境编排，支持数据库、Redis、后端API与前端开发服务器的统一启动与依赖管理。

```mermaid
graph TB
subgraph "容器编排"
DC["docker-compose.yml"]
end
subgraph "后端服务"
BE["backend/Dockerfile"]
API["backend/app/main.py"]
CFG["backend/app/config.py"]
DB["backend/app/database.py"]
SCH["backend/app/workers/scheduler.py"]
ALEMBIC["backend/alembic/*"]
end
subgraph "前端服务"
FE["frontend/Dockerfile"]
PKG["frontend/package.json"]
end
subgraph "基础设施"
PG["PostgreSQL:5432"]
RD["Redis:6379"]
end
DC --> BE
DC --> FE
DC --> PG
DC --> RD
BE --> API
API --> DB
API --> SCH
DB --> PG
SCH --> RD
FE --> API
```

**图表来源**
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
- [backend/Dockerfile:1-41](file://backend/Dockerfile#L1-L41)
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)
- [backend/app/main.py:1-100](file://backend/app/main.py#L1-L100)
- [backend/app/config.py:1-46](file://backend/app/config.py#L1-L46)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [backend/app/workers/scheduler.py:1-189](file://backend/app/workers/scheduler.py#L1-L189)
- [backend/alembic.ini:1-150](file://backend/alembic.ini#L1-L150)
- [backend/alembic/env.py:1-89](file://backend/alembic/env.py#L1-L89)

**章节来源**
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
- [backend/Dockerfile:1-41](file://backend/Dockerfile#L1-L41)
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)

## 核心组件
- 后端API（FastAPI）
  - 应用入口与生命周期管理、路由注册、CORS中间件、健康检查端点。
  - 配置加载与数据库连接、Redis连接、定时任务调度器。
- 数据库（PostgreSQL）
  - 异步SQLAlchemy引擎、会话管理、模型定义与索引。
- 缓存（Redis）
  - 用于任务调度与状态存储等场景。
- 前端（Next.js）
  - 开发模式运行，与后端API交互。
- 迁移与版本控制（Alembic）
  - 异步迁移环境、配置文件与日志级别。

**章节来源**
- [backend/app/main.py:1-100](file://backend/app/main.py#L1-L100)
- [backend/app/config.py:1-46](file://backend/app/config.py#L1-L46)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [backend/app/workers/scheduler.py:1-189](file://backend/app/workers/scheduler.py#L1-L189)
- [backend/alembic.ini:1-150](file://backend/alembic.ini#L1-L150)
- [backend/alembic/env.py:1-89](file://backend/alembic/env.py#L1-L89)

## 架构总览
下图展示生产环境典型拓扑：Nginx作为反向代理与SSL终止，后端API以多实例运行，数据库与Redis作为共享资源，前端静态资源可由Nginx或CDN提供。

```mermaid
graph TB
subgraph "外部访问"
U["用户浏览器"]
end
subgraph "边缘层"
NGINX["Nginx 反向代理<br/>SSL/TLS 终止"]
end
subgraph "应用层"
LB["负载均衡器/反向代理"]
subgraph "后端实例"
API1["API 实例 1"]
API2["API 实例 2"]
API3["API 实例 N"]
end
end
end
subgraph "数据与缓存"
DB["PostgreSQL 主库/只读副本"]
RDS["Redis 集群/哨兵"]
end
U --> NGINX
NGINX --> LB
LB --> API1
LB --> API2
LB --> API3
API1 --> DB
API2 --> DB
API3 --> DB
API1 --> RDS
API2 --> RDS
API3 --> RDS
```

**图表来源**
- [docker-compose.yml:36-66](file://docker-compose.yml#L36-L66)
- [backend/app/main.py:97-100](file://backend/app/main.py#L97-L100)

## 详细组件分析

### 后端API（FastAPI）与容器化
- 容器镜像构建要点
  - 基于Python slim镜像，安装Playwright所需系统依赖，并预装依赖后复制应用代码。
  - 暴露8000端口，使用Uvicorn启动应用。
- 应用特性
  - 生命周期钩子在启动时初始化调度器，在关闭时优雅停机。
  - 注册认证、查询、引用数据、报告等路由前缀。
  - 提供/CORS允许来自前端开发地址的跨域请求。
  - 提供健康检查端点。
- 配置与连接
  - 通过环境变量加载数据库URL、Redis URL、JWT密钥、平台API密钥等。
  - 数据库连接为异步引擎，使用会话工厂管理事务。
- 定时任务
  - 使用APScheduler异步调度器，每小时检查到期查询并调用引用引擎执行。

```mermaid
sequenceDiagram
participant C as "容器"
participant U as "Uvicorn"
participant A as "FastAPI 应用"
participant S as "调度器"
participant D as "数据库"
participant R as "Redis"
C->>U : "启动进程"
U->>A : "加载应用与生命周期"
A->>S : "启动调度器"
A->>D : "建立异步连接"
A->>R : "建立连接"
A-->>C : "健康检查端点可用"
S->>D : "周期性查询待执行任务"
S->>A : "触发执行逻辑"
```

**图表来源**
- [backend/Dockerfile:1-41](file://backend/Dockerfile#L1-L41)
- [backend/app/main.py:33-45](file://backend/app/main.py#L33-L45)
- [backend/app/config.py:12-14](file://backend/app/config.py#L12-L14)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [backend/app/workers/scheduler.py:33-51](file://backend/app/workers/scheduler.py#L33-L51)

**章节来源**
- [backend/Dockerfile:1-41](file://backend/Dockerfile#L1-L41)
- [backend/app/main.py:1-100](file://backend/app/main.py#L1-L100)
- [backend/app/config.py:1-46](file://backend/app/config.py#L1-L46)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [backend/app/workers/scheduler.py:1-189](file://backend/app/workers/scheduler.py#L1-L189)

### 前端（Next.js）与容器化
- 容器镜像构建要点
  - 基于Node Alpine镜像，安装依赖后复制应用代码。
  - 暴露3000端口，开发模式启动。
- 与后端交互
  - 默认CORS允许来自前端开发地址的请求，生产环境需根据域名调整。

**章节来源**
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)
- [frontend/package.json:1-45](file://frontend/package.json#L1-L45)
- [backend/app/main.py:53-63](file://backend/app/main.py#L53-L63)

### 数据库与迁移（PostgreSQL + Alembic）
- 连接与会话
  - 使用异步引擎与会话工厂，提供依赖注入式数据库会话。
- 迁移
  - 配置文件指定数据库URL，环境脚本支持离线与在线迁移，异步连接迁移上下文。
- 模型与索引
  - 查询模型包含用户外键、关键词、平台列表、频率、状态、时间戳等字段，并建立复合索引以优化查询。

```mermaid
erDiagram
USERS {
uuid id PK
string email UK
string name
string plan
int max_queries
boolean is_active
timestamp created_at
timestamp updated_at
}
QUERIES {
uuid id PK
uuid user_id FK
string keyword
string target_brand
jsonb brand_aliases
jsonb platforms
string frequency
string status
timestamp last_queried_at
timestamp next_query_at
timestamp created_at
timestamp updated_at
}
CITATION_RECORDS {
uuid id PK
uuid query_id FK
jsonb raw_data
timestamp created_at
}
QUERY_TASKS {
uuid id PK
uuid query_id FK
string platform
string status
timestamp scheduled_at
timestamp executed_at
}
USERS ||--o{ QUERIES : "拥有"
QUERIES ||--o{ CITATION_RECORDS : "生成"
QUERIES ||--o{ QUERY_TASKS : "拆分任务"
```

**图表来源**
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [backend/alembic.ini:86-89](file://backend/alembic.ini#L86-L89)
- [backend/alembic/env.py:1-89](file://backend/alembic/env.py#L1-L89)

**章节来源**
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/alembic.ini:1-150](file://backend/alembic.ini#L1-L150)
- [backend/alembic/env.py:1-89](file://backend/alembic/env.py#L1-L89)

### 认证与安全（JWT）
- 接口
  - 提供注册、登录、获取当前用户信息的接口。
- 安全要点
  - JWT密钥默认值仅用于开发，生产必须替换。
  - CORS在开发环境允许前端地址，生产需限定来源。

**章节来源**
- [backend/app/api/auth.py:1-115](file://backend/app/api/auth.py#L1-L115)
- [backend/app/config.py:14](file://backend/app/config.py#L14)

### 编排与健康检查（Docker Compose）
- 服务编排
  - db、redis、backend、frontend四类服务，分别映射端口、挂载卷、加载环境文件。
- 健康检查
  - PostgreSQL与Redis提供健康检查探针，后端API提供/CORS与健康检查端点。
- 依赖顺序
  - 后端等待数据库与Redis健康后再启动，前端依赖后端。

**章节来源**
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
- [backend/app/main.py:97-100](file://backend/app/main.py#L97-L100)

## Docker容器化部署

### 镜像构建配置
GEO项目采用多阶段容器化部署，后端和前端分别构建独立镜像：

**后端镜像构建流程**
- 基础镜像：python:3.11-slim
- 系统依赖：安装Playwright运行所需的系统库
- 依赖安装：pip安装requirements.txt中的所有依赖
- 浏览器安装：预装Chromium浏览器驱动
- 应用部署：复制源码并暴露8000端口

**前端镜像构建流程**
- 基础镜像：node:20-alpine
- 依赖安装：使用npm ci安装生产依赖
- 应用部署：复制源码并暴露3000端口

**章节来源**
- [backend/Dockerfile:1-41](file://backend/Dockerfile#L1-L41)
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)
- [backend/requirements.txt:1-42](file://backend/requirements.txt#L1-L42)

### 服务编排配置
Docker Compose定义了完整的微服务架构：

**数据库服务（db）**
- 镜像：postgres:15-alpine
- 端口映射：5432:5432
- 健康检查：使用pg_isready检测数据库可用性
- 数据持久化：挂载postgres_data卷

**缓存服务（redis）**
- 镜像：redis:7-alpine
- 端口映射：6379:6379
- 健康检查：使用redis-cli ping检测
- 数据持久化：挂载redis_data卷

**后端服务（backend）**
- 构建：使用./backend目录作为构建上下文
- 端口映射：8000:8000
- 环境配置：加载.env文件
- 依赖关系：等待db和redis健康检查通过
- 命令：uvicorn启动FastAPI应用

**前端服务（frontend）**
- 构建：使用./frontend目录作为构建上下文
- 端口映射：3000:3000
- 环境配置：加载.env文件
- 依赖关系：依赖backend服务
- 命令：npm run dev启动开发服务器

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

### 环境配置管理
项目使用Pydantic Settings进行环境变量管理，支持不同环境的配置分离：

**核心配置项**
- 数据库连接：DATABASE_URL（默认指向db容器）
- Redis连接：REDIS_URL（默认指向redis容器）
- JWT配置：JWT_SECRET、JWT_EXPIRE_HOURS
- LLM提供商：支持OpenAI、DeepSeek、通义千问等
- CORS配置：CORS_ORIGINS允许跨域请求的来源列表

**章节来源**
- [backend/app/config.py:1-46](file://backend/app/config.py#L1-L46)

## 生产环境部署策略

### Nginx反向代理配置
生产环境推荐使用Nginx作为反向代理和SSL终止：

**基础反向代理配置**
```
upstream backend {
    server backend:8000;
}

server {
    listen 80;
    server_name geo.example.com;
    
    location / {
        proxy_pass http://backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

**SSL证书配置**
- 使用Let's Encrypt自动签发免费SSL证书
- 配置HTTP到HTTPS重定向
- 启用现代TLS协议和加密套件

**负载均衡配置**
- 使用Nginx内置负载均衡器
- 配置健康检查和故障转移
- 支持多实例后端部署

### 容器编排与扩展
生产环境建议使用Docker Swarm或Kubernetes进行容器编排：

**服务扩展**
- 后端API：根据负载情况动态扩展实例数量
- 数据库：配置主从复制和只读副本
- 缓存：使用Redis集群提高可用性

**存储管理**
- 使用持久化存储卷确保数据安全
- 配置定期备份策略
- 实施数据同步和灾备方案

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

## 监控与日志管理

### 健康检查与监控
项目已内置基本的健康检查功能，生产环境需要增强监控能力：

**应用级监控**
- 健康检查端点：/health
- 性能指标：响应时间、错误率、吞吐量
- 资源使用：CPU、内存、磁盘空间

**基础设施监控**
- 数据库连接池监控
- Redis连接状态监控
- 文件系统空间监控

**日志管理方案**
- 结构化日志输出到标准输出
- 使用集中式日志收集系统（如ELK Stack）
- 日志轮转和保留策略

**章节来源**
- [backend/app/main.py:97-100](file://backend/app/main.py#L97-L100)
- [backend/app/middleware/logging_middleware.py:1-24](file://backend/app/middleware/logging_middleware.py#L1-L24)

### 错误追踪与告警
**错误追踪配置**
- 使用结构化日志记录异常信息
- 集成错误追踪服务（如Sentry）
- 设置错误阈值和告警规则

**性能监控**
- 数据库查询性能监控
- API响应时间监控
- 缓存命中率监控

**章节来源**
- [backend/app/middleware/rate_limit.py:1-83](file://backend/app/middleware/rate_limit.py#L1-L83)

## 运维最佳实践

### 备份策略
**数据库备份**
- 定时全量备份：每周日凌晨2点执行
- 增量备份：每小时执行
- 多地备份：本地和云端同时保存

**配置备份**
- 环境变量文件备份
- Docker Compose配置备份
- SSL证书备份

**恢复流程**
- 制定详细的灾难恢复计划
- 定期进行恢复演练
- 建立快速恢复机制

### 安全配置
**网络安全**
- 最小权限原则
- 网络隔离和防火墙配置
- 入站/出站流量控制

**应用安全**
- 定期更新依赖包
- 密钥轮换策略
- 安全审计日志

**数据安全**
- 敏感数据加密存储
- 数据传输加密
- 访问权限控制

### 故障恢复
**故障分类与响应**
- 一级故障：系统完全不可用，立即启动应急预案
- 二级故障：部分功能受影响，优先保证核心业务
- 三级故障：性能下降但可正常运行，监控观察

**恢复流程**
- 快速诊断和定位问题
- 实施临时修复措施
- 执行永久性修复
- 验证系统恢复正常

**章节来源**
- [backend/app/config.py:14](file://backend/app/config.py#L14)
- [backend/app/middleware/rate_limit.py:34-69](file://backend/app/middleware/rate_limit.py#L34-L69)

## CI/CD流水线配置

### 自动化部署流程
**开发到生产的完整流程**
1. 代码提交触发CI流水线
2. 自动化测试（单元测试、集成测试）
3. 代码质量检查
4. 构建Docker镜像
5. 推送镜像到镜像仓库
6. 自动部署到测试环境
7. 手动审批进入生产环境
8. 部署到生产环境并监控

**流水线阶段配置**
- 代码检出和分支管理
- 依赖安装和缓存优化
- 测试执行和覆盖率报告
- 安全扫描和漏洞检测
- 镜像构建和标签管理
- 多环境部署策略

**回滚机制**
- 支持一键回滚到上一个稳定版本
- 自动化回滚测试
- 回滚通知和审计

**章节来源**
- [backend/requirements.txt:35-42](file://backend/requirements.txt#L35-L42)

### 部署检查清单
**生产部署前检查**
- 所有测试通过
- 配置文件验证
- 环境变量检查
- 数据库迁移验证
- 服务健康检查

**部署后验证**
- 健康检查端点验证
- 核心功能测试
- 性能基准测试
- 监控告警检查

## 依赖分析
- 后端依赖
  - Web框架、数据库、配置校验、认证加密、缓存与调度、浏览器自动化、HTTP客户端、测试工具等。
- 前端依赖
  - Next.js、React、UI组件库、图表库、类型与样式工具等。
- 运行时依赖
  - Playwright Chromium浏览器、系统库满足其运行需求。

```mermaid
graph LR
subgraph "后端"
REQ["requirements.txt"]
PY["Python 3.11"]
PLT["Playwright"]
end
subgraph "前端"
PKGJSON["package.json"]
NODE["Node 20"]
end
REQ --> PY
REQ --> PLT
PKGJSON --> NODE
```

**图表来源**
- [backend/requirements.txt:1-42](file://backend/requirements.txt#L1-L42)
- [frontend/package.json:1-45](file://frontend/package.json#L1-L45)

**章节来源**
- [backend/requirements.txt:1-42](file://backend/requirements.txt#L1-L42)
- [frontend/package.json:1-45](file://frontend/package.json#L1-L45)

## 性能考虑
- 数据库
  - 查询模型已建立多列索引，建议结合慢查询日志与执行计划持续优化。
- 缓存
  - Redis用于任务调度与临时状态，建议在高并发场景下启用持久化与主从复制。
- API
  - 使用异步数据库连接与事件循环，减少阻塞；对高频接口开启限流与熔断。
- 前端
  - 生产构建与静态资源缓存策略，配合CDN提升加载速度。
- 容器
  - 后端与前端镜像体积较小，建议启用只读根文件系统与最小权限运行。

## 故障排查指南
- 健康检查
  - 后端/CORS与健康检查端点可用于快速判断服务可用性。
- 日志
  - 后端使用标准库日志，Alembic配置了日志级别；建议在生产中接入集中式日志收集。
- 数据库迁移
  - 使用异步迁移环境，确保数据库URL正确；离线/在线迁移均可通过配置切换。
- 认证问题
  - 生产需替换JWT密钥；CORS来源需按域名精确配置。
- 单元测试
  - 认证模块测试覆盖注册、登录与当前用户接口，可作为回归测试基线。

**章节来源**
- [backend/app/main.py:97-100](file://backend/app/main.py#L97-L100)
- [backend/alembic.ini:115-150](file://backend/alembic.ini#L115-L150)
- [backend/alembic/env.py:64-89](file://backend/alembic/env.py#L64-L89)
- [tests/test_auth.py:1-104](file://tests/test_auth.py#L1-L104)

## 结论
本部署与运维文档基于仓库现有配置，给出了从容器化到生产部署的实施路径与最佳实践建议。建议在生产环境中补充Nginx反向代理与SSL、集中化日志与监控、完善的备份与灾难恢复策略，并通过CI/CD实现自动化部署与回滚。文档涵盖了Docker容器化部署、生产环境策略、监控日志管理、运维最佳实践和CI/CD流水线等关键内容，为GEO项目的稳定运行提供了全面的技术保障。

## 附录

### A. Docker容器化部署流程（开发/演示）
- 准备工作
  - 确保已安装Docker与Docker Compose。
- 启动服务
  - 在仓库根目录执行编排命令，等待所有服务进入健康状态。
- 访问应用
  - 前端：http://localhost:3000
  - 后端：http://localhost:8000
  - 数据库：localhost:5432
  - Redis：localhost:6379

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

### B. 生产环境部署策略
- 反向代理与SSL
  - 使用Nginx作为反向代理，开启HTTPS并配置证书自动续期。
- 负载均衡
  - 将后端API以多实例部署并通过LB分发流量，确保健康检查与自动扩缩容。
- 环境隔离
  - 区分开发、测试、预发布与生产环境，严格管理环境变量与密钥。

### C. 监控与日志管理
- 健康检查
  - 利用/CORS与健康检查端点，结合探针实现自动发现与告警。
- 错误追踪
  - 在应用中集成结构化日志，输出到标准输出，由平台收集至集中式系统。
- 性能监控
  - 关注数据库慢查询、Redis命中率、API响应时间与错误率。

### D. 运维最佳实践
- 备份策略
  - 数据库与Redis定期快照与归档，验证恢复流程。
- 安全配置
  - 最小权限原则、密钥轮换、网络隔离、入站/出站策略。
- 故障恢复
  - 制定回滚预案与演练计划，确保快速恢复。

### E. CI/CD流水线与自动化部署
- 建议阶段
  - 代码提交触发测试（含认证接口测试），通过后构建镜像并推送制品库，随后部署到目标环境。
- 回滚机制
  - 支持一键回滚至上一个稳定版本。
- 配置管理
  - 环境变量与密钥通过安全渠道注入，避免硬编码。