16 KiB

Raw Blame History

运维最佳实践

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

简介

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

项目结构

GEO采用前后端分离的容器化架构：

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

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

图表来源

章节来源

核心组件

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

章节来源

架构总览

下图展示容器化部署下的服务交互与数据流：

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响应

图表来源

详细组件分析

数据库与迁移（PostgreSQL + Alembic）

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

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

图表来源

章节来源

定时任务调度（APScheduler）

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

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

图表来源

backend/app/workers/scheduler.py:30-90

章节来源

backend/app/workers/scheduler.py:1-95

健康检查与容器编排

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

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:1-71

配置与环境变量

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

章节来源

backend/app/config.py:1-17

前后端镜像构建

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

章节来源

依赖分析

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

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/*"]

图表来源

章节来源

性能考虑

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

故障排查指南

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

章节来源

结论

本指南基于仓库现有配置与代码，总结了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延迟、错误率、任务积压。

16 KiB Raw Blame History Unescape Escape

运维最佳实践

目录

简介

项目结构

核心组件

架构总览

详细组件分析

数据库与迁移（PostgreSQL + Alembic）

定时任务调度（APScheduler）

健康检查与容器编排

配置与环境变量

前后端镜像构建

依赖分析

性能考虑

故障排查指南

结论

附录

日常运维任务清单

安全运维实践

故障恢复流程

容量规划与扩容策略

运维自动化与CI/CD

运维团队职责与应急响应

成本优化与监控

16 KiB

Raw Blame History