RuoYi AI 完全教程:企业级 AI 助手平台的部署、模型配置与功能详解
企业想落地一个自己的 AI 助手平台,通常要同时解决几件事:多个大模型厂商的账号与密钥要统一管理、公司文档要做成能问答的知识库、业务流程要能和 AI 串起来、用户权限与审计还要跟得上。自己从零拼凑这些模块,工作量不小。RuoYi AI 就是冲着这个场景来的:它基于国内 Java 圈非常熟悉的若依(RuoYi-Vue-Plus)企业级开发框架,把模型管理、知识库 RAG、工作流编排、多智能体这些 AI 能力做成开箱即用的全栈平台,MIT 协议开源(GitHub 约 5.8k Star),官方还提供在线演示与完整中文文档(doc.ruoyiai.chat)。
本文按「功能与架构 → 环境要求 → Docker 部署 → 模型配置 → 核心功能使用 → 注意事项」的顺序,把 RuoYi AI 的部署与使用完整走一遍,部署命令均为官方 README 原文。
一、功能与架构总览
RuoYi AI 官方定位是「企业级 AI 助手平台」,核心能力由五大模块构成:
- 模型管理:多模型统一接入(DeepSeek、智谱、MIMO、百炼、OpenAI 等),支持多模态理解;还能集成 Coze、Dify、FastGPT、RAGFlow 等外部 AI 平台。官方文档补充:模型管理统一管理 OpenAI、DeepSeek、通义千问、智谱、Ollama 及自定义 OpenAI-compatible API 等多厂商模型
- 知识管理:本地 RAG + 向量数据库(Milvus / Weaviate / Qdrant)+ 文档解析,覆盖文档解析、知识分块、向量化、向量库操作、召回、重排与混合检索的完整 RAG 链路
- 工具管理:集成 MCP 协议、Skills 技能能力与可扩展工具生态;文档站细分为 Function Calling、内置工具、本地 MCP、远程 MCP 与工具市场
- 流程编排:可视化工作流设计器,拖拽节点编排,SSE 流式执行;目前已支持模型调用、邮件发送、人工审核等节点,文档站还列出知识检索、条件分支、HTTP、网络搜索、图片生成等流程节点
- 智能体管理:基于 LangChain4j 的 Agent 框架,支持 Supervisor(监督者)模式编排与多种决策模型,可灵活搭配工具与 Skills;文档站举例可编排网页搜索、SQL、图表、ECharts、闲聊等角色,智能体可预检索知识库并绑定 MCP
此外官方文档站还单列了多模态接口(图片、语音、视频与预测接口的 Provider 路由)、上下文管理(系统提示词、会话历史与知识片段的组装)等模块。项目采用多仓库形态:后端服务(ruoyi-ai 本仓库)、用户前端(ruoyi-web)、管理后台(ruoyi-admin)、短剧平台(ruoyi-drama)、编程助手(ruoyi-copilot)、小程序端(ruoyi-uniapp),在 GitHub、Gitee、GitCode 三个平台同步发布。官方提供三个在线演示环境:用户端(web.ruoyiai.chat)、短剧演示与编程演示,均支持扫码登录体验。
技术栈
- 后端:Spring Boot 3.5.8 + LangChain4j(Java 生态的 LLM 应用框架),底座是 RuoYi-Vue-Plus
- 数据存储:MySQL 8.0 + Redis + 向量数据库(Milvus / Weaviate / Qdrant)
- 前端:Vue 3 + Vben Admin + element-plus-x
- 安全认证:Sa-Token + JWT 双重保障,继承若依的权限体系
- 文档处理:PDF、Word、Excel 解析与图像智能分析
- 实时通信:WebSocket 实时通信 + SSE 流式响应(对话打字机效果、工作流流式执行都走 SSE)
- 系统监控:完善的日志体系、性能监控与服务健康检查
二、环境要求
官方推荐 Docker 部署,对宿主机的要求很简单:
- Docker Engine(Linux / macOS)或 Docker Desktop(Windows)
- Docker Compose V2
一键部署会同时拉起后端、管理端、用户端以及 MySQL、Redis、Weaviate、MinIO 等依赖服务,向量库在一键包里默认使用 Weaviate(知识管理模块另支持 Milvus、Qdrant,按需在完整部署中选用)。也就是说,只要服务器能跑 Docker,就不需要预先安装 JDK、MySQL、Node 等一堆环境。源码构建方式(方式二)则需要分别构建后端、管理端与用户端三个仓库,具体环境要求以官方文档为准。
三、部署教程
方式一:一键启动全部服务(推荐)
使用仓库内的 docker-compose-all.yaml,拉取 GHCR 上的预构建镜像一次启动全部服务(镜像已公开,无需 docker login)。Linux / macOS 执行以下官方命令:
# 克隆 v3.1.0 版本
git clone --depth 1 --branch v3.1.0 https://github.com/ageerle/ruoyi-ai.git
cd ruoyi-ai
# 固定镜像版本。GHCR 镜像已公开,无需 docker login
cp docs/docker/ruoyi-ai/.env.example docs/docker/ruoyi-ai/.env
sed -i 's/^RUIYI_VERSION=.*/RUIYI_VERSION=v3.1.0/' docs/docker/ruoyi-ai/.env
# 从 GHCR 拉取预构建镜像并启动全部服务
docker compose --env-file docs/docker/ruoyi-ai/.env \
-f docs/docker/ruoyi-ai/docker-compose-all.yaml pull
docker compose --env-file docs/docker/ruoyi-ai/.env \
-f docs/docker/ruoyi-ai/docker-compose-all.yaml up -d
# 查看服务状态
docker compose --env-file docs/docker/ruoyi-ai/.env \
-f docs/docker/ruoyi-ai/docker-compose-all.yaml ps
# 访问服务(将 SERVER_IP 替换为服务器地址)
# 管理端: http://SERVER_IP:25666 (admin / admin123)
# 用户端: http://SERVER_IP:25137
# 后端API: http://SERVER_IP:26039
Windows + Docker Desktop 用户可用 PowerShell 执行等价命令(官方 README_ZH 中有完整版,主要是用 Copy-Item 创建 .env、用 -replace 固定 RUIYI_VERSION,compose 命令相同)。启动完成后,管理端默认账号为 admin / admin123,首次登录后应立即修改密码(见注意事项)。
方式二:分步部署(源码编译)
需要从源码构建(比如要改代码、二开)时,按后端 → 管理端 → 用户端的顺序分别部署三个仓库:
# 第一步:部署后端服务(进入 ruoyi-ai 目录)
cd ruoyi-ai
docker-compose up -d --build
docker-compose logs -f backend # 等待后端启动完成
# 第二步:部署管理端(进入 ruoyi-admin 目录)
cd ruoyi-admin
docker-compose up -d --build
# 访问管理端: http://localhost:5666
# 第三步:部署用户端(可选,进入 ruoyi-web 目录)
cd ruoyi-web
docker-compose up -d --build
# 访问用户端: http://localhost:5137
服务端口对照
- 管理端:一键部署 25666 / 分步部署 5666
- 用户端:一键部署 25137 / 分步部署 5137
- 后端服务:一键部署 26039 / 分步部署 6039
- MySQL:23306(两种方式相同)
- Redis:一键部署 26379 / 分步部署 6379
- Weaviate:28080(两种方式相同)
- MinIO:API 一键 29000 / 分步 9000;控制台一键 29090 / 分步 9090
升级方法
一键部署的升级很简单:修改 .env 中的 RUIYI_VERSION 为目标已发布版本,再用相同的 --env-file 与 -f 参数执行 pull 与 up -d 即可:
# 修改 docs/docker/ruoyi-ai/.env 中的 RUIYI_VERSION 后执行
docker compose --env-file docs/docker/ruoyi-ai/.env \
-f docs/docker/ruoyi-ai/docker-compose-all.yaml pull
docker compose --env-file docs/docker/ruoyi-ai/.env \
-f docs/docker/ruoyi-ai/docker-compose-all.yaml up -d
# 注意:除非确定要删除持久化数据卷,不要执行 docker compose down -v
四、模型配置
平台跑起来之后,第一件事是接模型。RuoYi AI 的模型与 API Key 在管理后台(ruoyi-admin)中统一配置,官方文档有专门的「在 ruoyi-admin 中配置模型和 API Key」一页,建议边看边配。配置思路概括如下:
- 添加模型厂商与凭据:在模型管理中接入 DeepSeek、智谱、通义千问(百炼)、OpenAI、Ollama 等厂商,填入各自的 API Key;本地 Ollama 与自定义 OpenAI-compatible API 也在支持之列,方便接内网模型服务或中转接口
- 多模态模型:模型管理支持多模态理解;文档站的多模态接口一节说明了图片、语音、视频与预测接口的 Provider 路由与调用方式(并注明当前普通聊天附件尚未接通的边界,接入前留意)
- 接入外部平台:如果团队已经在用 Dify、Coze、FastGPT、RAGFlow,可以通过平台集成把它们接进来统一门户。文档站说明:FastGPT、RAGFlow 及 OpenAI / Anthropic 兼容服务可按平台说明配置;Dify、Coze 提供适配代码,需补齐厂商选项与凭据支持,官方文档另有「本地开发接入 Dify 官方云服务」一页可供参考
- 给业务选用模型:模型接入后,即可在对话、知识库、工作流节点与智能体中选用,不同场景可以搭配不同模型(比如日常对话用便宜快速的模型,复杂推理换旗舰模型)
密钥集中托管在平台侧、按权限分配给用户使用,是这种企业级平台相对「每人自己配 Key」的核心优势:管理员统一采购与限额,使用者只面对功能入口。
五、核心功能使用
1. 智能对话与多模态
用户端是面向最终用户的对话入口,回复走 SSE 流式输出。模型管理支持多模态理解,文档站的多模态接口覆盖图片、语音、视频与预测接口的调用方式。上下文管理方面,文档站提到系统会组装系统提示词、会话历史与知识片段,并以「最近 20 条历史记忆」为例说明会话记忆的验证方式——长对话时它不是把全部历史无脑塞给模型,而是有明确的上下文组装策略。
2. 知识库与 RAG 问答
这是企业落地最常用的模块。把公司文档交给知识管理处理:文档解析(PDF、Word、Excel 等,含图像智能分析)→ 知识分块 → 向量化存入向量库(Milvus / Weaviate / Qdrant)→ 提问时召回相关片段 → 重排与混合检索提高精度 → 交给模型生成带依据的回答。相比直接把文档丢给通用聊天机器人,本地 RAG 的数据不出企业环境,且答案可溯源到原文片段,适合制度问答、产品手册、运维知识库等场景。
3. 可视化工作流编排
流程编排提供拖拽式设计器,把模型调用、知识检索、条件分支、邮件发送、HTTP 调用、网络搜索、图片生成、人工审核等节点串成流程,执行过程通过 SSE 流式呈现。典型用法是把「AI 生成 + 人工审核 + 邮件/接口分发」这类半自动业务流程固化下来:AI 负责起草,关键环节留人工审核节点把关,审核通过再自动执行后续动作。
4. 多智能体(Agent)
智能体管理基于 LangChain4j 的 Agent 框架,支持 Supervisor 模式:由一个监督者智能体统筹多个角色智能体(文档站举例包括网页搜索、SQL、图表、ECharts、闲聊等角色),并支持多种决策模型。每个智能体可以灵活搭配工具与 Skills、预检索知识库、绑定 MCP 服务,适合把「查数据 → 分析 → 出图表 → 写结论」这类多步骤任务交给一组智能体协作完成。
5. 工具、MCP 与技能
工具管理支持 Function Calling、内置工具、本地 MCP 与远程 MCP,并有工具市场;文档站的 MCP 管理一节从协议概念讲到 LOCAL、REMOTE 与魔搭 ModelScope 的实战。技能管理则负责 docx、pdf、xlsx 等技能资源的组织。这一层决定了平台的可扩展上限:标准化的外部系统走 MCP 接入,文档处理类能力走 Skills 沉淀。
六、注意事项
- 默认密码必须改:管理端初始账号 admin / admin123 是公开信息,上线后第一时间修改;官方特别提醒生产环境要修改 Compose 默认的 MySQL 与 MinIO 密码
- 端口暴露面:一键部署默认还会发布 MySQL(23306)、Redis(26379)、Weaviate(28080)、MinIO(29000/29090)端口,生产环境应通过防火墙或反向代理只开放应用端口(管理端、用户端、后端 API),数据库与存储端口不要直接暴露公网
- 版本固定:部署时用 RUIYI_VERSION 固定镜像版本,不要盲目跟 latest,升级前先看目标版本的发布说明
- 数据卷安全:不要随手执行 docker compose down -v,它会删除持久化数据卷;升级走 pull + up -d 的滚动方式
- 多仓库版本配套:分步部署时后端、管理端、用户端是独立仓库,注意三者版本配套,别混用跨度过大的版本
- 平台集成边界:Dify、Coze 目前是「提供适配代码、需补齐厂商选项与凭据」的集成深度,与 FastGPT、RAGFlow 的现成配置程度不同,选型时先按官方文档确认
七、适用人群与小结
RuoYi AI 最适合三类团队:一是已经在用若依/Java 技术栈的企业开发团队,权限、用户、组织这些底座能力现成,二开成本低;二是想把知识库问答、工作流、智能体统一到一个自有平台的中小企业与部门,避免数据散落在多个 SaaS 里;三是需要私有化部署、对数据出境敏感的场景,Docker 一键部署加上本地 RAG 与 Ollama 接入,可以做到全链路内网运行。
它的边界也要清楚:这是若依生态里的全栈重型平台,个人玩家只是想和 AI 聊天的话并不需要它;真正价值在企业场景的「统一模型管理 + 私有知识库 + 流程与智能体编排 + 权限底座」这一整套。如果你正打算给团队搭一个能长期演进的 AI 平台底座,RuoYi AI 值得用一台测试机按本文的一键部署先跑起来,花半天把模型配置与知识库链路验一遍,再决定是否投入二开。







