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

276 lines
15 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 监控与日志管理
<cite>
**本文引用的文件**
- [backend/app/main.py](file://backend/app/main.py)
- [backend/docker-compose.yml](file://backend/docker-compose.yml)
- [backend/app/config.py](file://backend/app/config.py)
- [backend/app/database.py](file://backend/app/database.py)
- [backend/app/workers/scheduler.py](file://backend/app/workers/scheduler.py)
- [backend/app/workers/citation_engine.py](file://backend/app/workers/citation_engine.py)
- [backend/app/workers/platforms/base.py](file://backend/app/workers/platforms/base.py)
- [backend/app/workers/platforms/kimi.py](file://backend/app/workers/platforms/kimi.py)
- [backend/app/workers/platforms/wenxin.py](file://backend/app/workers/platforms/wenxin.py)
- [backend/requirements.txt](file://backend/requirements.txt)
- [backend/Dockerfile](file://backend/Dockerfile)
- [backend/app/api/deps.py](file://backend/app/api/deps.py)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本方案围绕GEO项目的监控与日志管理，系统性地梳理应用健康检查、服务可用性监控、响应时间监控、错误率统计、日志收集与管理、错误追踪与告警通知、性能指标采集与可视化，以及日志分析与故障诊断的最佳实践。当前仓库中已具备基础的健康检查端点、容器编排与健康检查、日志记录与重试机制，但尚未集成统一的监控与告警体系（如Prometheus/Grafana）。本文在现有能力基础上，提出可落地的扩展建议与实施路径。
## 项目结构
后端采用FastAPI框架，通过APScheduler进行定时任务调度，使用Playwright驱动浏览器访问外部AI平台，结合PostgreSQL与Redis作为数据与缓存存储。Docker Compose负责多服务编排与健康检查。
```mermaid
graph TB
subgraph "后端服务"
API["FastAPI 应用<br/>/health 健康检查"]
SCH["APScheduler 调度器"]
CE["引用检测引擎"]
DB["PostgreSQL 引擎/会话"]
REDIS["Redis 连接"]
end
subgraph "外部平台"
KIMI["Kimi 适配器"]
WENXIN["文心一言适配器"]
end
API --> SCH
SCH --> CE
CE --> KIMI
CE --> WENXIN
CE --> DB
CE --> REDIS
```
图表来源
- [backend/app/main.py:45-47](file://backend/app/main.py#L45-L47)
- [backend/app/workers/scheduler.py:30-40](file://backend/app/workers/scheduler.py#L30-L40)
- [backend/app/workers/citation_engine.py:148-170](file://backend/app/workers/citation_engine.py#L148-L170)
- [backend/app/database.py:6-18](file://backend/app/database.py#L6-L18)
- [backend/app/config.py:7-8](file://backend/app/config.py#L7-L8)
章节来源
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [backend/docker-compose.yml:1-71](file://backend/docker-compose.yml#L1-L71)
- [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)
## 核心组件
- 健康检查端点：提供基础可用性探测，便于反向代理与编排系统判断服务状态。
- 定时任务调度器：基于APScheduler的异步调度器，周期性扫描并执行到期查询任务。
- 引用检测引擎：封装品牌匹配、竞争品牌检测、平台适配器调用与结果持久化。
- 平台适配器：Kimi与文心一言的Playwright驱动实现，包含重试与稳定性处理。
- 数据库与配置：异步SQLAlchemy引擎与环境变量配置，支撑任务状态与结果存储。
- 容器编排与健康检查：Compose对数据库与Redis进行健康检查，后端服务依赖健康状态启动。
章节来源
- [backend/app/main.py:45-47](file://backend/app/main.py#L45-L47)
- [backend/app/workers/scheduler.py:25-95](file://backend/app/workers/scheduler.py#L25-L95)
- [backend/app/workers/citation_engine.py:148-309](file://backend/app/workers/citation_engine.py#L148-L309)
- [backend/app/workers/platforms/kimi.py:11-206](file://backend/app/workers/platforms/kimi.py#L11-L206)
- [backend/app/workers/platforms/wenxin.py:11-205](file://backend/app/workers/platforms/wenxin.py#L11-L205)
- [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/docker-compose.yml:16-34](file://backend/docker-compose.yml#L16-L34)
## 架构总览
下图展示从API到调度器、引擎、平台适配器与数据库的整体交互流程，并标注健康检查与容器编排的关键节点。
```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "FastAPI 应用"
participant SCH as "调度器"
participant CE as "引用检测引擎"
participant KIMI as "Kimi 适配器"
participant WENXIN as "文心一言适配器"
participant DB as "数据库"
Client->>API : GET /health
API-->>Client : {"status" : "ok"}
SCH->>CE : 触发检查并执行查询
CE->>KIMI : query(keyword)
CE->>WENXIN : query(keyword)
CE->>DB : 写入CitationRecord/更新QueryTask
CE-->>SCH : 返回执行结果
```
图表来源
- [backend/app/main.py:45-47](file://backend/app/main.py#L45-L47)
- [backend/app/workers/scheduler.py:51-84](file://backend/app/workers/scheduler.py#L51-L84)
- [backend/app/workers/citation_engine.py:159-234](file://backend/app/workers/citation_engine.py#L159-L234)
- [backend/app/workers/platforms/kimi.py:33-48](file://backend/app/workers/platforms/kimi.py#L33-L48)
- [backend/app/workers/platforms/wenxin.py:33-48](file://backend/app/workers/platforms/wenxin.py#L33-L48)
## 详细组件分析
### 健康检查与服务可用性监控
- 基础健康检查端点：提供轻量级可用性探测，适合反向代理与编排系统快速判断服务状态。
- 容器健康检查：Compose对PostgreSQL与Redis进行健康检查，后端服务依赖这些服务健康后再启动，提升整体可用性保障。
- 建议扩展：
- 在应用内增加更细粒度的依赖检查（数据库连接池、Redis连接、外部平台可用性）。
- 将健康检查结果暴露为指标，接入Prometheus/Grafana进行可视化与告警。
章节来源
- [backend/app/main.py:45-47](file://backend/app/main.py#L45-L47)
- [backend/docker-compose.yml:16-34](file://backend/docker-compose.yml#L16-L34)
### 日志收集与管理策略
- 日志记录范围：调度器、引擎、平台适配器均使用标准日志模块记录信息与错误，覆盖任务执行、平台查询、异常处理等关键环节。
- 日志级别建议：
- INFO：任务开始/结束、平台查询成功、结果写入。
- WARNING：重试警告、超时警告。
- ERROR：平台查询失败、数据库写入失败、异常抛出。
- 结构化日志格式建议：
- 统一字段：timestamp、level、service、module、function、message、trace_id（可选）、span_id（可选）、extra（JSON）。
- 示例字段：service=backend、module=scheduler/engine/platform、function=check_and_execute_queries/execute_query/query。
- 日志轮转与存储：
- 使用logrotate或容器日志驱动自带轮转；生产环境建议将日志输出到stdout/stderr，由容器编排系统集中收集（如Fluent Bit/Fluentd）。
- 存储策略：短期本地、长期归档至对象存储或集中日志平台（如ELK/Graylog/Loki）。
章节来源
- [backend/app/workers/scheduler.py:40-90](file://backend/app/workers/scheduler.py#L40-L90)
- [backend/app/workers/citation_engine.py:211-227](file://backend/app/workers/citation_engine.py#L211-L227)
- [backend/app/workers/platforms/kimi.py:28-48](file://backend/app/workers/platforms/kimi.py#L28-L48)
- [backend/app/workers/platforms/wenxin.py:28-48](file://backend/app/workers/platforms/wenxin.py#L28-L48)
### 错误追踪机制
- 异常捕获与堆栈跟踪：
- 调度器与引擎在关键路径捕获异常并记录详细错误信息，便于定位问题。
- 平台适配器对Playwright操作进行超时与异常处理，并在多次重试后记录最终失败原因。
- 告警通知：
- 建议在应用层或网关层集成告警通道（如邮件、Webhook、IM机器人），当ERROR/WARNING级别日志达到阈值时触发。
- 可结合日志平台的规则引擎或Prometheus Alertmanager实现自动告警。
- 诊断要点：
- 关注平台查询超时、浏览器启动失败、数据库事务提交失败等高频错误。
- 为每次查询生成唯一trace_id，贯穿日志链路，便于跨服务串联分析。
章节来源
- [backend/app/workers/scheduler.py:73-74](file://backend/app/workers/scheduler.py#L73-L74)
- [backend/app/workers/citation_engine.py:211-227](file://backend/app/workers/citation_engine.py#L211-L227)
- [backend/app/workers/platforms/kimi.py:116-119](file://backend/app/workers/platforms/kimi.py#L116-L119)
- [backend/app/workers/platforms/wenxin.py:114-117](file://backend/app/workers/platforms/wenxin.py#L114-L117)
### 性能监控指标
- CPU与内存：通过容器监控（如cAdvisor/Prometheus Node Exporter）采集后端容器的CPU/内存使用率。
- 数据库连接数：从数据库侧查看连接数与慢查询，或通过中间件埋点导出指标。
- API响应时间：在FastAPI中间件中统计请求耗时，按路由分组导出直方图与摘要指标。
- 业务指标：
- 查询任务执行成功率、失败率、平均耗时。
- 平台查询成功率、平均响应时间、重试次数。
- CitationRecord写入速率、QueryTask状态转换时延。
章节来源
- [backend/app/main.py:24-28](file://backend/app/main.py#L24-L28)
- [backend/app/workers/scheduler.py:51-84](file://backend/app/workers/scheduler.py#L51-L84)
- [backend/app/workers/citation_engine.py:159-234](file://backend/app/workers/citation_engine.py#L159-L234)
### 监控工具选择与配置
- Prometheus：抓取后端应用指标（自定义指标+Node Exporter），用于构建仪表盘与告警。
- Grafana：可视化Prometheus数据，创建面板展示健康状态、性能趋势与告警历史。
- 日志平台（可选）：Loki配合Promtail收集日志，Grafana中实现日志与指标联动。
- 告警：Alertmanager基于规则触发，结合企业微信/钉钉/Slack等通道推送。
章节来源
- [backend/requirements.txt:20-22](file://backend/requirements.txt#L20-L22)
- [backend/Dockerfile:35-40](file://backend/Dockerfile#L35-L40)
### 日志分析与故障诊断最佳实践
- 统一日志格式与标签：为每条日志添加服务名、模块、函数、trace_id等标签，便于聚合与检索。
- 分层告警：针对不同级别与模块设置阈值与静默窗口，避免噪声干扰。
- 快速定位：优先查看ERROR/WARNING级别日志，结合trace_id串联相关模块日志。
- 回放与回归：对关键业务路径（如平台查询、数据库写入）建立回放机制，复现问题并验证修复。
## 依赖分析
- 组件耦合：
- 调度器与引擎松耦合，通过接口与数据库交互；平台适配器遵循统一抽象，便于扩展新平台。
- 数据库连接通过依赖注入提供，降低全局状态耦合。
- 外部依赖：
- PostgreSQL/Redis：通过环境变量配置，容器编排保证依赖服务健康。
- Playwright：浏览器自动化依赖系统库，Dockerfile中已安装必要依赖与浏览器。
- 潜在风险：
- 平台查询超时与不稳定：已有重试与超时处理，建议进一步引入熔断与降级策略。
- 日志分散：建议集中化收集与结构化输出，避免grep式排查。
```mermaid
graph LR
REQ["requirements.txt"] --> FASTAPI["FastAPI"]
REQ --> APS["APScheduler"]
REQ --> SQLA["SQLAlchemy"]
REQ --> REDIS["Redis"]
REQ --> PW["Playwright"]
DF["Dockerfile"] --> SYSDEPS["系统依赖安装"]
DF --> PLY["Playwright 安装"]
DF --> CMD["Uvicorn 启动"]
DC["docker-compose.yml"] --> DBH["PostgreSQL 健康检查"]
DC --> RDH["Redis 健康检查"]
DC --> DEP["后端依赖健康启动"]
```
图表来源
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
- [backend/Dockerfile:6-33](file://backend/Dockerfile#L6-L33)
- [backend/docker-compose.yml:16-34](file://backend/docker-compose.yml#L16-L34)
章节来源
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
- [backend/Dockerfile:1-41](file://backend/Dockerfile#L1-L41)
- [backend/docker-compose.yml:1-71](file://backend/docker-compose.yml#L1-L71)
## 性能考虑
- I/O密集型优化：平台查询与数据库写入均为I/O密集，建议：
- 使用连接池与批量写入减少开销。
- 对平台查询结果进行缓存（短期有效），降低重复请求。
- 超时与重试：平台适配器已内置指数退避重试，建议：
- 设置最大重试次数与超时上限，防止雪崩。
- 引入熔断器，当错误率超过阈值时短时间拒绝请求。
- 资源限制：在容器编排中设置CPU/内存限制与重启策略，避免单点故障影响整体。
## 故障排查指南
- 健康检查失败：
- 检查后端/数据库/Redis健康检查配置与日志。
- 确认依赖服务已就绪再启动后端。
- 平台查询失败：
- 查看平台适配器日志，确认浏览器启动与页面交互是否正常。
- 检查网络连通性与平台可用性。
- 数据库写入失败：
- 检查数据库连接字符串与权限。
- 关注事务提交与异常回滚日志。
- 日志分析：
- 使用统一字段检索trace_id，串联各模块日志。
- 结合Grafana面板观察指标趋势，定位异常时段。
章节来源
- [backend/docker-compose.yml:46-50](file://backend/docker-compose.yml#L46-L50)
- [backend/app/workers/platforms/kimi.py:28-48](file://backend/app/workers/platforms/kimi.py#L28-L48)
- [backend/app/workers/platforms/wenxin.py:28-48](file://backend/app/workers/platforms/wenxin.py#L28-L48)
- [backend/app/workers/citation_engine.py:211-227](file://backend/app/workers/citation_engine.py#L211-L227)
## 结论
GEO项目已具备基础的健康检查、容器健康检查与完善的日志记录能力。建议在此基础上引入统一的监控与告警体系（Prometheus/Grafana），完善结构化日志与指标导出，增强平台查询的稳定性与可观测性，以支撑生产环境的持续运维与快速故障定位。
## 附录
- 快速对照表
- 健康检查端点：GET /health
- 数据库连接：DATABASE_URL
- Redis连接：REDIS_URL
- 定时任务：每小时执行一次
- 平台适配器：Kimi、文心一言
章节来源
- [backend/app/main.py:45-47](file://backend/app/main.py#L45-L47)
- [backend/app/config.py:7-8](file://backend/app/config.py#L7-L8)
- [backend/app/workers/scheduler.py:32-38](file://backend/app/workers/scheduler.py#L32-L38)
- [backend/app/workers/platforms/base.py:4-17](file://backend/app/workers/platforms/base.py#L4-L17)
Reference in New Issue View Git Blame Copy Permalink