RuoYi AI

这是什么？适合谁？

RuoYi AI（https://github.com/ageerle/ruoyi-ai，5.7k+ Stars、1.4k+ Forks，MIT 协议，2024 年 1 月启动）是若依（RuoYi）生态下的一款开箱即用的企业级全栈 AI 助手平台。它把「AI 能力」长进了若依这套在国内 Java 企业开发里极有群众基础的快速开发框架里，让团队能用熟悉的 Spring Boot + Vue 技术栈，快速搭出一个带多 Agent 协作、知识库 RAG、可视化工作流编排的 AI 应用，而不是从零拼装。

技术栈非常「企业级」：后端 Spring Boot 3.5.8 + Langchain4j，存储 MySQL 8.0 + Redis + 向量库（Milvus/Weaviate/Qdrant），前端 Vue 3 + Vben Admin + element-plus-x，安全层 Sa-Token + JWT 双保险。它主打五块能力：多模型管理（统一接入 DeepSeek/智谱/MIMO/百炼/OpenAI，并兼容 Coze/DIFY/FastGPT/RAGFlow 平台）、知识库管理（本地 RAG + 向量库 + PDF/Word/Excel 解析）、工具管理（MCP 协议 + Skills）、可视化工作流编排（拖拽节点 + SSE 流式）、多 Agent 框架（Langchain4j + Supervisor 模式编排）。

横向对比：跟 Dify 相比，RuoYi AI 的价值不在「最强大的 LLMOps 编排」，而在**「企业级工程底座 + 若依权限/组织/租户体系」**——Dify 是通用 LLM 应用平台，RuoYi AI 是给已有 Java 团队、要跟现有业务系统打通的 AI 平台；跟 FastGPT、MaxKB 比，它的知识库和 Agent 是「集成在完整后台框架里」，而非独立产品；跟 Coze 这类 SaaS 比，它完全私有化部署、数据不出内网。缺点是上手门槛高于纯 SaaS，且工作流节点类型还比较有限（当前支持模型调用、邮件、人工审核等）。

适合人群：有 Java/Vue 技术栈的企业研发团队；需要在私有化环境（内网/等保）部署 AI 能力的政企项目；已经在用若依做后台、想给系统加 AI 助手的团队；需要把 Agent 跟现有 RBAC 权限、组织架构、审批流打通的中台团队。

不适合人群：非技术背景、只想快速做 Prompt 对话的个人（用 Coze / Dify 云版更省事）；纯粹要做超复杂 LLM 编排、需要海量节点类型的团队（用 Dify 或 LangChain 生态更灵活）；不想维护 MySQL/Redis/向量库等一堆中间件的轻量场景。

准备工作

1. 运行环境：Docker Engine + Docker Compose V2（推荐一键部署方式），服务器建议 4C8G 起步（要跑向量库 + 后端 + 双前端）。本地方案也可源码构建（需 JDK、Node、MySQL 8.0、Redis）。
2. 账号与成本：平台本身 MIT 免费、私有化部署。真实成本来自你要接的大模型 API：DeepSeek 按 token 计费（deepseek-chat 约 $0.27/百万输入、$1.10/百万输出，以官网为准）；智谱 ChatGLM 新用户有免费额度；阿里云百炼（通义千问）新用户送免费 token；OpenAI API 按量计费；火山引擎 有 Coding Plan 优惠。向量库 Milvus/Weaviate/Qdrant、MySQL、Redis 均可免费自托管。
3. 部署命令（推荐一键启动，固定 v3.1.0 稳定版）：

   git clone --depth 1 --branch v3.1.0 https://github.com/ageerle/ruoyi-ai.git
   cd ruoyi-ai
   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
   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
   

4. 前置知识：懂 Spring Boot + Vue 基础、MySQL/Redis 运维常识；会用 Docker；理解 RAG 和 Agent 的基本概念。不要求精通 Langchain4j（框架已封装好）。
5. 替代方案：当不想自托管时，Dify（开源 LLMOps，也有云版）、FastGPT、MaxKB（知识库问答）、Coze（SaaS Agent）都是退路；但想要「若依权限体系 + 私有化 + Java 生态」三者兼具，RuoYi AI 是更贴合的选择。

4 步核心流程

第 1 步：一键 Docker 部署

执行上面的 docker compose 命令后，公共 GHCR 镜像免登录拉取，一条命令同时拉起后端、管理后台、用户前台以及 MySQL、Redis、Weaviate、MinIO 全部依赖。启动完成后检查状态：

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。也可以直接体验官方线上 Demo（地址见参考链接，账号 admin/admin123）。

预期产出：浏览器打开管理后台能登录，看到模型管理、知识库、工作流、Agent 等完整菜单——一个可用的 AI 中台骨架已经跑起来了。

第 2 步：配置多模型与知识库

登录后台后，先接模型：在「模型管理」里配置 DeepSeek / 智谱 / MIMO / 百炼 / OpenAI 任一家（或多家的 API Key），也可以反向接入 Coze/DIFY/FastGPT/RAGFlow 平台作为模型来源。接着搭知识库：选一个向量库（Milvus / Weaviate / Qdrant 三选一），上传 PDF/Word/Excel 文档，框架会自动解析、切片、向量化。

可复制的验证 Prompt（在对话里测模型和知识库是否打通）：

基于我上传的《XX 项目技术方案》文档，用三句话总结核心架构，并说明它和标准微服务架构的差异。

预期产出：对话能正确引用你上传的文档内容回答（RAG 命中），说明模型 + 向量库 + 文档解析整条链路已通。

