Admin Service and CLI

Relevant source files

• admin/build_cli_release.sh
• admin/client/http_client.py
• admin/client/parser.py
• admin/client/pyproject.toml
• admin/client/ragflow_cli.py
• admin/client/ragflow_client.py
• admin/client/user.py
• 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/file_service.py
• api/db/services/system_settings_service.py
• api/utils/__init__.py
• api/utils/crypt.py
• api/utils/file_utils.py
• api/utils/health_utils.py
• conf/system_settings.json
• deepdoc/parser/ppt_parser.py
• deepdoc/vision/__init__.py
• deepdoc/vision/operators.py
• deepdoc/vision/postprocess.py
• 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/engine/engine.go
• internal/handler/document.go
• internal/handler/document_test.go
• internal/router/router.go
• internal/service/nlp/retrieval.go
• internal/utility/convert.go
• test/testcases/test_web_api/test_canvas_app/test_list_operations_unit.py
• test/unit_test/deepdoc/vision/test_operators_standardize_image.py
• web/src/pages/agent/canvas/node/list-operations-node.tsx
• web/src/pages/agent/form/list-operations-form/index.tsx

The RAGFlow Admin Service and CLI provide a dedicated management layer for system administrators to oversee users, monitor service health, and perform maintenance tasks. This system is implemented as a dual-layer architecture: a Go-based admin server for core operations and a multi-language CLI (Python and Go) for developer and operator interactions.

Admin Service Architecture

The Admin Service operates as a privileged management interface. It provides endpoints for superuser authentication, user lifecycle management, and system-wide settings.

Server Implementation

The administrative logic is primarily implemented in the Go backend, which provides high-performance handling of system management tasks.

• Go Admin Server: Initialized using the Gin framework, it defines specialized administrative logic in the Handler struct internal/admin/handler.go40-43
• Authentication: Admin login requires the is_superuser flag to be true. The system checks this flag during the login process in Handler.Login internal/admin/handler.go110-113
• Routing: Admin-specific routes are set up with a /api/v1/admin prefix to handle user management, service control, and system variables via the Router.Setup method internal/admin/router.go45-167
• Service Layer: The Service struct encapsulates interactions with various DAOs (Data Access Objects) for managing tenants, files, tasks, and ingestion processes internal/admin/service.go46-67

Data Flow: Admin Authentication

The following diagram illustrates the authentication flow for administrative access.

Admin Login Sequence

Sources: internal/admin/handler.go94-136 internal/admin/router.go49 internal/admin/handler.go46-51

ragflow-cli

The ragflow-cli is a command-line interface that allows administrators and users to interact with RAGFlow services. The codebase features both a Go-native implementation and a Python client wrapper.

Implementation Details

• Command Parsing (Go): The Go implementation uses a custom Lexer and Parser to handle SQL-like syntax (e.g., LIST DATASETS, CREATE USER) and meta-commands internal/cli/parser.go27-42 internal/cli/user_parser.go128-169
• Command Parsing (Python): The Python CLI uses a Lark-based parser to translate natural language commands into API calls via the RAGFlowClient admin/client/ragflow_client.py52-55
• Mode Selection: The CLI supports APIMode and AdminMode, allowing it to target different system components based on the CommandLineMode internal/cli/parser.go236-249 internal/cli/cli_http.go25-36
• Lexical Analysis: The Lexer performs tokenization of input strings, identifying keywords like LOGIN, LIST, SERVICES, and ADMIN internal/cli/lexer.go187-251

Supported Command Categories

The ragflow-cli supports a wide range of commands. Commands are parsed by the Parser internal/cli/parser.go50-61 and then executed by the CLI struct's methods internal/cli/cli_http.go25-36

