This document describes RAGFlow's system health monitoring and status reporting infrastructure. It covers the health check endpoints exposed for operational monitoring, component status reporting, task executor heartbeat monitoring, and the Model Context Protocol (MCP) server integration. This system ensures high availability by providing real-time visibility into the backend services, document engines, and task processing layers across both Python and Go implementations.
RAGFlow exposes multiple health check endpoints to support different monitoring use cases, from simple liveness probes to detailed component status reporting. The system uses a multi-layered approach involving the core Python backend, the Go-based administrative layer, and specialized storage engine probes.
| Endpoint | Authentication | Implementation | Purpose |
|---|---|---|---|
GET /api/v1/admin/ping | None | admin/server/routes.py | Admin connectivity check admin/server/routes.py38-40 |
GET /v1/system/ping | None | internal/handler/system.go | Go backend liveness check internal/handler/system.go47-49 |
GET /v1/system/status | Required | internal/handler/system.go | Go detailed component status internal/handler/system.go105-119 |
GET /v1/system/healthz | None | internal/handler/system.go | Dependency health (Python-compatible) internal/handler/system.go59-66 |
GET /health | None | deepdoc/server (via Docker) | DeepDoc service health check docker/docker-compose.yml15-19 |
GET /system/ping | None | api/apps/restful_apis/system_api.py | Python REST API liveness check api/apps/restful_apis/system_api.py38-40 |
The following diagram maps the health monitoring flow from external requests to internal code entities and storage systems.
System Health Data Flow
Sources: api/utils/health_utils.py34-69 internal/service/system.go109-118 admin/server/routes.py38-40 internal/handler/system.go59-66 api/apps/restful_apis/system_api.py38-40
health_utils.py)The comprehensive health check logic in Python uses a series of probes:
check_db() executes a lightweight SELECT 1 query via the DB model api/utils/health_utils.py34-41check_redis() uses the REDIS_CONN.health() method to verify connectivity api/utils/health_utils.py44-51check_doc_engine() calls the health() method of the configured docStoreConn (Elasticsearch, Infinity, or OceanBase) api/utils/health_utils.py53-61check_storage() verifies the file storage backend via settings.STORAGE_IMPL.health() api/utils/health_utils.py63-69check_oceanbase_health() api/utils/health_utils.py124-188internal/service/system.go)The Go backend provides a parallel status reporting system via SystemService:
getDocEngineStatus() retrieves the engine instance via engine.Get() and performs a Ping() with a 5-second timeout internal/service/system.go120-154getStorageStatus() checks the storage.GetStorageFactory() for initialization and calls Health() internal/service/system.go156-191getDatabaseStatus() uses dao.GetDB().DB().Ping() to verify the SQL connection internal/service/system.go193-234getRedisStatus() checks the internal Redis client health internal/service/system.go236-253Sources: api/utils/health_utils.py34-69 api/utils/health_utils.py124-188 internal/service/system.go109-154 internal/service/system.go193-253
RAGFlow monitors the background task processing layer through heartbeats stored in Redis.
In the Go backend, the GetStatus() method in internal/service/system.go aggregates component health and task executor heartbeats internal/service/system.go110-118 The heartbeats are retrieved via getTaskExecutorHeartbeats() which queries the Redis store for active worker metadata internal/service/system.go106 In Python, the status() endpoint in system_api.py retrieves these from the TASKEXE set in Redis api/apps/restful_apis/system_api.py166-176
Executors are identified by a HOST_ID. By default, this is the system hostname, but if the hostname exceeds 32 characters, it is truncated to an MD5 hash docker/entrypoint.sh62-69 This ID is passed to task executor processes to track their specific health status docker/entrypoint.sh212-214
Sources: internal/service/system.go106-118 api/apps/restful_apis/system_api.py166-176 docker/entrypoint.sh62-69 docker/entrypoint.sh212-214
The Model Context Protocol (MCP) server integration allows RAGFlow to act as a tool provider for external LLM clients.
The MCP server is enabled via the --enable-mcpserver flag in docker/entrypoint.sh docker/entrypoint.sh86-89 It runs as a Starlette application mcp/server/server.py31-34 and supports multiple transport modes:
The RAGFlowConnector class handles the internal API communication between the MCP server and the RAGFlow backend mcp/server/server.py58-63 To ensure performance, it implements metadata caching:
_dataset_metadata_cache stores dataset metadata with a TTL of 300 seconds mcp/server/server.py59-64_document_metadata_cache tracks document lists per dataset to reduce API roundtrips mcp/server/server.py65MCP Integration Mapping
Sources: mcp/server/server.py38-118 docker/entrypoint.sh86-89 docker/entrypoint.sh47-50
The Admin Service provides a dedicated management layer for system operators, exposing endpoints for user and system health.
The Admin layer is enabled via the --enable-adminserver flag docker/entrypoint.sh90-93 In the standard Docker deployment, the Admin service is exposed on port 9381 (Python) or 9383 (Go) docker/docker-compose.yml52-55
The admin/server/routes.py file defines the administrative interface:
/ping returns a simple "pong" response admin/server/routes.py38-41/users allows admins to list all registered users, including their is_active and is_superuser status admin/server/routes.py76-85get_log_levels and set_log_level admin/server/routes.py33Admin Service Mapping
Sources: admin/server/routes.py28-85 admin/server/services.py40-55 docker/entrypoint.sh90-93 docker/docker-compose.yml45-55
Refresh this wiki