第 3 步：定义 Agent 与可视化工作流编排

在「Agent」模块用 Langchain4j 定义 Agent 角色和能力，选择决策模型；多 Agent 场景用 Supervisor 模式编排——一个监督者 Agent 根据意图把任务分派给不同子 Agent，再由子 Agent 组合调用工具和 Skills（MCP 协议接入）。复杂流程用「工作流」模块的拖拽设计器编排：拉节点、连线，配置模型调用、邮件发送、人工审核等节点，SSE 流式输出执行结果。

可复制的编排思路（定义一个「客服工单分类 + 自动回复」工作流）：

节点1：模型调用（对用户消息做意图分类）
节点2：条件分支（投诉 → 走人工审核节点；咨询 → 走知识库 RAG 回答）
节点3：邮件发送（把投诉工单摘要发给对应负责人）

预期产出：一个可被前端调用、能端到端跑通的 Agent 应用或工作流，执行过程以 SSE 流式返回，可在界面看到每步产出。

第 4 步：部署上线与生产加固

上线前必须做三件事：改默认密码（MySQL、MinIO 的默认密码务必改掉，admin 账号密码也要改）；收敛端口——只通过防火墙或反向代理暴露应用端口（25666/25137），不要直接把 MySQL(23306)、Redis(26379)、MinIO(29000/29090) 暴露到公网；升级路径——后续升级只改 .env 里的 RUIYI_VERSION 再 docker compose pull && up -d，不要用 docker compose down -v（会删持久化数据卷）。

预期产出：一个安全配置到位、可通过反向代理域名访问、具备完整权限体系的私有化 AI 平台。

常见踩坑（6 条）

踩坑 1：docker compose 起不来 / 端口冲突

• 症状：up -d 后部分容器反复重启
• 原因：默认映射的端口（25666/25137/26039/23306 等）与宿主机已有服务冲突，或内存不足
• 解决：检查 docker compose ps 看退出容器日志；改映射端口；确认服务器内存足够（向量库较吃内存）

踩坑 2：登录后台但对话报模型错误

• 症状：界面正常，一发消息就报 4xx/5xx
• 原因：模型 API Key 未配、Key 失效或模型名写错
• 解决：在「模型管理」逐个验证 Key，确认模型标识与所选 provider 一致（如 deepseek-chat、glm-4 等）

踩坑 3：知识库问答答非所问 / 引不到文档

• 症状：上传了文档，回答却是模型自由发挥
• 原因：文档没成功向量化，或向量库未正确连接，或切片参数不合理
• 解决：确认向量库健康、文档解析状态成功；对长文档调切片大小；用第 2 步的验证 Prompt 复测命中

踩坑 4：工作流执行一半中断

• 症状：多节点流程跑到某节点停住
• 原因：单节点调用超时，或人工审核节点没人处理
• 解决：给模型节点设合理超时与重试；人工审核节点配好审批人和通知，避免流程卡在「等人」上

踩坑 5：升级后数据丢失

• 症状：升级版本后数据库空、之前数据没了
• 原因：误用了 docker compose down -v（-v 会删除数据卷）
• 解决：升级只用 pull + up -d，绝不加 -v；备份 MySQL/MinIO 数据卷

踩坑 6：多 Agent 行为失控、成本爆表

• 症状：Supervisor 模式 token 消耗异常高、结果不稳定
• 原因：给每个子 Agent 都配了最贵模型、没设温度与最大步数
• 解决：简单子 Agent 用便宜模型（如 DeepSeek），设置 temperature 与迭代上限，确定性步骤尽量用工作流节点而非 Agent

常见问题 FAQ

Q1：RuoYi AI 免费吗？能商用吗？ A：MIT 协议，完全免费、可商用、可二开。实际成本来自自托管服务器 + 你接入的大模型 API。来源：GitHub 仓库 与 官方文档。

Q2：它和 Dify、FastGPT 有什么区别？ A：Dify 是通用 LLMOps 平台、编排能力更全；FastGPT/MaxKB 聚焦知识库问答；RuoYi AI 的核心差异是**「若依生态 + Java 全栈 + 完整权限/组织体系 + 私有化」**，适合要跟现有 Java 业务系统、RBAC 权限打通的团队。已有若依项目时它几乎是零学习成本的 AI 化升级路径。

Q3：必须要 Docker 吗？能不能源码部署？ A：可以源码部署。官方提供「逐模块构建」方案：后端 cd ruoyi-ai && docker-compose up -d --build、管理后台 cd ruoyi-admin、用户前台 cd ruoyi-web，各自独立端口（5666/5137/6039）。但一键 docker-compose-all.yaml 最省事，推荐优先。

Q4：支持哪些模型和国产模型？ A：DeepSeek、智谱 GLM、MIMO、阿里云百炼（通义千问）、OpenAI 均可直接接入，还支持把 Coze / Dify / FastGPT / RAGFlow 平台作为模型来源接入；多模态理解也支持。具体列表以官方文档的「模型管理」页为准。

Q5：小团队 / 低预算怎么控制成本？ A：模型层全用 DeepSeek 或 智谱 免费额度；向量库选轻量的 Qdrant 单节点；部署用最小规格（4C8G）跑 Docker；用工作流节点代替昂贵的多 Agent 循环。平台本身零授权费，成本几乎就是模型 API 的钱。

参考链接

• RuoYi AI GitHub 仓库
• 官方文档
• 线上 Demo（商业版）
• 子项目：用户前台 ruoyi-web

---

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。