# 系统监控与健康状态

1. 目的与范围 #

本文档介绍Ragflow-Plus的系统监控与健康状态子系统，提供基础设施级别的监控能力。该系统管理数据库连接，监控容器部署中的服务健康状态，并为系统管理员提供诊断工具，确保平台的可靠性和性能。

关于部署配置详情，请参阅 Docker 部署。关于外部服务设置，请参阅 外部服务设置。

1.1 系统监控功能 #

系统监控和健康子系统使管理员能够：

• 监控MySQL、Elasticsearch、Redis和MinIO服务的数据库连接性
• 对所有基础设施组件执行自动化健康检查
• 诊断连接问题和服务故障
• 验证环境配置和服务依赖
• 确保容器编排和网络健康
• 跟踪系统资源使用情况和性能指标

2. 系统架构 #

系统监控架构在容器编排、数据库连接管理和健康检查验证层之间运行。

2.1 基础设施健康监控概述 #

系统监控架构包含多个层次：

2.2 服务依赖和健康架构 #

配置管理和连接工厂的架构：

3. 数据库连接管理 #

数据库连接管理系统通过工厂函数和环境感知配置为所有基础设施服务提供集中式连接。

3.1 连接工厂函数 #

系统提供以下连接工厂函数：

3.1.1 MySQL连接工厂 #

def get_db_connection():
    """获取MySQL数据库连接"""
    config = DB_CONFIG
    return pymysql.connect(
        host=config['host'],
        port=config['port'],
        user=config['user'],
        password=config['password'],
        database=config['database'],
        charset='utf8mb4'
    )

3.1.2 MinIO连接工厂 #

def get_minio_client():
    """获取MinIO客户端"""
    config = MINIO_CONFIG
    return Minio(
        config['endpoint'],
        access_key=config['access_key'],
        secret_key=config['secret_key'],
        secure=config.get('secure', False)
    )

3.1.3 Elasticsearch连接工厂 #

def get_es_client():
    """获取Elasticsearch客户端"""
    config = ES_CONFIG
    return Elasticsearch(
        [f"{config['host']}:{config['port']}"],
        http_auth=(config.get('user'), config.get('password'))
    )

3.1.4 Redis连接工厂 #

def get_redis_connection():
    """获取Redis连接"""
    config = REDIS_CONFIG
    return redis.Redis(
        host=config['host'],
        port=config['port'],
        password=config.get('password'),
        db=config.get('db', 0),
        decode_responses=True
    )

3.2 环境感知配置 #

系统通过is_running_in_docker()函数自动检测运行环境，并根据环境调整配置：

3.2.1 Docker环境检测 #

def is_running_in_docker():
    """检测是否在Docker容器中运行"""
    # 检查/.dockerenv文件
    if os.path.exists('/.dockerenv'):
        return True

    # 检查/proc/self/cgroup
    try:
        with open('/proc/self/cgroup', 'r') as f:
            return 'docker' in f.read()
    except:
        pass

    return False

3.2.2 配置选择逻辑 #

• Docker环境：使用容器服务名称作为主机名（如mysql、es01、minio、redis）
• 非Docker环境：使用环境变量或配置文件中的主机名和端口

3.3 连接测试逻辑 #

test_connections()函数实现全面的服务验证：

1. MySQL验证：执行SELECT 1查询以验证数据库连接性和权限
2. MinIO验证：列出可用存储桶以验证对象存储访问
3. Elasticsearch验证：检索集群信息和版本详情
4. Redis验证：执行ping操作以验证缓存连接性

3.3.1 MySQL测试实现 #

def test_connections():
    """测试所有服务连接"""
    results = {}

    # MySQL测试
    try:
        db_conn = get_db_connection()
        cursor = db_conn.cursor()
        cursor.execute("SELECT 1")
        cursor.close()
        db_conn.close()
        results['mysql'] = {'status': 'ok', 'message': 'Connected'}
    except Exception as e:
        results['mysql'] = {'status': 'error', 'message': str(e)}

    # MinIO测试
    try:
        client = get_minio_client()
        buckets = client.list_buckets()
        results['minio'] = {'status': 'ok', 'buckets': len(buckets)}
    except Exception as e:
        results['minio'] = {'status': 'error', 'message': str(e)}

    # Elasticsearch测试
    try:
        es = get_es_client()
        info = es.info()
        results['elasticsearch'] = {'status': 'ok', 'version': info['version']['number']}
    except Exception as e:
        results['elasticsearch'] = {'status': 'error', 'message': str(e)}

    # Redis测试
    try:
        r = get_redis_connection()
        r.ping()
        results['redis'] = {'status': 'ok', 'message': 'Connected'}
    except Exception as e:
        results['redis'] = {'status': 'error', 'message': str(e)}

    return results

