# 部署与运维

<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)
- [tests/test_auth.py](file://tests/test_auth.py)
</cite>

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

## 简介
本文件面向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-48](file://backend/app/main.py#L1-L48)
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)
- [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-48](file://backend/app/main.py#L1-L48)
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)
- [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
```

（本图为概念性架构示意，不对应具体源码文件）

## 详细组件分析

### 后端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:1-48](file://backend/app/main.py#L1-L48)
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)

章节来源
- [backend/Dockerfile:1-41](file://backend/Dockerfile#L1-L41)
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)

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

章节来源
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)
- [frontend/package.json:1-40](file://frontend/package.json#L1-L40)
- [backend/app/main.py:30-36](file://backend/app/main.py#L30-L36)

### 数据库与迁移（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-43](file://backend/app/api/auth.py#L1-L43)
- [backend/app/config.py:9-9](file://backend/app/config.py#L9-L9)

### 编排与健康检查（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:45-48](file://backend/app/main.py#L45-L48)

## 依赖分析
- 后端依赖
  - 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-35](file://backend/requirements.txt#L1-L35)
- [frontend/package.json:1-40](file://frontend/package.json#L1-L40)

章节来源
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
- [frontend/package.json:1-40](file://frontend/package.json#L1-L40)

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

（本节为通用指导，不直接分析具体文件）

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

章节来源
- [backend/app/main.py:45-48](file://backend/app/main.py#L45-L48)
- [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实现自动化部署与回滚。

## 附录

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

（本节为通用指导，不直接分析具体文件）