从智能问答到 AI Agent：基于 Spring Boot + RAG 的智能安装助手实践

前言

这篇文章复盘一个我从 0 到 1 实现的 Java + AI 应用项目：智能安装助手。

它最初只是一个能够导入安装文档、回答问题、识别简单安装指令的 MVP。随着后续迭代，我把它逐步升级成了一个更完整的 AI 应用闭环：

• 通过 RAG 检索安装知识；
• 通过 Agent Router 区分“知识问答”和“安装操作”；
• 通过受控执行平台执行服务启动、停止、扩缩容等任务；
• 通过异步任务、日志、审计和资源模型记录整个操作过程；
• 通过登录鉴权、确认令牌、权限策略和目标校验做安全收口。

最终它不再只是一个“调用大模型的聊天页面”，而是一个以 Spring Boot 为核心、结合 RAG 和 Agent 思路的智能安装执行平台原型。

项目背景

企业级软件安装和部署通常存在几个问题：

1. 安装文档分散，排查问题时需要反复翻文档；
2. 安装步骤复杂，容易遗漏前置条件；
3. 运维操作风险高，不能让 AI 直接执行危险命令；
4. 操作过程缺少统一的任务、日志和审计记录；
5. 如果只是普通 FAQ，无法真正进入业务闭环。

所以这个项目的目标不是做一个简单问答机器人，而是尝试回答一个问题：

能不能让 AI 既能理解安装知识，又能在受控、安全、可审计的前提下执行安装操作？

围绕这个目标，我把项目拆成几个阶段推进。

技术栈

后端：

• Java
• Spring Boot
• Maven
• JDBC
• H2
• Milvus SDK

前端：

• React
• TypeScript
• Vite

AI / RAG：

• 文档切分
• Embedding 抽象
• Memory VectorStore
• Milvus VectorStore
• DashScope Embedding
• DashScope Chat Model

执行平台：

• PowerShell 本地脚本
• Docker
• Docker Compose

安全与工程化：

• Token 登录鉴权
• 角色权限控制
• 确认令牌
• 异步任务
• 审计日志
• Smoke Test
• 一键启动脚本

整体架构

项目整体分为前端工作台、后端 API、RAG 链路、Agent Router、安装执行平台和审计资源系统。