Category	Example Commands	Go Parser Method	Go Executor Method
System (User)	PING, SHOW VERSION, LIST CONFIGS	parseAPIPingServer internal/cli/user_parser.go65-73 parseAPIShowVersion internal/cli/user_parser.go301-315 parseAPIListConfigs internal/cli/user_parser.go172-180	PingServerByCommand internal/cli/common_command.go112-118 APIShowVersionCommand internal/cli/user_command.go41-73 ListConfigs internal/cli/user_command.go75-115
System (Admin)	ADMIN PING, ADMIN SHOW VERSION, ADMIN LIST CONFIGS	parseAdminPingServer internal/cli/admin_parser.go72-98 parseAdminShowVersion internal/cli/admin_parser.go338-352 parseAdminListConfigs internal/cli/admin_parser.go194-202	PingAdmin internal/cli/admin_command.go27-48 AdminShowVersionCommand internal/cli/admin_command.go109-116 AdminListConfigsCommand internal/cli/admin_command.go263-264
User Management (User)	REGISTER USER, LOGIN USER, LOGOUT	parseAPIRegister internal/cli/user_parser.go75-120 parseAPILoginUser internal/cli/user_parser.go19-53 parseAPILogout internal/cli/user_parser.go55-63	LoginUserByCommand internal/cli/common_command.go33-54 Logout internal/cli/common_command.go216-253
User Management (Admin)	ADMIN CREATE USER, ADMIN DROP USER, ADMIN LIST USERS	parseAdminCreateUser internal/cli/admin_parser.go303-315 parseAdminDropUser internal/cli/admin_parser.go317-328 parseAdminListUsersCommand internal/cli/admin_parser.go273-281	AdminCreateUserCommand internal/cli/admin_command.go221-222 AdminDropUserCommand internal/cli/admin_command.go242-243 AdminListUsersCommand internal/cli/admin_command.go253-254
Service Management (Admin)	ADMIN LIST SERVICES, ADMIN START SERVICE	parseAdminListServices internal/cli/admin_parser.go154-162 parseAdminStartService internal/cli/admin_parser.go362-373	AdminListServicesCommand internal/cli/admin_command.go266-267 AdminStartServiceCommand internal/cli/admin_command.go268-269
Ingestion Management (Admin)	ADMIN LIST INGESTION TASKS, ADMIN STOP INGESTION TASKS	parseAdminListIngestionTasks internal/cli/admin_parser.go258-274 parseAdminStopIngestionTasks internal/cli/admin_parser.go433-446	ListAdminIngestionTasks internal/cli/admin_command.go290-291 AdminStopIngestionCommand internal/cli/admin_command.go284-285

Sources: internal/cli/user_parser.go128-169 internal/cli/parser.go80-144 internal/cli/parser.go146-234 internal/cli/cli_http.go38-200

CLI Command Processing Flow

The following diagram illustrates the general flow of how a command is processed by the Go CLI.

CLI Command Processing Flow

Sources: internal/cli/parser.go50-61 internal/cli/cli_http.go25-35 internal/cli/cli_http.go38-200 internal/admin/handler.go40-51 internal/admin/service.go70-93

Admin Service Logic

The administrative logic is primarily contained in the Go internal/admin package and the Python admin/server directory.

Key Management Functions

• User Management: The Go Service in internal/admin/service.go provides methods to list all users and handle their lifecycle, including transaction-safe user creation internal/admin/service.go144-161 internal/admin/service.go172-229
• Authentication Control: Admin login requires superuser privileges, verified via the IsSuperuser pointer in the user entity internal/admin/handler.go110-113
• Ingestion Task Management: The Go Service provides functions to list, stop, and remove ingestion tasks by wrapping the IngestionTaskService internal/admin/service.go106-116
• Queue Operations: The Go handler allows administrators to inspect message queues, publish messages, and pull messages for debugging internal/admin/router.go101-107

Service Monitoring

The admin handler provides endpoints to monitor the health and configuration of internal components.

• Health Check: GET /healthz returns the status of various components (Redis, DB, etc.) via service.GetComponentsHealthz internal/admin/handler.go60-73
• System Configs: The CLI ListConfigs command retrieves settings, reporting on Redis, Database, and Document Engine status internal/cli/user_command.go75-115
• Log Level Management: Administrators can get and set the system's log level via dedicated endpoints internal/admin/router.go92-93
• Version Information: The admin server exposes its version information through a GET /version endpoint internal/admin/router.go99

Code Entity Mapping: Admin Service Layer

Sources: internal/admin/handler.go40-51 internal/admin/router.go36-167 internal/admin/service.go70-93 internal/admin/service.go106-116

Health Monitoring Implementation

The system tracks service availability through heartbeats and periodic status updates.

1. Health Check Endpoints: The Go server provides /healthz, /live, and /api/v1/admin/ping endpoints used by the CLI to verify connectivity internal/admin/router.go40-48 internal/admin/handler.go60-83
2. System Config Reporting: The GetConfigs function in the CLI parses server configuration data to report on the status of Redis, the Document Engine (Elasticsearch/Infinity), and the Database internal/cli/user_command.go117-208
3. Ingestion Monitoring: The Service.ListIngestionTasks method retrieves all tasks for administrative oversight internal/admin/service.go106-108
4. Queue Health: The Handler.ShowMessageQueue endpoint allows monitoring of message flow in the system internal/admin/router.go103

Sources: internal/admin/handler.go60-83 internal/cli/user_command.go117-208 internal/admin/service.go106-108 internal/admin/router.go103