4. 健康检查和诊断系统 #

健康检查和诊断系统提供自动化的服务健康验证和故障诊断能力。

4.1 核心健康检查函数 #

系统提供以下核心健康检查功能：

4.1.1 系统状态检查 #

主应用提供/api/system/status端点，检查以下组件：

• 文档引擎（Elasticsearch）：检查连接和集群状态
• 存储（MinIO）：检查对象存储访问
• 数据库（MySQL）：检查数据库连接
• Redis：检查缓存连接
• 任务执行器心跳：监控任务执行器状态

4.1.2 健康检查响应格式 #

{
  "doc_engine": {
    "type": "elasticsearch",
    "status": "green",
    "elapsed": "12.5"
  },
  "storage": {
    "storage": "minio",
    "status": "green",
    "elapsed": "5.2"
  },
  "database": {
    "database": "mysql",
    "status": "green",
    "elapsed": "3.1"
  },
  "redis": {
    "status": "green",
    "elapsed": "1.5"
  },
  "task_executor_heartbeats": {
    "TASKEXE_1": [
      {
        "timestamp": 1234567890,
        "status": "running"
      }
    ]
  }
}

4.1.3 状态颜色编码 #

• green：服务正常运行
• yellow：服务部分可用
• red：服务不可用或出现错误

4.2 Docker健康检查集成 #

Docker Compose配置包含服务依赖和健康检查：

4.2.1 服务依赖配置 #

services:
  ragflowplus-server:
    depends_on:
      mysql:
        condition: service_healthy
      es01:
        condition: service_healthy
      minio:
        condition: service_healthy
      redis:
        condition: service_healthy

4.2.2 健康检查配置示例 #

services:
  mysql:
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

  es01:
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:9200/_cluster/health || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 5

  minio:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

4.3 任务执行器心跳监控 #

系统通过Redis监控任务执行器的心跳：

4.3.1 心跳机制 #

• 任务执行器每30秒发送一次心跳
• 心跳信息存储在Redis有序集合中
• 系统检查最近30分钟内的心跳记录

4.3.2 心跳数据结构 #

{
  "task_executor_id": "TASKEXE_1",
  "timestamp": 1234567890,
  "status": "running",
  "active_tasks": 2,
  "completed_tasks": 150
}

5. 监控最佳实践 #

5.1 定期健康检查 #

• 设置定期健康检查任务（建议每5分钟）
• 记录健康检查结果到日志系统
• 配置告警规则，当服务状态变为red时发送通知

5.2 性能监控 #

• 监控健康检查响应时间（elapsed字段）
• 跟踪服务连接池使用情况
• 监控系统资源使用（CPU、内存、磁盘）

5.3 故障诊断 #

• 检查健康检查错误消息
• 验证服务配置和网络连接
• 查看服务日志以获取详细错误信息
• 使用test_connections()函数进行手动诊断

5.4 容器健康检查 #

• 确保所有服务容器配置了健康检查
• 使用depends_on确保服务启动顺序
• 监控容器重启次数和状态

6. 故障排查 #

6.1 常见问题 #

6.1.1 MySQL连接失败 #

• 检查MySQL服务是否运行
• 验证数据库凭据是否正确
• 检查网络连接和防火墙设置
• 确认数据库用户有足够的权限

6.1.2 Elasticsearch连接失败 #

• 检查Elasticsearch服务是否运行
• 验证集群健康状态
• 检查索引是否正常
• 验证认证凭据

6.1.3 MinIO连接失败 #

• 检查MinIO服务是否运行
• 验证访问密钥和秘密密钥
• 检查存储桶是否存在
• 验证网络连接

6.1.4 Redis连接失败 #

• 检查Redis服务是否运行
• 验证密码配置
• 检查内存使用情况
• 验证网络连接

6.2 诊断工具 #

使用以下工具进行故障诊断：

1. 手动连接测试：调用test_connections()函数
2. 日志检查：查看应用和服务日志
3. 网络诊断：使用ping和telnet测试网络连接
4. 容器检查：使用docker ps和docker logs检查容器状态

7. 总结 #

系统监控与健康状态子系统为Ragflow-Plus平台提供了全面的基础设施监控能力。通过自动化的健康检查、环境感知配置和详细的诊断工具，系统管理员可以确保平台的可靠性和性能，快速识别和解决服务故障。