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

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

目录

  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与前端开发服务器的统一启动与依赖管理。

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健康后再启动，前端依赖后端。

章节来源

依赖分析

  • 后端依赖
    • 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实现自动化部署与回滚。

附录

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

  • 准备工作
    • 确保已安装Docker与Docker Compose。
  • 启动服务
    • 在仓库根目录执行编排命令，等待所有服务进入健康状态。
  • 访问应用

章节来源

B. 生产环境部署策略

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

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

C. 监控与日志管理

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

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

D. 运维最佳实践

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

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

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

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

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