# 运维最佳实践

<cite>
**本文档引用的文件**
- [docker-compose.yml](file://docker-compose.yml)
- [backend/Dockerfile](file://backend/Dockerfile)
- [frontend/Dockerfile](file://frontend/Dockerfile)
- [backend/requirements.txt](file://backend/requirements.txt)
- [frontend/package.json](file://frontend/package.json)
- [backend/app/config.py](file://backend/app/config.py)
- [backend/app/main.py](file://backend/app/main.py)
- [backend/app/database.py](file://backend/app/database.py)
- [backend/alembic.ini](file://backend/alembic.ini)
- [backend/alembic/env.py](file://backend/alembic/env.py)
- [backend/app/workers/scheduler.py](file://backend/app/workers/scheduler.py)
</cite>

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

## 简介
本指南面向GEO平台的运维团队，围绕日常运维任务、安全运维、故障恢复、容量规划与扩容、运维自动化与CI/CD、团队职责与应急响应、以及成本优化与监控等方面，提供可操作的最佳实践。文档基于仓库现有配置与代码进行梳理，并结合容器化部署与异步数据库访问等技术特性，给出落地建议。

## 项目结构
GEO采用前后端分离的容器化架构：
- 前端服务：Next.js应用，开发模式下通过NPM脚本启动，容器暴露3000端口。
- 后端服务：FastAPI应用，使用Uvicorn运行，容器暴露8000端口。
- 数据库：PostgreSQL 15，持久化卷挂载，健康检查通过pg_isready。
- 缓存：Redis 7，持久化卷挂载，健康检查通过redis-cli ping。
- 配置：后端通过Pydantic设置从.env文件加载；数据库迁移使用Alembic。

```mermaid
graph TB
subgraph "前端"
FE_Docker["前端Dockerfile<br/>暴露3000端口"]
FE_NPM["package.json<br/>dev/build/start/lint"]
end
subgraph "后端"
BE_Docker["后端Dockerfile<br/>暴露8000端口"]
BE_Main["app/main.py<br/>FastAPI应用与路由注册"]
BE_Config["app/config.py<br/>.env加载与默认配置"]
BE_DB["app/database.py<br/>异步引擎与会话工厂"]
BE_Sched["app/workers/scheduler.py<br/>APScheduler定时任务"]
BE_Alembic["alembic.ini / env.py<br/>数据库迁移配置"]
end
subgraph "基础设施"
DB["PostgreSQL 15<br/>健康检查: pg_isready"]
REDIS["Redis 7<br/>健康检查: redis-cli ping"]
end
FE_Docker --> |"3000"| BE_Main
BE_Docker --> |"8000"| BE_Main
BE_Main --> BE_DB
BE_Main --> REDIS
BE_DB --> DB
BE_Sched --> BE_DB
BE_Sched --> REDIS
```

图表来源
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)
- [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/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)
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)
- [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/alembic.ini:1-150](file://backend/alembic.ini#L1-L150)
- [backend/alembic/env.py:1-89](file://backend/alembic/env.py#L1-L89)

## 核心组件
- 应用入口与生命周期：后端通过FastAPI应用注册路由与CORS中间件，并在应用生命周期内启动定时任务调度器。
- 数据库连接：使用SQLAlchemy异步引擎与会话工厂，支持异步事务与连接池配置。
- 配置管理：通过Pydantic设置从.env文件读取配置，包含数据库URL、Redis URL、JWT密钥、浏览器驱动路径等。
- 定时任务：基于APScheduler的异步调度器，按小时检查并执行到期的查询任务。
- 数据库迁移：Alembic配置与环境脚本，支持离线与在线迁移，连接字符串来自配置。

章节来源
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
- [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)

## 架构总览
下图展示容器化部署下的服务交互与数据流：

```mermaid
sequenceDiagram
participant Dev as "开发者/CI"
participant Compose as "docker-compose"
participant FE as "前端容器(3000)"
participant BE as "后端容器(8000)"
participant DB as "PostgreSQL(5432)"
participant R as "Redis(6379)"
Dev->>Compose : 启动/停止/重建
Compose->>BE : 依赖DB/Redis健康就绪
Compose->>FE : 依赖后端可用
FE->>BE : HTTP请求 /api/v1/*
BE->>DB : 异步ORM读写
BE->>R : 缓存/任务状态
BE-->>FE : JSON响应
```

图表来源
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)

## 详细组件分析

### 数据库与迁移（PostgreSQL + Alembic）
- 连接与会话：异步引擎与会话工厂确保高并发下的连接复用与事务一致性。
- 迁移策略：Alembic支持离线与在线迁移，连接字符串来自配置；日志级别可调以降低噪音。
- 建议：
  - 在生产环境固定DATABASE_URL，避免硬编码。
  - 迁移前先做备份，使用在线迁移时控制窗口时间。
  - 将迁移脚本纳入版本控制并审查变更。

```mermaid
flowchart TD
Start(["开始"]) --> CheckCfg["读取DATABASE_URL配置"]
CheckCfg --> Mode{"迁移模式"}
Mode --> |离线| Offline["生成/执行离线迁移"]
Mode --> |在线| Online["建立异步连接并执行迁移"]
Offline --> Done(["结束"])
Online --> Done
```

图表来源
- [backend/alembic.ini:86-90](file://backend/alembic.ini#L86-L90)
- [backend/alembic/env.py:33-88](file://backend/alembic/env.py#L33-L88)
- [backend/app/config.py:7-8](file://backend/app/config.py#L7-L8)

章节来源
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [backend/alembic.ini:1-150](file://backend/alembic.ini#L1-L150)
- [backend/alembic/env.py:1-89](file://backend/alembic/env.py#L1-L89)
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)

### 定时任务调度（APScheduler）
- 触发周期：每小时检查一次到期查询。
- 执行逻辑：查询状态为active且next_query_at小于等于当前UTC时间的任务，逐条交由引用引擎执行。
- 错误处理：单任务异常不影响整体调度，日志记录错误并继续处理其他任务。
- 建议：
  - 将调度器纳入应用生命周期，在应用启动时启动，退出时优雅关闭。
  - 对高频任务增加幂等性校验与去重机制。
  - 监控任务执行耗时与积压情况。

```mermaid
flowchart TD
S(["启动调度器"]) --> AddJob["添加每小时检查任务"]
AddJob --> Loop{"每小时触发"}
Loop --> Query["查询到期active任务"]
Query --> Exec["逐条执行引用引擎"]
Exec --> Log["记录结果/异常"]
Log --> Loop
```

图表来源
- [backend/app/workers/scheduler.py:30-90](file://backend/app/workers/scheduler.py#L30-L90)

章节来源
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)

### 健康检查与容器编排
- 数据库健康检查：使用pg_isready，间隔与重试次数可调。
- Redis健康检查：使用redis-cli ping。
- 服务依赖：后端等待数据库与缓存健康后再启动，前端等待后端可用。
- 建议：
  - 生产环境调整健康检查参数，避免误判。
  - 使用独立的健康检查端点（如/health）对外暴露，便于外部监控系统探测。

```mermaid
sequenceDiagram
participant DC as "docker-compose"
participant DB as "PostgreSQL"
participant R as "Redis"
participant BE as "后端"
DC->>DB : 健康检查(pg_isready)
DB-->>DC : OK
DC->>R : 健康检查(redis-cli ping)
R-->>DC : PONG
DC->>BE : 启动应用(等待DB/Redis健康)
```

图表来源
- [docker-compose.yml:16-34](file://docker-compose.yml#L16-L34)
- [docker-compose.yml:46-50](file://docker-compose.yml#L46-L50)

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

### 配置与环境变量
- 关键配置项：数据库URL、Redis URL、JWT密钥、过期时间、Playwright浏览器路径、第三方平台API Key等。
- 加载方式：通过Pydantic设置从.env文件加载，支持类型校验与默认值。
- 建议：
  - 生产环境使用只读权限的数据库账号与专用密钥。
  - 将敏感信息放入密钥管理服务或编排平台的密文存储。
  - 分环境(.env.dev/.env.prod)隔离配置，避免混用。

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

### 前后端镜像构建
- 后端镜像：基于python:3.11-slim，安装Playwright所需系统依赖，预装Python依赖并安装浏览器驱动。
- 前端镜像：基于node:20-alpine，使用npm ci安装依赖。
- 建议：
  - 使用多阶段构建减少镜像体积。
  - 固定基础镜像版本，启用镜像扫描与漏洞告警。
  - 在CI中缓存依赖层以提升构建速度。

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

## 依赖分析
- 组件耦合：
  - 后端主程序依赖数据库模块与调度器模块。
  - 调度器依赖数据库会话工厂与引用引擎。
  - Alembic依赖配置与模型元数据。
- 外部依赖：
  - 数据库：PostgreSQL（异步驱动）。
  - 缓存：Redis。
  - 浏览器自动化：Playwright（chromium）。
- 可能的改进：
  - 将调度器抽象为可注入的服务，便于测试与替换。
  - 将数据库连接参数与迁移配置进一步解耦。

```mermaid
graph LR
Main["app/main.py"] --> DBMod["app/database.py"]
Main --> Sched["app/workers/scheduler.py"]
Sched --> DBMod
Alembic["alembic/env.py"] --> Cfg["app/config.py"]
Alembic --> Models["app/models/*"]
```

图表来源
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [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/env.py:1-89](file://backend/alembic/env.py#L1-L89)
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)

章节来源
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [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/env.py:1-89](file://backend/alembic/env.py#L1-L89)
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)

## 性能考虑
- 数据库性能：
  - 使用异步引擎与连接池，合理设置超时与空闲回收。
  - 为热点查询建立索引，避免全表扫描。
  - 控制事务粒度，减少长事务锁竞争。
- 缓存策略：
  - 利用Redis缓存热点数据与任务状态，降低数据库压力。
  - 设置合理的TTL与淘汰策略，避免内存膨胀。
- 定时任务：
  - 控制任务频率与执行时长，避免高峰期抖动。
  - 对任务执行结果进行统计与告警。
- 前后端镜像：
  - 减少镜像层数与体积，缩短拉取与启动时间。
  - 使用CDN与静态资源优化。

## 故障排查指南
- 健康检查失败
  - 检查数据库与Redis健康检查命令是否可用。
  - 查看容器日志，确认端口映射与网络连通。
- 数据库连接异常
  - 核对DATABASE_URL格式与凭据。
  - 检查PostgreSQL日志与连接数上限。
- 定时任务未执行
  - 确认调度器已启动且未报错。
  - 检查任务状态与next_query_at字段。
- 前端无法访问后端
  - 核对CORS配置与路由前缀。
  - 检查后端/health端点返回状态。

章节来源
- [docker-compose.yml:16-34](file://docker-compose.yml#L16-L34)
- [backend/app/main.py:30-36](file://backend/app/main.py#L30-L36)
- [backend/app/workers/scheduler.py:30-90](file://backend/app/workers/scheduler.py#L30-L90)

## 结论
本指南基于仓库现有配置与代码，总结了GEO平台的运维关注点与最佳实践建议。建议在生产环境中进一步完善配置管理、安全加固、监控告警与自动化流程，以保障系统的稳定性与可维护性。

## 附录

### 日常运维任务清单
- 定期备份策略
  - 数据库：使用pg_dump/pg_restore进行增量/全量备份，保留至少7天滚动备份。
  - 持久化卷：定期快照或导出postgres_data与redis_data。
- 数据库维护
  - 清理历史日志与临时表，重建索引，更新统计信息。
  - 监控慢查询与锁等待，定位瓶颈。
- 系统更新流程
  - 先在测试环境验证镜像与配置变更，再灰度到生产。
  - 使用滚动更新与健康检查，确保零停机。

### 安全运维实践
- 漏洞扫描
  - 镜像扫描：在CI中集成镜像漏洞扫描工具。
  - 依赖扫描：定期扫描Python与Node依赖的安全问题。
- 安全补丁管理
  - 基础镜像与依赖库定期升级，优先修复高危漏洞。
- 访问审计
  - 开启数据库与应用日志审计，记录敏感操作。
  - 限制数据库连接权限，最小化管理员账号使用。

### 故障恢复流程
- 灾难恢复计划
  - 明确RTO/RPO目标，准备多活或多副本方案。
- 数据恢复
  - 从最近备份恢复，核对时间点一致性。
- 系统回滚策略
  - 采用蓝绿/金丝雀发布，失败自动回滚。
  - 回滚前做好配置与数据备份。

### 容量规划与扩容策略
- 水平扩展
  - 前后端服务均可横向扩展，注意会话与共享状态的处理。
- 垂直扩展
  - 根据CPU/内存与I/O使用率评估，逐步提升实例规格。
- 决策因素
  - QPS、响应时间、错误率、资源利用率阈值。

### 运维自动化与CI/CD
- 自动化脚本
  - 备份脚本：封装pg_dump与卷快照命令。
  - 部署脚本：封装docker-compose拉起/回滚流程。
- CI/CD流水线
  - 触发条件：push到主分支或打标签。
  - 步骤：代码检查、单元测试、镜像构建、安全扫描、部署、健康检查。
  - 告警：失败通知与自动回滚。

### 运维团队职责与应急响应
- 职责分工
  - 基础设施：负责容器编排、网络与存储。
  - 应用运维：负责后端服务、数据库与缓存。
  - 安全与合规：负责漏洞扫描、密钥与审计。
- 应急响应
  - 建立值班制度与应急预案，明确升级路径。
  - 使用统一告警平台，确保信息透明与快速处置。

### 成本优化与监控
- 成本优化
  - 合理选择实例规格与存储类型，避免过度配置。
  - 使用预留实例或批量折扣，优化闲置资源。
- 资源利用率监控
  - CPU/内存/磁盘/网络IO与数据库连接数。
  - 业务指标：QPS、P95/P99延迟、错误率、任务积压。