22 KiB

Raw Permalink Blame History

部署与运维

**本文引用的文件** - [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)

更新摘要

所做更改

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

简介

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

项目结构

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

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

图表来源

章节来源

核心组件

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

章节来源

架构总览

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

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异步调度器，每小时检查到期查询并调用引用引擎执行。

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 : "触发执行逻辑"

图表来源

章节来源

前端（Next.js）与容器化

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

章节来源

数据库与迁移（PostgreSQL + Alembic）

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

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 : "拆分任务"

图表来源

章节来源

认证与安全（JWT）

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

章节来源

编排与健康检查（Docker Compose）

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

章节来源

Docker容器化部署

镜像构建配置

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

后端镜像构建流程

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

前端镜像构建流程

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

章节来源

服务编排配置

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

环境配置管理

项目使用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

生产环境部署策略

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集群提高可用性

存储管理

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

章节来源

监控与日志管理

健康检查与监控

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

应用级监控

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

基础设施监控

数据库连接池监控
Redis连接状态监控
文件系统空间监控

日志管理方案

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

章节来源

错误追踪与告警

错误追踪配置

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

性能监控

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

章节来源

backend/app/middleware/rate_limit.py:1-83

运维最佳实践

备份策略

数据库备份

定时全量备份：每周日凌晨2点执行
增量备份：每小时执行
多地备份：本地和云端同时保存

配置备份

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

恢复流程

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

安全配置

网络安全

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

应用安全

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

数据安全

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

故障恢复

故障分类与响应

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

恢复流程

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

章节来源

CI/CD流水线配置

自动化部署流程

开发到生产的完整流程

代码提交触发CI流水线
自动化测试（单元测试、集成测试）
代码质量检查
构建Docker镜像
推送镜像到镜像仓库
自动部署到测试环境
手动审批进入生产环境
部署到生产环境并监控

流水线阶段配置

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

回滚机制

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

章节来源

backend/requirements.txt:35-42

部署检查清单

生产部署前检查

所有测试通过
配置文件验证
环境变量检查
数据库迁移验证
服务健康检查

部署后验证

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

依赖分析

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

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

图表来源

章节来源

性能考虑

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

故障排查指南

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

章节来源

结论

本部署与运维文档基于仓库现有配置，给出了从容器化到生产部署的实施路径与最佳实践建议。建议在生产环境中补充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

B. 生产环境部署策略

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

C. 监控与日志管理

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

D. 运维最佳实践

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

E. CI/CD流水线与自动化部署

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

22 KiB Raw Permalink Blame History Unescape Escape

部署与运维

更新摘要

目录

简介

项目结构

核心组件

架构总览

详细组件分析

后端API（FastAPI）与容器化

前端（Next.js）与容器化

数据库与迁移（PostgreSQL + Alembic）

认证与安全（JWT）

编排与健康检查（Docker Compose）

Docker容器化部署

镜像构建配置

服务编排配置

环境配置管理

生产环境部署策略

Nginx反向代理配置

容器编排与扩展

监控与日志管理

健康检查与监控

错误追踪与告警

运维最佳实践

备份策略

安全配置

故障恢复

CI/CD流水线配置

自动化部署流程

部署检查清单

依赖分析

性能考虑

故障排查指南

结论

附录

A. Docker容器化部署流程（开发/演示）

B. 生产环境部署策略

C. 监控与日志管理

D. 运维最佳实践

E. CI/CD流水线与自动化部署

22 KiB

Raw Permalink Blame History