fischer
/
geo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
geo/.qoder/repowiki/zh/content/部署与运维/部署与运维.md

675 lines
22 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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