agentic_huge_data_base / wiki
页面 RAGFlow · 7.8 系统状态与健康监控·DeepWiki 中文全文译文
DeepWiki 中文译文 / RAGFlow / 7.8

7.8 · 系统状态与健康监控（System Status and Health Monitoring）

复杂文档理解与引用检索 · 聚焦本章的模块关系、源码依据与实现要点。

项目RAGFlow 章节7.8 状态全文译文 模块界面与交互、系统架构、检索、召回与索引、存储与持久化
项目要点页2.5 参考项目 项目章节目录RAGFlow DeepWiki 原始章节System Status and Health Monitoring 上一章7.7 下一章8
源码线索
  • admin/server/auth.py
  • admin/server/config.py
  • admin/server/roles.py
  • admin/server/routes.py
  • admin/server/services.py
  • agent/component/list_operations.py
  • api/db/services/system_settings_service.py
  • api/utils/health_utils.py
  • conf/system_settings.json
  • test/testcases/test_web_api/test_canvas_app/test_list_operations_unit.py
模块标签
  • 界面与交互
  • 系统架构
  • 检索、召回与索引
  • 存储与持久化
  • 接口与服务契约

章节正文

系统状态与健康监控

原始 DeepWiki 页面https://deepwiki.com/infiniflow/ragflow/7.8-system-status-and-health-monitoring

系统状态与健康监控

相关源文件

本章引用的主要源码文件：

  • admin/server/auth.py
  • admin/server/config.py
  • admin/server/roles.py
  • admin/server/routes.py
  • admin/server/services.py
  • agent/component/list_operations.py
  • api/db/services/system_settings_service.py
  • api/utils/health_utils.py
  • conf/system_settings.json
  • test/testcases/test_web_api/test_canvas_app/test_list_operations_unit.py
  • web/README.md
  • web/src/components/api-service/chat-overview-modal/anchor.tsx
  • web/src/components/api-service/chat-overview-modal/api-content.tsx
  • web/src/components/api-service/chat-overview-modal/backend-service-api.tsx
  • web/src/components/api-service/chat-overview-modal/markdown-toc.tsx
  • web/src/components/bulk-operate-bar.tsx
  • web/src/components/empty/empty.tsx
  • web/src/components/ui/message.ts
  • web/src/components/ui/ragflow-pagination.tsx
  • web/src/components/ui/scroll-area.tsx
  • web/src/pages/admin/forms/role-form.tsx
  • web/src/pages/admin/forms/user-form.tsx
  • web/src/pages/admin/layouts/authorized-layout.tsx
  • web/src/pages/admin/layouts/navigation-layout.tsx
  • web/src/pages/admin/layouts/root-layout.tsx
  • web/src/pages/admin/login.tsx
  • web/src/pages/admin/monitoring.tsx
  • web/src/pages/admin/roles.tsx
  • web/src/pages/admin/service-detail.tsx
  • web/src/pages/admin/service-status.tsx
  • web/src/pages/admin/task-executor-detail.tsx
  • web/src/pages/admin/user-detail.tsx
  • web/src/pages/admin/users.tsx
  • web/src/pages/admin/whitelist.tsx
  • web/src/pages/agent/canvas/node/list-operations-node.tsx
  • web/src/pages/agent/form/list-operations-form/index.tsx
  • web/src/pages/user-setting/setting-api/index.tsx
  • web/src/pages/user-setting/setting-model/langfuse/index.tsx
  • web/src/services/admin-service.ts
  • web/src/services/admin.service.d.ts

目的与范围

本文档描述了 RAGFlow 的系统健康监控和状态报告基础设施。内容涵盖：为运维监控暴露的健康检查端点、组件状态报告、任务执行器心跳监控，以及模型上下文协议（MCP）服务器集成。该系统通过提供后端服务、文档引擎和任务处理层的实时可见性，确保高可用性。

健康检查端点

RAGFlow 暴露了多个健康检查端点，以支持不同的监控场景——从简单的存活探针到详细的组件状态报告。系统采用多层架构，涉及核心 Python 后端（Quart/Flask）和基于 Go 的管理层。

端点概览
端点认证实现用途
GET /health无Go 管理服务Go 管理服务存活检查
GET /api/v1/admin/ping无admin/server/routes.pyPython 管理端连通性 admin/server/routes.py:38-40
GET /api/v1/admin/auth需要admin/server/routes.py管理会话授权检查 admin/server/routes.py:67-73
GET /system/ping无Python 核心核心后端连通性
GET /system/healthz无api/utils/health_utils.py综合组件健康 api/utils/health_utils.py:34-69
健康监控架构

