Administration and Operations

Relevant source files

• admin/client/pyproject.toml
• admin/client/uv.lock
• admin/server/auth.py
• admin/server/config.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
• internal/admin/router.go
• internal/cli/admin_command.go
• internal/cli/admin_parser.go
• internal/cli/cli.go
• internal/cli/cli_http.go
• internal/cli/common_command.go
• internal/cli/lexer.go
• internal/cli/parser.go
• internal/cli/types.go
• internal/cli/user_command.go
• internal/cli/user_parser.go
• internal/dao/document.go
• internal/dao/document_test.go
• internal/handler/document.go
• internal/handler/document_test.go
• internal/router/router.go
• internal/service/nlp/retrieval.go
• test/testcases/test_web_api/test_canvas_app/test_list_operations_unit.py
• web/src/pages/agent/canvas/node/list-operations-node.tsx
• web/src/pages/agent/form/list-operations-form/index.tsx

This page provides a technical overview of the administrative and operational infrastructure of RAGFlow. The system employs a dual-server architecture for administration (Python-based and Go-based), a secure sandbox for code execution, and a comprehensive suite of CLI and migration tools to manage multi-tenant environments and system health.

Admin Service and CLI

RAGFlow features a dedicated administrative layer separate from the core RAG services. This layer is implemented as both a Python-based server and a high-performance Go-based service.

Admin Service Architecture

The Admin Service manages system-wide entities such as users, tenants, and global settings.

• Python Admin Server: Defined in admin/server/, this Flask-based application handles administrative routes like /api/v1/admin/users admin/server/routes.py35-79 It utilizes UserMgr for logic admin/server/services.py40-153 and enforces admin-only access via the @check_admin_auth decorator admin/server/auth.py136-149
• Go Admin Backend: Implemented in internal/admin/, providing high-performance endpoints. The Router in internal/admin/router.go defines a comprehensive suite of protected routes for user management, service control, and system variables internal/admin/router.go58-131
• Health Monitoring: The system provides comprehensive health checks for MySQL/PostgreSQL, Redis, Document Engines (Elasticsearch, Infinity, OceanBase), and MinIO storage api/utils/health_utils.py34-70 The Go backend exposes these via /healthz and /live endpoints internal/admin/router.go40-42
• Default Initialization: On startup, the system automatically initializes a default admin user (admin@ragflow.io) and a corresponding tenant if none exist admin/server/auth.py88-114

RAGFlow CLI

The ragflow-cli is a command-line interface that translates SQL-like commands into API requests.

• Go CLI Client: A robust implementation in internal/cli/ featuring a recursive descent Parser internal/cli/parser.go27-50 and a Lexer internal/cli/lexer.go25-36 It supports two distinct modes: AdminMode and APIMode internal/cli/cli_http.go26-36
• Command Set: Supports extensive administrative actions including admin_login_user internal/cli/admin_parser.go26-60 admin_list_services internal/cli/admin_parser.go154-162 and management of roles, resources, and ingestion tasks internal/cli/admin_command.go120-163
• Python CLI Client: Located in admin/client/, it uses a Lark grammar to parse commands.

For details, see Admin Service and CLI.

---

Sandbox Code Executor

To support the Code component within agent workflows, RAGFlow utilizes a secure sandbox environment. This ensures that user-provided scripts (Python, Node.js) are executed in isolation.

• Execution Strategy: The system provides a SandboxMgr to handle code execution requests admin/server/services.py28
• Provider System: The Go backend defines sandbox provider management via endpoints to list providers, retrieve schemas, and test connections internal/admin/router.go116-120
• Agent Integration: The sandbox is primarily invoked by the Code component in the agent canvas to process data or perform custom logic safely.

For details, see Sandbox Code Executor.

---

Testing Infrastructure

RAGFlow maintains a multi-layered testing suite to ensure system stability across different document engines and model providers.

• Unit and Integration Tests: The codebase includes tests for vision operators deepdoc/vision/operators.py28-208 and document handlers internal/handler/document_test.go
• Benchmarking: The Go CLI includes native benchmark support, allowing commands to be executed with multiple iterations to measure performance internal/cli/admin_command.go30-39
• Health Checks: Real-time monitoring of document store latency and cluster stats (e.g., Elasticsearch cluster health) api/utils/health_utils.py72-82

For details, see Testing Infrastructure.

---

Migration and Utility Tools

The system includes utilities for operational maintenance, data integrity, and versioning.

• Document Processing Utilities: Tools for repairing broken PDFs via Ghostscript api/utils/file_utils.py156-196 and generating thumbnails for various file types api/utils/file_utils.py83-145
• Database Migrations: Scripts for handling schema updates in MySQL/PostgreSQL and migrating document indices.
• Document Management: The DocumentHandler in the Go backend provides sophisticated methods for batch updating metadata, status changes, and ingestion task removal internal/handler/document.go76-84

For details, see Migration and Utility Tools.

---

System Interaction Diagram

Administrative Control Flow

This diagram bridges the Go-based CLI interface to the backend management entities.

Sources: internal/cli/parser.go27-50 internal/cli/cli_http.go38-195 internal/admin/router.go36-136 internal/handler/document.go93-106

Health and Ingestion Monitoring

This diagram maps the administrative probes to the ingestion and storage infrastructure.

Sources: internal/admin/router.go40-42 internal/admin/router.go108-112 internal/cli/admin_command.go53-90 internal/handler/document.go78-82

---

Sources:

• internal/admin/router.go 36-136
• internal/cli/parser.go 27-251
• internal/cli/lexer.go 79-232
• internal/cli/cli_http.go 25-195
• internal/cli/admin_command.go 29-191
• internal/cli/admin_parser.go 26-278
• internal/handler/document.go 48-142
• admin/server/routes.py 35-214
• admin/server/services.py 40-179
• api/utils/health_utils.py 34-186