375 lines
16 KiB
Markdown
375 lines
16 KiB
Markdown
# 运维最佳实践
|
||
|
||
<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延迟、错误率、任务积压。 |