下图展示了从外部请求到内部代码实体和存储系统的健康监控流程。

系统健康数据流

RAGFlow · 健康监控架构 · 图 1
RAGFlow · 健康监控架构 · 图 1

来源： admin/server/routes.py:38-40, api/utils/health_utils.py:34-69, admin/server/config.py:224-238

服务组件监控

RAGFlow 跟踪多个分布式组件的状态。这些组件被归类为 ServiceType 枚举，包括 METADATA、RETRIEVAL、MESSAGE_QUEUE、RAGFLOW_SERVER、TASK_EXECUTOR 和 FILE_STORE admin/server/config.py:52-59。

服务配置加载

系统通过 load_configurations() 加载组件配置，该方法解析系统设置并将其映射到特定的配置类，例如 MySQLConfig、ElasticsearchConfig 或 RedisConfig admin/server/config.py:224-260。每个配置对象包含一个 detail_func_name，用于特定的健康探测（例如 check_ragflow_server_alive）admin/server/config.py:237。

健康探测逻辑

api/utils/health_utils.py 文件包含对外部依赖进行探测的核心逻辑：

  • 数据库：check_db() 对 MySQL 或 PostgreSQL 执行轻量级的 SELECT 1 探测 api/utils/health_utils.py:34-41。
  • Redis：check_redis() 使用 REDIS_CONN.health() 方法验证连通性 api/utils/health_utils.py:44-50。
  • 文档引擎：check_doc_engine() 支持多个后端。它会调用已配置引擎的 health() 方法，为 Elasticsearch、Infinity 或 OceanBase 提供特定的状态信息 api/utils/health_utils.py:53-60。

来源： admin/server/config.py:52-59, api/utils/health_utils.py:34-60

管理服务状态仪表盘

前端提供了一个位于 /admin/service-status 的综合状态仪表盘 web/src/pages/admin/service-status.tsx:90。该仪表盘可视化展示所有已注册服务的健康状态。

前端组件映射

下图将 UI 组件与底层服务调用和后端路由进行了关联。

管理状态组件映射

RAGFlow · 前端组件映射 · 图 2
RAGFlow · 前端组件映射 · 图 2
关键 UI 功能
  • 状态徽章：服务使用颜色编码的徽章标记为 alive（存活）、timeout（超时）或 fail（失败）web/src/pages/admin/service-status.tsx:149-161。
  • 服务详情：点击服务可查看深入指标，例如 Elasticsearch 的集群统计信息或 OceanBase 的连接池指标 web/src/pages/admin/service-status.tsx:103-109。
  • 任务监控：针对 task_executor 组件的特定视图，显示处理进度和消息队列类型 web/src/pages/admin/service-status.tsx:74。

来源： web/src/pages/admin/service-status.tsx:111-164, web/src/services/admin-service.ts:61

运维数据库监控：OceanBase

对于使用 OceanBase 的部署，RAGFlow 通过 check_oceanbase_health() 提供专门的健康监控 api/utils/health_utils.py:136。

收集的指标：

  • 连通性：跟踪连接状态为 connected（已连接）或 disconnected（已断开）api/utils/health_utils.py:167。
  • 延迟：以毫秒为单位测量；值超过 1000ms 会触发 "degraded"（降级）状态 api/utils/health_utils.py:191。
  • 吞吐量与负载：报告 query_per_second（每秒查询数，QPS）、slow_queries（慢查询数）和 active_connections（活跃连接数）api/utils/health_utils.py:178-180。
  • 存储：报告 storage_used（已用存储）和 storage_total（总存储），用于容量规划 api/utils/health_utils.py:176-177。

来源： api/utils/health_utils.py:136-200

MCP 服务器集成监控

RAGFlow 支持模型上下文协议（MCP）以实现外部工具集成。这些服务器的监控通过 mcp_api 处理。

  • 连通性测试：系统允许通过专用 API 端点测试 MCP 服务器连接 web/src/components/api-service/chat-overview-modal/backend-service-api.tsx:8。
  • 工具发现：监控包括验证 MCP 服务器是否正确地向 RAGFlow 代理暴露其工具模式 agent/component/list_operations.py:48-50。

来源： web/src/components/api-service/chat-overview-modal/api-content.tsx:30, agent/component/list_operations.py:48-52