告别繁琐——RAGFlow CLI 让后端管理变得轻而易举
阅读时间 11 分钟
为了满足系统运维监控以及用户账户管理的精细化需求，特别是针对 RAGFlow 用户目前面临的“用户无法自行找回遗失密码”、“账户状态难以有效管控”等实际问题，RAGFlow 正式推出了一款专业的后端管理命令行工具。
该工具基于清晰的客户端-服务器架构，通过采用功能分离的设计理念，构建了一个高效、可靠的系统管理通道，使管理员能够在底层实现系统恢复和权限控制。
具体的架构设计如下图所示
通过此工具，RAGFlow 用户可以一站式地了解 RAGFlow Server 以及 MySQL、Elasticsearch、Redis、MinIO 和 Infinity 等组件的运行状态。它还支持全面的用户生命周期管理，包括账户创建、状态控制、密码重置和数据清理。
启动服务
如果您通过 Docker 部署 RAGFlow，请修改 docker/docker_compose.yml 文件，在服务启动命令中添加参数。
command:
- --enable-adminserver
如果您从源代码部署 RAGFlow，可以直接执行以下命令来启动管理服务器
python3 admin/server/admin_server.py
服务器启动后，默认监听 9381 端口，等待客户端连接。如果您需要使用其他端口，请修改 docker/.env 文件中的 ADMIN_SVR_HTTP_PORT 配置项。
安装客户端并连接至管理服务
建议使用 pip 安装指定版本的客户端
pip install ragflow-cli==0.21.0
0.21.0 版本是当前的最新版本。请确保 ragflow-cli 的版本与 RAGFlow 服务器的版本相匹配，以避免兼容性问题。
ragflow-cli -h 127.0.0.1 -p 9381
这里，-h 指定服务器IP，-p 指定服务器端口。如果服务器部署在不同的地址或端口，请相应地调整参数。
首次登录时，输入默认的管理员密码 admin。成功登录后，建议及时在命令行工具中更改默认密码以增强安全性。
命令使用指南
通过客户端输入以下命令，您可以方便地管理用户并监控服务的运行状态。
交互功能说明
- 支持使用方向键移动光标和查看历史命令。
- 按
Ctrl+C可以随时终止当前的交互。 - 如果您需要复制内容，请避免使用
Ctrl+C以防意外中断进程。
命令格式规范
- 所有命令不区分大小写，且必须以分号
;结尾。 - 用户名和密码等文本参数需要用单引号
'或双引号"括起来。 - 密码中禁止使用
\、'和"等特殊字符。
服务管理命令
LIST SERVICES;
- 列出 RAGFlow 后端服务及所有关联中间件的运行状态。
使用示例
admin> list services;
Listing all services
+-------------------------------------------------------------------------------------------+-----------+----+---------------+-------+----------------+---------+
| extra | host | id | name | port | service_type | status |
+-------------------------------------------------------------------------------------------+-----------+----+---------------+-------+----------------+---------+
| {} | 0.0.0.0 | 0 | ragflow_0 | 9380 | ragflow_server | Timeout |
| {'meta_type': 'mysql', 'password': 'infini_rag_flow', 'username': 'root'} | localhost | 1 | mysql | 5455 | meta_data | Alive |
| {'password': 'infini_rag_flow', 'store_type': 'minio', 'user': 'rag_flow'} | localhost | 2 | minio | 9000 | file_store | Alive |
| {'password': 'infini_rag_flow', 'retrieval_type': 'elasticsearch', 'username': 'elastic'} | localhost | 3 | elasticsearch | 1200 | retrieval | Alive |
| {'db_name': 'default_db', 'retrieval_type': 'infinity'} | localhost | 4 | infinity | 23817 | retrieval | Timeout |
| {'database': 1, 'mq_type': 'redis', 'password': 'infini_rag_flow'} | localhost | 5 | redis | 6379 | message_queue | Alive |
+-------------------------------------------------------------------------------------------+-----------+----+---------------+-------+----------------+---------+
列出 RAGFlow 后端服务及所有关联中间件的运行状态。
SHOW SERVICE <id>;
- 查询指定服务的详细运行状态。
<id>: 执行命令LIST SERVICES;后显示结果中的服务标识符 ID。
使用示例
- 查询 RAGFlow 后端服务
admin> show service 0;
Showing service: 0
Service ragflow_0 is alive. Detail:
Confirm elapsed: 4.1 ms.
响应表明 RAGFlow 后端服务在线，响应时间为 4.1 毫秒。
- 查询 MySQL 服务
admin> show service 1;
Showing service: 1
Service mysql is alive. Detail:
+---------+----------+------------------+------+------------------+------------------------+-------+-----------------+
| command | db | host | id | info | state | time | user |
+---------+----------+------------------+------+------------------+------------------------+-------+-----------------+
| Daemon | None | localhost | 5 | None | Waiting on empty queue | 86356 | event_scheduler |
| Sleep | rag_flow | 172.18.0.6:56788 | 8790 | None | | 2 | root |
| Sleep | rag_flow | 172.18.0.6:53482 | 8791 | None | | 73 | root |
| Query | rag_flow | 172.18.0.6:56794 | 8795 | SHOW PROCESSLIST | init | 0 | root |
+---------+----------+------------------+------+------------------+------------------------+-------+-----------------+
响应表明 MySQL 服务在线，当前的连接和执行状态如上表所示。
- 查询 MinIO 服务
admin> show service 2;
Showing service: 2
Service minio is alive. Detail:
Confirm elapsed: 2.3 ms.
响应表明 MinIO 服务在线，响应时间为 2.3 毫秒。
- 查询 Elasticsearch 服务
admin> show service 3;
Showing service: 3
Service elasticsearch is alive. Detail:
+----------------+------+--------------+---------+----------------+--------------+---------------+--------------+------------------------------+----------------------------+-----------------+-------+---------------+---------+-------------+---------------------+--------+------------+--------------------+
| cluster_name | docs | docs_deleted | indices | indices_shards | jvm_heap_max | jvm_heap_used | jvm_versions | mappings_deduplicated_fields | mappings_deduplicated_size | mappings_fields | nodes | nodes_version | os_mem | os_mem_used | os_mem_used_percent | status | store_size | total_dataset_size |
+----------------+------+--------------+---------+----------------+--------------+---------------+--------------+------------------------------+----------------------------+-----------------+-------+---------------+---------+-------------+---------------------+--------+------------+--------------------+
| docker-cluster | 8 | 0 | 1 | 2 | 3.76 GB | 2.15 GB | 21.0.1+12-29 | 17 | 757 B | 17 | 1 | ['8.11.3'] | 7.52 GB | 2.30 GB | 31 | green | 226 KB | 226 KB |
+----------------+------+--------------+---------+----------------+--------------+---------------+--------------+------------------------------+----------------------------+-----------------+-------+---------------+---------+-------------+---------------------+--------+------------+--------------------+
响应表明 Elasticsearch 集群运行正常，具体指标包括文档数、索引状态、内存使用情况等。
- 查询 Infinity 服务
admin> show service 4;
Showing service: 4
Fail to show service, code: 500, message: Infinity is not in use.
响应表明 Infinity 当前未被 RAGFlow 系统使用。
admin> show service 4;
Showing service: 4
Service infinity is alive. Detail:
+-------+--------+----------+
| error | status | type |
+-------+--------+----------+
| | green | infinity |
+-------+--------+----------+
启用 Infinity 并再次查询后，响应表明 Infinity 服务在线且状态良好。
- 查询 Redis 服务
admin> show service 5;
Showing service: 5
Service redis is alive. Detail:
+-----------------+-------------------+---------------------------+-------------------------+---------------+-------------+--------------------------+---------------------+-------------+
| blocked_clients | connected_clients | instantaneous_ops_per_sec | mem_fragmentation_ratio | redis_version | server_mode | total_commands_processed | total_system_memory | used_memory |
+-----------------+-------------------+---------------------------+-------------------------+---------------+-------------+--------------------------+---------------------+-------------+
| 0 | 3 | 10 | 3.03 | 7.2.4 | standalone | 404098 | 30.84G | 1.29M |
+-----------------+-------------------+---------------------------+-------------------------+---------------+-------------+--------------------------+---------------------+-------------+
响应表明 Redis 服务在线，版本号、部署模式和资源使用情况如上表所示。
用户管理命令
LIST USERS;
- 列出 RAGFlow 系统中的所有用户。
使用示例
admin> list users;
Listing all users
+-------------------------------+----------------------+-----------+----------+
| create_date | email | is_active | nickname |
+-------------------------------+----------------------+-----------+----------+
| Mon, 13 Oct 2025 15:58:42 GMT | admin@ragflow.io | 1 | admin |
| Mon, 13 Oct 2025 15:54:34 GMT | lynn_inf@hotmail.com | 1 | Lynn |
+-------------------------------+----------------------+-----------+----------+
响应表明系统中当前有两名用户，状态均为启用。
其中，admin@ragflow.io 是管理员账号，在系统初始启动时自动创建。
SHOW USER <username>;
- 通过邮箱查询用户详细信息。
<username>: 用户的邮箱地址，必须用单引号'或双引号"括起来。
使用示例
- 查询管理员用户
admin> show user "admin@ragflow.io";
Showing user: admin@ragflow.io
+-------------------------------+------------------+-----------+--------------+------------------+--------------+----------+-----------------+---------------+--------+-------------------------------+
| create_date | email | is_active | is_anonymous | is_authenticated | is_superuser | language | last_login_time | login_channel | status | update_date |
+-------------------------------+------------------+-----------+--------------+------------------+--------------+----------+-----------------+---------------+--------+-------------------------------+
| Mon, 13 Oct 2025 15:58:42 GMT | admin@ragflow.io | 1 | 0 | 1 | True | English | None | None | 1 | Mon, 13 Oct 2025 15:58:42 GMT |
+-------------------------------+------------------+-----------+--------------+------------------+--------------+----------+-----------------+---------------+--------+-------------------------------+
响应结果显示 admin@ragflow.io 是超级管理员，且当前状态为已启用 (enabled)。
- 查询普通用户
admin> show user "lynn_inf@hotmail.com";
Showing user: lynn_inf@hotmail.com
+-------------------------------+----------------------+-----------+--------------+------------------+--------------+----------+-------------------------------+---------------+--------+-------------------------------+
| create_date | email | is_active | is_anonymous | is_authenticated | is_superuser | language | last_login_time | login_channel | status | update_date |
+-------------------------------+----------------------+-----------+--------------+------------------+--------------+----------+-------------------------------+---------------+--------+-------------------------------+
| Mon, 13 Oct 2025 15:54:34 GMT | lynn_inf@hotmail.com | 1 | 0 | 1 | False | English | Mon, 13 Oct 2025 15:54:33 GMT | password | 1 | Mon, 13 Oct 2025 17:24:09 GMT |
+-------------------------------+----------------------+-----------+--------------+------------------+--------------+----------+-------------------------------+---------------+--------+-------------------------------+
响应结果显示 lynn_inf@hotmail.com 是一个通过密码登录的普通用户，最后登录时间显示为提供的时间戳。
CREATE USER <username> <password>;
- 创建一个新用户。
<username>: 用户的邮箱地址，必须符合标准的邮箱格式规范。<password>: 用户的密码，不得包含\、'或"等特殊字符。
使用示例
admin> create user "example@ragflow.io" "psw";
Create user: example@ragflow.io, password: psw, role: user
+----------------------------------+--------------------+----------------------------------+--------------+---------------+----------+
| access_token | email | id | is_superuser | login_channel | nickname |
+----------------------------------+--------------------+----------------------------------+--------------+---------------+----------+
| be74d786a9b911f0a726d68c95a0776b | example@ragflow.io | be74d6b4a9b911f0a726d68c95a0776b | False | password | |
+----------------------------------+--------------------+----------------------------------+--------------+---------------+----------+
已成功创建一个普通用户。昵称和头像等个人信息可由用户在登录后访问个人资料页面自行设置。
ALTER USER PASSWORD <username> <new_password>;
- 更改用户密码。
<username>: 用户邮箱地址<password>: 新密码（不得与旧密码相同，且不得包含特殊字符）
使用示例
admin> alter user password "example@ragflow.io" "psw";
Alter user: example@ragflow.io, password: psw
Same password, no need to update!
当新密码与旧密码相同时，系统提示无需更改。
admin> alter user password "example@ragflow.io" "new psw";
Alter user: example@ragflow.io, password: new psw
Password updated successfully!
密码已成功更新。此后用户可以使用新密码登录。
ALTER USER ACTIVE <username> <on/off>;
- 启用或禁用用户。
<username>: 用户邮箱地址<on/off>: 启用或禁用状态
使用示例
admin> alter user active "example@ragflow.io" off;
Alter user example@ragflow.io activate status, turn off.
Turn off user activate status successfully!
用户已成功禁用。只有处于禁用状态的用户才能被删除。
DROP USER <username>;
- 删除用户及其所有关联数据
<username>: 用户邮箱地址
重要提示
- 只有已禁用的用户才能被删除。
- 在继续操作之前，请确保所有需要保留的必要数据（如知识库和文件）已转移给其他用户。
- 此操作将永久删除以下用户数据
用户创建的所有知识库、上传的文件、配置的智能体，以及用户在他人知识库中上传的文件都将被永久删除。此操作不可逆，请极其谨慎操作。
- 删除命令具有幂等性。如果在删除过程中系统发生故障或操作中断，可以在排除故障后重新执行该命令以继续删除剩余数据。
使用示例
- 用户成功删除
admin> drop user "example@ragflow.io";
Drop user: example@ragflow.io
Successfully deleted user. Details:
Start to delete owned tenant.
- Deleted 2 tenant-LLM records.
- Deleted 0 langfuse records.
- Deleted 1 tenant.
- Deleted 1 user-tenant records.
- Deleted 1 user.
Delete done!
响应表明用户已成功删除，并列出了数据清理的详细步骤。
- 删除超级管理员（禁止操作）
admin> drop user "admin@ragflow.io";
Drop user: admin@ragflow.io
Fail to drop user, code: -1, message: Can't delete the super user.
响应表明删除失败。超级管理员账户受到保护，即使处于禁用状态也无法删除。
数据与 Agent 管理命令
LIST DATASETS OF <username>;
- 列出指定用户的所有知识库
<username>: 用户邮箱地址
使用示例
admin> list datasets of "lynn_inf@hotmail.com";
Listing all datasets of user: lynn_inf@hotmail.com
+-----------+-------------------------------+---------+----------+-----------------+------------+--------+-----------+-------------------------------+
| chunk_num | create_date | doc_num | language | name | permission | status | token_num | update_date |
+-----------+-------------------------------+---------+----------+-----------------+------------+--------+-----------+-------------------------------+
| 8 | Mon, 13 Oct 2025 15:56:43 GMT | 1 | English | primary_dataset | me | 1 | 3296 | Mon, 13 Oct 2025 15:57:54 GMT |
+-----------+-------------------------------+---------+----------+-----------------+------------+--------+-----------+-------------------------------+
响应显示该用户有一个私有知识库，文档和分段数量等详细信息如上表所示。
LIST AGENTS OF <username>;
- 列出指定用户的所有智能体
<username>: 用户邮箱地址
使用示例
admin> list agents of "lynn_inf@hotmail.com";
Listing all agents of user: lynn_inf@hotmail.com
+-----------------+-------------+------------+----------------+
| canvas_category | canvas_type | permission | title |
+-----------------+-------------+------------+----------------+
| agent_canvas | None | me | finance_helper |
+-----------------+-------------+------------+----------------+
响应表明该用户有一个私有智能体，详细信息如上表所示。
其他命令
- ? 或 \help
显示帮助信息。
- \q 或 \quit
后续计划
我们始终致力于提升系统管理体验和整体安全性。在现有强大功能的基础上，RAGFlow 后端管理工具将持续演进。除了当前高效灵活的命令行界面外，我们即将推出专业的系统管理 UI，使管理员能够在一个更安全、更直观的图形化环境中执行所有运维任务。
为了加强权限控制，当前在普通用户界面中可见的系统状态信息将被撤销。未来专业的管理 UI 上线后，系统核心运行状态的访问权限将仅限于管理员。这将有效解决当前权限暴露过多的问题，进一步加固系统的安全边界。
此外，我们还将陆续推出更多精细化的管理功能，包括
- 对数据集和智能体的精细化控制
- 用户团队协作管理机制
- 增强的系统监控和审计能力
这些改进将建立一个更全面的企业级管理生态系统，为管理员提供更全方位、更便捷的系统控制体验。