28 个 Java 模块 + 5 个独立部署 App，4C8G 单机全链路架构拆解
一、架构总览
Dream-SaaS 是一个双语言微服务架构的 AI Agent 平台。Java 负责业务逻辑与 API 治理，Python 负责 AI 编排与重计算，整体分为 6 层：
二、技术栈与版本
2.1 Java 侧
| 技术 | 版本 | 说明 |
|---|---|---|
| JDK | 21 | 全模块统一 |
| Spring Boot | 3.5.5 | 核心框架 |
| Spring Cloud | 2025.0.0 | Northfields，对齐 Boot 3.5 |
| Spring Cloud Alibaba | 2025.0.0.0 | Nacos 注册配置中心 |
| Spring AI | 1.1.6 | AI 能力抽象（ChatClient / Advisor / Tool Calling / VectorStore） |
| Spring AI Alibaba | 1.1.2.2 | 通义 DashScope 集成 + Graph 编排 + ReactAgent + MCP |
| MyBatis-Plus | 3.5.14 | ORM |
| Redisson | 3.40.2 | 分布式锁与缓存 |
| springdoc-openapi | 2.8.16 | API 文档 |
| java-jwt | 4.4.0 | JWT 令牌 |
| RocketMQ Spring Boot | 2.3.1 | 消息队列 |
| Apache POI | 5.4.0 | Office 文件处理 |
| Fastjson2 | 2.0.61 | JSON 序列化 |
| Hutool | 5.8.43 | 工具集 |
| PostgreSQL JDBC | 42.7.3 | 数据库驱动 |
| MySQL Connector/J | 8.0.33 | 数据库驱动 |
2.2 Python 侧
| 技术 | 版本 | 说明 |
|---|---|---|
| Python | 3.10+ | 编排层运行时 |
| FastAPI | 0.115.0 | 异步 Web 框架，原生 SSE 流式支持 |
| LangGraph | 0.2.0 | 图编排引擎（对应 Java 侧 Spring AI Alibaba Graph） |
| LiteLLM | 1.55.0 | 统一 LLM 调用，一个接口切换 100+ 模型 |
| OpenAI SDK | 1.55.0 | DashScope 兼容模式直连 |
| instructor | 1.7.0 | LLM 结构化输出（自动反序列化到 Pydantic Model） |
| Pydantic Settings | 2.6.0 | 配置管理（.env + 环境变量自动映射） |
| MCP SDK | 1.2.0 | Model Context Protocol（stdio 工具进程） |
2.3 前端
| 技术 | 版本 | 说明 |
|---|---|---|
| Vue | 3.5.13 | 渐进式前端框架 |
| Element Plus | 2.9.4 | UI 组件库 |
| Vite | 6.0.7 | 构建工具 |
| SPA 单页应用 | — | 所有前端均采用 SPA 模式 |
2.4 基础设施
| 组件 | 用途 |
|---|---|
| PostgreSQL + pgvector | 向量存储与检索 |
| Redis | 缓存、会话、分布式锁 |
| MySQL | 业务数据持久化 |
| RocketMQ | 异步事件通知（如内容任务生命周期） |
| Nginx | HTTPS 终端 + 静态资源 + 反向代理 |
2.5 选型决策
| 决策 | 原因 |
|---|---|
| Spring Cloud 2025.0 | 与 Boot 3.5 同代，配套 Nacos 实现服务注册与配置管理 |
| Spring AI + Alibaba | 原生 Spring 生态的 AI 抽象层，DashScope 直通通义模型 |
| FastAPI + LangGraph | Python 侧高性能 Web 框架 + 成熟的图编排能力 |
| pgvector | 复用 PostgreSQL，不额外引入向量数据库，降低运维成本 |
| 单机 4C8G | 先跑通全链路验证架构，再按需横向扩展 |
2.6 Java / Python 分工原则
双语言不是重复造轮子，而是各取所长：
| 放在 Java | 放在 Python |
|---|---|
| API 网关、鉴权、配额管控 | LLM Tool Calling 深循环 |
| 数据库 CRUD、事务管理 | Web 搜索、网页爬取 |
| 向量 Schema 管理、RAG 检索 | Prompt 快速迭代与编排 |
| Graph 声明式编排（复杂分支 / HITL） | 内容 Pipeline、定时批处理 |
| MCP Server 聚合暴露 | MCP stdio 工具进程 |
| Feign 服务间调用 | 多模型 A/B 测试（LiteLLM） |
三、前端架构
前端采用 Vue3 + Vite 构建，共有 4 个独立前端应用，全部由 Nginx 托管静态资源：
| 前端应用 | 路由路径 | 说明 |
|---|---|---|
| 主站 | / | 项目主入口 |
| companion SPA | /companion/ | AI 搭子交互界面 |
| study-admin | /study-admin/ | 学习助手管理后台 |
| content-admin | /content-admin/ | 内容管理后台 |
Nginx 同时承担 HTTPS 终端（Let's Encrypt 证书）、HTTP→HTTPS 重定向、安全响应头（HSTS / X-Content-Type-Options / X-Frame-Options）以及静态资源服务。API 请求通过 Nginx 反向代理分发到后端各服务。
四、网关层
采用 Nginx + Java Gateway 双层网关设计：
- Nginx：HTTPS 终端、静态资源托管、反向代理路由分发
- Java Gateway（
dream-ai-gateway，:8090）：统一鉴权、限流、配额管控，以及通过 Feign 调用后端服务
Nginx 按 URL 路径前缀将请求路由到不同后端服务，未匹配的请求兜底到 Gateway 统一接管。
五、业务层
5.1 五个独立部署的 Java App
| 服务 | 端口 | 职责 |
|---|---|---|
dream-ai-gateway | 8090 | API 网关 + Agent 对话入口 |
dream-ai-code-review | 8095 | 代码审查 Agent |
dream-ai-rag | 8096 | RAG 向量检索服务 |
dream-ai-agent-content | 8097 | 内容管理（Content OS） |
dream-ai-agent-companion | 8098 | AI 搭子 + 学习助手 Java 侧 |
五个 App 生命周期独立，可分别启停、独立扩缩容。其中 agent-study（学习助手）Java 侧模块编译时嵌入 agent-companion App 中，不单独部署，其核心 AI 编排逻辑在 Python 侧（:8001）执行。
5.2 电商业务域 Agent（dream-ai-agent-business）
| 业务域 | 职责 |
|---|---|
fulfillment | 履约 Agent（订单、物流、退款、售后） |
seller | 卖家服务 Agent |
ticketmgmt | 工单管理 Agent |
每个业务域遵循统一的 Java 包结构规范：graph（图编排节点定义）→ integration/feign（外部服务调用）→ service（业务逻辑）→ web（REST API 入口）→ trace（链路追踪埋点）。这是模块内的目录分层约定，确保各业务域代码结构一致、可维护。
六、Agent 核心层（Java）
6.1 核心模块与 Spring AI 能力
| 模块 | 职责 |
|---|---|
dream-ai-agent-core | Agent 框架核心（基类、生命周期、工具注册） |
dream-ai-agent-runtime | Agent 运行时管理 |
dream-ai-agent-chat | 对话管理与会话记忆 |
dream-ai-agent-skills | 技能与工具注册中心 |
dream-ai-agent-platform | 平台管理（用户、配额、系统配置） |
核心层基于 Spring AI 1.1.6 构建，关键能力：
- ChatClient：高层 Fluent API，封装 LLM 调用全流程（Advisor 链 → Tool 自动循环 → 结构化输出），日常开发首选入口
- Advisor 拦截器链：类似 Spring MVC Filter，在 LLM 调用前后插入逻辑。内置
QuestionAnswerAdvisor（RAG 检索注入）、MessageChatMemoryAdvisor（会话记忆）、SafeGuardAdvisor（安全过滤）等，支持自定义扩展 - Tool Calling：通过
@Tool/@ToolParam注解声明工具，ChatClient 自动完成 ReAct 循环（Think → 选 Tool → 执行 → Observe → 循环至最终回答） - ChatModel 装饰器：生产环境多层包装，如
InstrumentingTraceChatModel（Trace 追踪）→RecoveryInstrumentingChatModel（自愈重试）→ 基础模型
6.2 AI Agent 能力模块
| 模块 | 职责 |
|---|---|
dream-ai-agent-content | 内容创作 Agent |
dream-ai-agent-companion | AI 搭子 Agent |
dream-ai-agent-study | 学习助手 Agent |
dream-ai-agent-bi | BI 数据分析 Agent |
dream-ai-agent-business | 电商业务域 Agent |
dream-ai-agent-bug | 缺陷管理 Agent |
dream-ai-agent-memory | 记忆管理 Agent |
dream-ai-agent-repo | 仓库管理 Agent |
dream-ai-agent-tech | 技术文档 Agent |
dream-ai-agent-ragdoc | RAG 文档处理 |
dream-ai-agent-userhelp | 用户帮助 Agent |
6.3 图编排（Spring AI Alibaba Graph）
| 模块 | 职责 |
|---|---|
dream-ai-graph | 图编排引擎，作为共享库被 Gateway 和各业务 App 依赖，负责 Agent 节点编排与状态流转。不是独立部署的服务，而是嵌入到调用方的类库 |
dream-ai-graph 基于 Spring AI Alibaba 的 Graph 引擎构建，核心概念：
- StateGraph（声明式图定义）→ CompiledGraph（编译后可执行），支持三种边类型：顺序边、并行边（
CompletableFuture.allOf并发执行）、条件边（路由函数动态分支） - OverAllState：全局状态黑板，各节点读写共享状态
- CheckpointSaver（基于 Redisson）：状态持久化，支持 HITL（Human-in-the-loop）——图执行到人工审核节点时暂停，审核通过后携带
threadId从中断点恢复 - Supervisor 多子图模式：意图路由节点将请求分发到不同子图（如通用对话子图、代码审查子图、RAG 问答子图），子图可作为节点嵌入主图
- SSE 流式协议：
run.start → node.end → message.delta → message.done，前端可实时展示执行进度与 LLM 增量输出
此外，Spring AI Alibaba 还提供 ReactAgent（ReAct 模式：Think → Tool → Observe 循环）和 多 Agent 编排（SequentialAgent / ParallelAgent / RoutingAgent），用于更复杂的 Agent 协作场景。
6.4 MCP 模块（5 子模块）
| 子模块 | 职责 |
|---|---|
dream-saas-mcp-client | MCP 客户端，调用外部 MCP 服务 |
dream-saas-mcp-common | MCP 公共定义 |
dream-saas-mcp-registry | MCP 服务注册中心 |
dream-saas-mcp-server | MCP 服务端，暴露工具给外部 |
dream-saas-mcp-spi | MCP SPI 扩展点 |
6.5 跨语言协作模式
Java 与 Python 两层之间通过四种模式协作：
| 模式 | 说明 | 典型场景 |
|---|---|---|
| HTTP REST | Python httpx → Java Internal API | 会话读写、数据持久化 |
| SSE 直通 | Nginx → Python 流式响应 | 搭子/学习助手的实时对话 |
| 共享数据库 | Java/Python 各读写自己的 Schema | 向量数据、业务表 |
| 消息队列 | RocketMQ 事件通知 | 内容任务生命周期、异步解耦 |
Python 侧通过 core/nacos_integration.py 接入 Nacos 注册中心，与 Java 侧共享服务发现，实现统一的服务治理。
七、Java 模块全景（28 个模块）
28 个模块按职责分为 8 个分类，明细如下：
| 分类 | 模块名 | 小计 |
|---|---|---|
| 基础设施 | dream-ai-common | 1 |
| Agent 核心 | agent-core、agent-runtime、agent-chat、agent-skills、agent-platform | 5 |
| 业务域 Agent | agent-content、agent-companion、agent-study、agent-bi、agent-business、agent-bug、agent-memory、agent-repo、agent-tech、agent-ragdoc、agent-userhelp | 11 |
| 图编排 | dream-ai-graph | 1 |
| 独立服务 | gateway、code-review、rag、test | 4 |
| MCP 协议栈（5） | mcp-client、mcp-common、mcp-registry、mcp-server、mcp-spi（详见 6.4 节） | 5 |
| 前端 | dream-ai-content-admin | 1 |
| Python 桥接 | dream-ai-python（Java 侧 Python 进程的配置入口与启动管理） | 1 |
| 合计 | 28 |
补充说明： 另有根工程
dream-saas下的dream-saas-core、dream-saas-gateway、dream-saas-edge、dream-saas-common、dream-saas-cache、dream-saas-message等业务基座模块，提供跨项目的公共能力（缓存、消息、通用实体等）。这些基座模块属于平台底座，未计入上述 28 个 AI 业务模块。上表中
test模块为运维守护进程，部署方式详见第八节。
八、部署拓扑（4C8G 单机）
关于
dream-ai-test：该模块作为运维守护进程常驻，由 Systemd 管理，负责每 10 分钟健康检查和异常自动拉起。不暴露 API 端口，不参与业务请求，因此不在上述 5 个业务 App 之列。
公网域名：www.dream-saas.com，已备案，HTTPS + HTTP/2。
九、关键设计决策
| 决策 | 原因 |
|---|---|
| 5 个独立 App 部署 | Gateway / CodeReview / RAG / Content / Companion 生命周期独立，互不影响 |
| Nginx 直路由 + Gateway 兜底 | 性能敏感路径直达后端，其余走 Gateway 统一治理 |
| MCP 完整协议栈 | 5 个子模块分层设计（详见 6.4 节），Java 侧聚合暴露、Python 侧 stdio 进程，通过标准协议互通 |
| 跨语言四种协作模式 | HTTP REST / SSE 直通 / 共享数据库 / RocketMQ，按场景选用而非一刀切 |
| RocketMQ 异步解耦 | 内容任务通过消息队列异步通知，避免同步调用阻塞 |
| pgvector 而非独立向量库 | 复用 PostgreSQL，降低运维复杂度 |
| 4C8G 单机部署 | 成本优先，验证架构可行性后再横向扩展 |
| Gateway 不依赖业务 App | 网关只依赖 dream-ai-agent-platform（平台管理模块，负责用户鉴权、配额等），不依赖 content / companion / study 等业务 App，保证网关与业务解耦 |
十、小结
Dream-SaaS 的架构设计体现了几个核心思路：
- 分层清晰、各司其职：前端 → 网关 → 业务 → Agent 核心 → Python 编排 → 基础设施，6 层边界明确
- 5 个独立 App 解耦：Gateway / CodeReview / RAG / Content / Companion 生命周期独立，可分别启停
- MCP 协议栈分层：5 个子模块覆盖完整链路，对外暴露工具、对内注册服务
- 网关轻、业务重：Nginx + Gateway 只做鉴权限流路由，不碰业务逻辑
- 单机先行、成本可控：4C8G 跑通全链路，验证后再扩展
项目地址：dream-saas.com
系列文章：Agent 实战 #01
技术栈：Spring Boot 3.5.5 + Spring Cloud 2025.0 + Spring Cloud Alibaba 2025.0.0.0 + Spring AI 1.1.6 + Spring AI Alibaba 1.1.2.2 + FastAPI + LangGraph + PostgreSQL/pgvector
📎 附：配套资料
本文涉及的技术栈版本对照、Spring AI 核心接口用法、Graph 编排代码示例、Python 编排层速查、Java↔Python 语法对照表等内容，我整理了一份 《Agent 开发技术栈扩展参考手册》，覆盖从 Spring Cloud 微服务到 Python AI 编排栈的完整知识链路。
获取方式：关注作者，私信"Agent手册"即可获取。
适合正在从传统 Java 后端转型 Agent 开发的同学，拿来对照着用，少走弯路。
有问题评论区见，欢迎交流~
