Admin Service and CLI

Relevant source files

• admin/build_cli_release.sh
• admin/client/http_client.py
• admin/client/parser.py
• admin/client/ragflow_cli.py
• admin/client/ragflow_client.py
• api/utils/__init__.py
• api/utils/crypt.py
• cmd/admin_server.go
• cmd/ragflow_cli.go
• internal/admin/handler.go
• internal/admin/password.go
• internal/admin/router.go
• internal/admin/service.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/http_client.go
• internal/cli/lexer.go
• internal/cli/parser.go
• internal/cli/response.go
• internal/cli/types.go
• internal/cli/user_command.go
• internal/cli/user_parser.go
• internal/common/error_code.go
• internal/common/smtp_config.go
• internal/common/status_message.go
• internal/dao/user.go
• internal/engine/elasticsearch/client.go
• internal/engine/engine.go
• internal/handler/user.go
• internal/server/config.go
• internal/service/user.go
• internal/utility/captcha_png.go
• internal/utility/convert.go
• internal/utility/otp.go
• internal/utility/smtp.go
• internal/utility/token.go

The RAGFlow Admin Service and CLI provide a dedicated management layer for system administrators to oversee users, monitor service health, manage ingestion tasks, and perform maintenance. 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 task monitoring.

Server Implementation

The administrative logic is primarily implemented in the Go backend, which serves as the central point for privileged operations.

• Go Admin Server: Initialized via the AdminConfig which defines the host and port internal/server/config.go58-62 The server uses the Gin framework and is managed by internal/admin/handler.go and internal/admin/service.go internal/admin/handler.go39-50
• Authentication: Admin login requires the IsSuperuser flag to be true. The Login handler in Go verifies this flag after a successful email/password check internal/admin/handler.go145-153
• Service Layer: The admin.Service struct aggregates various DAOs (Data Access Objects) to perform cross-functional administrative tasks, including user, tenant, and ingestion task management internal/admin/service.go45-91

Data Flow: Admin Authentication

The following diagram illustrates the authentication flow for administrative access via the Go-based admin handler.

Admin Login Sequence

Sources: internal/admin/handler.go124-185 internal/service/user.go108-171 internal/admin/handler.go145-152

ragflow-cli

The ragflow-cli is a command-line interface that allows administrators and users to interact with RAGFlow services. It features a robust Go-based implementation with a custom parser and a Python client for scriptability.

Implementation Details

• Command Parsing: The Go CLI uses a custom recursive descent Parser internal/cli/parser.go27-42 and a Lexer internal/cli/lexer.go25-30 to handle SQL-like syntax. It supports different modes: AdminMode and APIMode internal/cli/parser.go254-262
• Lexical Analysis: The lexer recognizes keywords like LOGIN, DATASETS, INGESTION, and METADATA internal/cli/lexer.go187-250 internal/cli/types.go26-185
• Configuration: The CLI reads from rf.yml to manage multiple API server profiles, including host, tokens, and credentials internal/cli/cli.go49-56

Supported Command Categories

Category	Example Commands	File Reference
System	PING, SHOW SERVER VERSION, LIST CONFIGS	internal/cli/user_command.go40-114 internal/cli/user_parser.go62-70
User Mgmt	REGISTER USER, LOGIN USER, LIST USERS	internal/cli/user_parser.go72-117 internal/cli/user_parser.go27-60
Data Mgmt	LIST DATASETS, LIST DOCUMENTS FROM 'id', GET METADATA OF DATASET	internal/cli/user_parser.go186-220 internal/cli/user_parser.go222-268
Ingestion	LIST INGESTION, START INGESTION, STOP INGESTION	internal/cli/user_parser.go162-163 internal/cli/user_parser.go221-224
Admin	LIST SERVICES, SHOW SERVICE <num>, SHUTDOWN SERVICE	admin/client/ragflow_client.py120-170 internal/cli/parser.go80-144

Sources: internal/cli/user_parser.go17-270 internal/cli/types.go26-203 internal/cli/user_command.go40-114

Admin Service Logic

The admin.Service in Go encapsulates the business logic for privileged operations.

Key Management Functions

• Ingestion Task Monitoring: ListIngestionTasks retrieves all tasks and joins them with user information and the latest logs to show the current processing step internal/admin/service.go104-148
• Task Control: StopIngestionTasks sets a task status to STOPPING and publishes the stop signal to the message queue (e.g., Redis Streams or Nats) internal/admin/service.go167-186
• User Management: ListUsers provides a summary of all registered accounts, including their superuser status and creation dates internal/admin/service.go214-231
• Session Management: Logout invalidates a user's session by prefixing their access token with INVALID_ in the database internal/admin/service.go94-101

Health Monitoring and Diagnostics

The admin handler provides diagnostic endpoints for system maintenance.

• Health Check: GET /admin/health returns basic service status internal/admin/handler.go106-108
• Configuration Inspection: GetConfigs allows administrators to verify the connectivity and host addresses for Redis, the Database, and the Document Engine (Elasticsearch or Infinity) internal/cli/user_command.go116-207

Code Entity Mapping: Admin Service Layer

Sources: internal/admin/handler.go39-50 internal/admin/service.go45-91 internal/admin/service.go167-186 internal/admin/handler.go111-113

Health Monitoring Implementation

The system tracks service availability and configuration integrity through several mechanisms:

1. Ping/Pong Mechanism: Both Admin and API modes support a PING command. Admin mode hits /admin/ping while API mode hits /system/ping internal/cli/common_command.go106-125
2. Benchmark Mode: Commands like ShowServerVersion and Ping support an iterations parameter to perform multiple requests and measure average duration/latency internal/cli/user_command.go40-52 internal/cli/common_command.go98-104
3. Engine Diagnostics: The GetConfigs utility specifically extracts host and type information for the DocEngine (Elasticsearch/Infinity) and StorageEngine (Minio), allowing operators to identify configuration mismatches internal/cli/user_command.go128-205
4. Client-Side Validation: The Python RAGFlowClient performs a ping_server check before login to ensure the target instance is reachable admin/client/ragflow_client.py57-68

Sources: internal/cli/user_command.go40-207 internal/cli/common_command.go98-158 admin/client/ragflow_client.py86-98