`

用户在前端输入内容后，后端不会直接把所有内容都丢给大模型，而是先经过 Agent Router 判断：

• 如果是知识问题，进入 RAG；
• 如果是安装操作，进入安装执行平台；
• 如果操作需要确认，则生成确认令牌和等待确认任务；
• 如果权限不足或目标非法，则拒绝并写入审计。

第一阶段：从 MVP 到真实 RAG

MVP 阶段我先实现了最小闭环：

• 导入安装知识文档；
• 文档切片；
• 本地 hashing embedding；
• 内存向量库检索；
• Chat API 返回回答；
• Agent Router 识别安装操作；
• 前端可视化展示知识、聊天和执行结果。

这个阶段的 RAG 主要是为了证明产品闭环，所以使用的是：

• HashingEmbeddingModel
• InMemoryVectorStore

优点是无外部依赖、启动快、测试方便。缺点也很明显：数据重启后丢失，而且不是真正意义上的生产级向量检索。

后续升级目标就是把它做成真实 RAG 链路。

VectorStore 抽象

为了让内存向量库和 Milvus 可以无缝切换，我抽象了统一接口：

public interface VectorStore {
    void addAll(List<DocumentChunk> chunks);

    List<DocumentChunk> search(String query, int limit);

    List<DocumentChunk> allChunks();

    int count();
}

这个抽象带来的好处是：上层的 KnowledgeService 不需要关心底层到底是内存、Milvus，还是未来其他向量数据库。

接入 Milvus

真实 RAG 阶段新增了：

• MilvusVectorStore implements VectorStore
• MilvusGateway
• MilvusSdkGateway
• MilvusVectorRecord
• VectorStoreConfiguration
• VectorStoreProperties

同时使用 Docker Compose 在本地启动 Milvus：

services:
  milvus-standalone:
    image: milvusdb/milvus:v2.6.1

最终 RAG 链路变成：

文档导入
  -> 文档切片
  -> Embedding
  -> 写入 Milvus
  -> 相似度检索
  -> 返回 citations
  -> LLM 基于上下文生成回答

Embedding 维度一致性

这里遇到一个很典型的问题：

• 本地 hashing embedding 是 128 维；
• DashScope text-embedding-v3 是 1024 维；
• Milvus collection 一旦按某个维度创建，就不能直接混用另一个维度。

如果不提前处理，问题会在写入 Milvus 时才暴露，排查成本较高。

所以我在启动阶段增加了维度校验：

Milvus vector dimensions must match embedding dimensions

并且约定：

hashing + Milvus: 128
DashScope + Milvus: 1024

这一步让真实 RAG 切换更稳定。

第二阶段：接入真实 LLM

RAG 不只是检索 chunks，还需要让模型基于检索结果生成自然语言回答。

因此我又抽象了 ChatModel：

ChatModel
├── TemplateChatModel
└── DashScopeChatModel

默认使用 template 模式，这样没有 API Key 时也能本地运行和测试；当配置为 DashScope 后，知识问答会走真实 LLM。

这样系统可以在两种模式之间切换：

本地演示模式：
template chat + hashing embedding + memory vector store

真实 RAG 模式：
DashScope chat + DashScope embedding + Milvus

这个设计对个人项目很重要：既能降低本地启动门槛，又能证明项目具备真实 AI 应用能力。

第三阶段：Agent Router 区分问答和操作

如果所有用户输入都直接交给大模型，会有一个问题：用户可能输入的是操作指令，而不是知识问题。

例如：

start user-service
create partition orders
create cluster test-cluster

这类输入不能只生成一段文本回答，而应该进入安装执行流程。

因此我实现了 Agent Router：

用户输入
  -> Agent Router
      -> KNOWLEDGE_QA
      -> INSTALL_OPERATION

知识问题进入 RAG；安装操作进入 InstallToolService。

这个设计让项目从“问答系统”变成了“Agent 应用”，因为它不仅能回答，还能选择工具并驱动业务流程。

第四阶段：受控安装执行平台

安装执行平台是项目最重要的业务闭环。

它支持几类操作：

• 启动服务；
• 停止服务；
• 扩缩容服务；
• 创建/删除分区；
• 创建/销毁集群。

执行器也逐步从模拟升级为多种 provider：

simulated
script
docker
compose

为什么不能直接执行？

安装类操作有风险，不能让 AI 识别到一句话就直接执行。

所以操作会先生成执行计划：

InstallCommand
  -> InstallPlan
  -> confirmation token
  -> task
  -> executor

如果需要确认，第一次请求只会创建 WAITING_CONFIRMATION 任务，并返回确认令牌。

例如：

start user-service

系统返回类似：

START_SERVICE:user-service

用户再次携带正确 token 后，任务才会真正执行。

第五阶段：异步任务、日志、审计和回滚

为了让操作可追踪，我没有把执行结果只放在聊天回复里，而是设计了任务系统。

任务状态包括：

WAITING_CONFIRMATION
RUNNING
SUCCEEDED
FAILED
CANCELED
REJECTED

同时每个操作都会写入：

• task；
• task logs；
• audit logs；
• resource state。

任务能力包括：

• 取消；
• 重试；
• 回滚；
• 查看日志；
• 查看审计记录。

回滚不是偷偷改状态，而是创建新的可审计任务。

例如：

START_SERVICE rollback -> STOP_SERVICE
CREATE_PARTITION rollback -> DELETE_PARTITION
CREATE_CLUSTER rollback -> DESTROY_CLUSTER

这让系统更接近真实运维平台，而不只是一个 Demo。

第六阶段：真实资源模型

执行结果如果只留在任务日志里，后续很难查看当前系统状态。

因此我补充了三类资源模型：

• install_service_resource
• install_partition_resource
• install_cluster_resource

对应前端资源面板：

• Services
• Partitions
• Clusters

这样服务启动、扩缩容、分区创建、集群创建等操作，最终都会沉淀为可查询的资源状态。

这一步的意义是：AI 执行结果从“聊天消息”变成了“业务数据”。

第七阶段：安全收口

AI + 执行系统必须重视安全边界。

我主要做了几类收口。

1. Token 绑定真实角色

早期如果前端可以提交：

{
  "operator": "admin",
  "role": "ADMIN"
}

那权限控制就没有意义。

所以我改成后端登录发 token，后端根据 token 解析真实用户和角色。即使前端伪造 role=ADMIN，后端也不会信任。

默认用户：

viewer / viewer123
operator / operator123
admin / admin123

2. 确认令牌

高风险或本地执行操作需要二次确认。

没有正确 confirmation token，只能生成等待确认任务，不能真正执行。

3. 目标名称校验

增加 allow/deny/protected target pattern：

assistant.install.authorization.allowed-target-pattern=[\w\-\u4e00-\u9fa5]{1,128}
assistant.install.authorization.protected-target-pattern=(?i).*(prod|production|critical).*

这样可以限制目标名称，避免误操作生产环境或非法目标。

4. Active Task Guard

同一个 action + target 如果已有运行中任务，新请求会被拒绝，避免重复点击、重复提交导致并发操作。

第八阶段：一键启动和演示材料

为了让项目可演示、可交付、可给朋友测试，我补充了：

• start-local.bat
• start-local-milvus.bat
• stop-local.bat
• scripts/dev-start.ps1
• scripts/demo-flow.ps1
• docs/demo/demo-install-guide.md
• docs/demo/demo-service-catalog.md
• docs/demo/demo-runbook.md
• docs/project-resume-materials.md
• docs/architecture.md

启动命令示例：

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/dev-start.ps1

启动并导入演示文档：

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/dev-start.ps1 -SeedDemo

一个完整演示流程

本地启动后，打开：

http://localhost:5173

登录：

admin / admin123

导入演示文档后，可以先问一个知识问题：

What should be prepared before installing MySQL?

然后执行安装操作：

start demo-user-service

第一次请求会生成等待确认任务。

再次携带确认令牌：

START_SERVICE:demo-user-service

任务执行成功后，可以在前端查看：

• 任务列表；
• 执行日志；
• 审计记录；
• 服务资源状态。

再继续执行：

create partition demo-orders
create cluster demo-cluster

就可以看到分区和集群资源状态。

项目中遇到的几个问题

1. Windows / Docker / WSL 环境问题

接入 Milvus 时，需要 Docker Desktop 和 WSL 正常工作。

过程中遇到过：

• Docker Desktop engine starting 时间过长；
• WSL 版本过旧；
• Hypervisor 未启用；
• Docker Hub 拉取镜像超时；
• hosts 或 DNS 配置影响 GitHub / Docker Hub 访问。

最后通过启用 Windows 功能、更新 WSL、修复 hosts/DNS、配置 Docker registry mirror 等方式解决。

这部分虽然不属于业务代码，但对本地 AI 基础设施落地很关键。

2. PowerShell 中文编码

项目中多次遇到 PowerShell 中文乱码问题，尤其是：

• 中文 JSON 请求；
• 中文脚本文件名；
• 中文正则；
• 中文日志显示。

处理方式包括：

• 自动化测试尽量使用英文指令；
• 补充 ASCII 文件名的一键启动脚本；
• 核心拒绝原因使用稳定英文；
• 文档和展示层保留中文说明。

3. Milvus 写入后统计不一致

曾经出现文档写入后，搜索能查到，但状态接口的 chunk count 显示不一致。

后续通过：

• VectorStore.count()；
• Milvus collection stats；
• 写入后 flush；
• 状态接口独立统计；

逐步让状态显示更可靠。

4. AI 操作权限边界

最初操作请求里带有 operator 和 role 字段，但这存在明显风险：前端可以伪造管理员身份。

最终改成：

• 前端登录；
• 后端发 token；
• 后端根据 token 绑定真实角色；
• Controller 覆盖请求中的 operator/role；
• 安装策略只信任后端身份。

这是项目从 Demo 走向可用系统的重要一步。

测试和验证

项目中补充了多层验证：

后端测试：

cd backend
mvn test

前端构建：

cd frontend
npm run build

Smoke Test：

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/smoke-test.tests.ps1

真实执行 smoke：

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/smoke-test.ps1 -ExecutorProvider script

这些验证覆盖了 RAG、安装操作、任务状态、权限控制、资源状态和前端构建等核心路径。

这个项目对简历的价值

如果把它写进简历，我会这样定位：

基于 Spring Boot + React 构建智能安装助手，结合 RAG、Agent Router 和受控执行平台，实现安装知识问答、服务操作、异步任务、审计日志和资源状态管理。系统支持 DashScope + Milvus 的真实 RAG 模式，也支持本地无云依赖演示模式，并通过 Token 权限、确认令牌、目标校验和回滚机制保障操作安全。

它的亮点不在于“调用了大模型 API”，而在于把 AI 能力嵌入到了一个完整业务系统里：

• 有知识库；
• 有检索；
• 有路由；
• 有工具执行；
• 有权限；
• 有任务；
• 有审计；
• 有资源状态；
• 有本地演示和测试。

这比单纯做一个聊天页面更能体现 Java 后端和 AI 应用落地能力。

总结

这个项目从最初的 MVP，一步步升级成了一个较完整的 Java + AI 应用原型。

它经历了几个关键阶段：

1. 完成最小可运行 MVP；
2. 把内存 RAG 升级为 DashScope + Milvus 的真实 RAG；
3. 用 Agent Router 区分知识问答和安装操作；
4. 构建受控安装执行平台；
5. 增加异步任务、日志、审计、回滚；
6. 补齐服务、分区、集群资源模型；
7. 做登录鉴权和安全收口；
8. 补齐一键启动、演示数据和项目材料。

对我来说，这个项目最大的收获是：

AI 应用不是简单地把用户问题发给大模型，而是要把模型能力、业务流程、权限边界、执行系统和工程化验证结合起来。

这也是我认为它适合作为 Java 后端 + AI 应用方向项目经历的原因。