若依AI学习第11天：重回 3.0 源码，环境落地与模块全景

隔了一段时间没碰 RuoYi-AI，重新拉代码发现已经到 3.0，之前记的笔记还是 2.x 的东西，模块划分和技术栈都对不上了。这一篇重新出发：把版本对齐、把环境搭起来、把全局看清楚。

一、版本变了哪些

最核心的就三点：Spring Boot 升级到 3.5.8、Java 17、LangChain4j 到 1.13.0，另外引入了 LangChain4j-Agentic、LangGraph4j 和 Warm-Flow。

至于和 2.x 对不上的地方，翻旧资料时直接跳过：ruoyi-modules-api、ruoyi-knowledge-api 已删除（知识库合入 ruoyi-chat），ruoyi-graph（知识图谱）、ruoyi-aihuman（数字人）已移出，代码中无有效引用。

二、当前模块全景

这是这次重新学习的"地图"，先记住它，后面每学一块都能往上挂。

ruoyi-ai (3.0.0)├── ruoyi-admin                    # 启动入口 + skills 资源目录├── ruoyi-common (25 个模块)        # 基础设施│   ├── core / web / json / doc    # 基础工具│   ├── mybatis / redis / oss      # 数据层│   ├── satoken / security / tenant / sensitive  # 安全多租户│   ├── chat / sse / websocket     # AI 通信层（chat 是 AI 抽象）│   ├── idempotent / ratelimiter / log / translation / encrypt  # 工程能力│   └── excel / mail / sms / social / job  # 外围集成├── ruoyi-modules (5 个)│   ├── ruoyi-chat                 # 学习主战场（对话 + RAG + Agent + MCP + 可观测性）│   ├── ruoyi-aiflow               # AI 工作流引擎（基于 LangGraph4j）│   ├── ruoyi-workflow             # Warm-Flow 审批流（业务流，与 AI 无关）│   ├── ruoyi-system               # 系统管理│   └── ruoyi-generator            # 代码生成└── ruoyi-extend (2 个)    ├── ruoyi-monitor-admin        # Spring Boot Admin 监控    └── ruoyi-snailjob-server      # SnailJob 分布式任务调度

两个容易搞混的地方

ruoyi-aiflow 不等于 ruoyi-workflow。 名字像，但完全无关：前者是 AI 流程编排（底层 LangGraph4j），后者是审批流引擎（底层 Warm-Flow 1.8.2，做请假报销这类业务审批）。

ruoyi-common-chat 不等于 ruoyi-modules/ruoyi-chat。 前者是公共 AI 抽象层（接口 + DTO + 实体），被多个模块共用；后者才是业务实现，RAG、Agent、MCP 的落地代码都在这。

三、环境怎么搭

一句话建议：本地源码 + Docker 只跑中间件。

理由很简单：Docker 部署的后端是编译好的镜像，改代码不生效，也没法断点调试、看实时日志。学源码就得让源码直接跑在 IDE 里，前端用 pnpm dev 热更新。Docker 只负责起 MySQL、Redis 这类"装了就忘"的基础设施。

最少要起哪些中间件

这是最容易踩的坑。答案取决于学到哪一步：

所以最小集就两个：MySQL + Redis。

向量库三选一，靠一行配置切换。项目默认配的是 Milvus，但它比较重（要带 etcd、minio、standalone、attu 四个容器，镜像约 1.2 GB）。相比之下 Weaviate 是单容器，如果 Docker 里已经有现成的，可以直接复用。

具体操作三步走

Step 1 · 起中间件

最小集 MySQL + Redis，学 RAG 时加向量库。可以用项目自带的 compose 文件（在 docs/docker/ruoyi-ai/ 目录下 docker compose up -d mysql redis weaviate），也可以用已有的本地容器。起的时候记下映射的 host 端口。

Step 2 · 改数据源

打开 ruoyi-admin/src/main/resources/application-dev.yml，把 MySQL 和 Redis 的地址指向刚起的容器，端口与 Step 1 记下的 host 端口一致。

Step 3 · 起源码（两个项目）

四、扫盲：Weaviate 和 MinIO 到底是什么

搭环境时看着一堆中间件，最让人困惑的是"这俩是干嘛的"。简单说一下。

Weaviate：向量数据库

存知识库文档切分后的 embedding 向量。用户提问时，把问题也转成向量，去里面找"语义最相似"的片段，拼进上下文 —— 这就是 RAG 的检索环节。

项目用策略模式管理了三种向量库，靠配置切换：

三者检索评分口径不同，项目用 L2 归一化统一到 [0,1] 区间 —— 这是能随意切换向量库的前提。

值得一提的是，RAG 只在请求带 knowledgeId 时才触发，所以不启向量库，普通对话完全不受影响。

MinIO：对象存储

走 S3 兼容协议，存上传的文件：知识库原始文档、聊天图片附件等。同一套代码能对接阿里云、腾讯云、七牛等。

它的配置方式比较特别：不写在 yml 里，而是存在数据库表 sys_oss_config，可以在管理后台动态切换。

要注意的是，默认类型不是启动时读表的 status 字段，而是应用启动时由 SysOssConfigServiceImpl.init() 把 status='0' 的那条写进 Redis。所以改了表之后必须重启应用才生效 —— 这个机制值得记住，不然改了配置不生效会以为哪里出了问题。

结尾

这一篇做的事其实很简单：把版本对齐了、把模块看全了、把环境搭对了。

这三件事看着基础，但直接决定后面读源码顺不顺 —— 不会再卡在"这个类在哪个模块"、"这个配置为什么没生效"、"这个项目到底有几种部署方式"这类问题上。

下一篇开始进主线，从 ChatServiceFacade 这个对话链路的入口看起。它是整个项目里最关键的一个类，读懂它之后，RAG、Agent、MCP 这些挂在它周边的东西就都好理解了。

如果这个系列对你有帮助，欢迎关注，我们下一篇见。