SuperBizAgent 系统架构设计

目录

1. 系统概述
2. 架构设计原则
3. 系统整体架构
4. 详细组件架构
5. 核心模块设计
6. 数据流设计
7. API 接口架构
8. 部署架构

---

1. 系统概述

1.1 项目定位

SuperBizAgent 是基于 Spring Boot + AI Agent 的企业级智能问答与运维系统，集成 RAG（检索增强生成）知识库与 AIOps（智能运维）能力，为企业提供智能化的业务咨询与自动化运维服务。

1.2 核心能力

能力模块	能力描述	技术实现
RAG 智能问答	基于向量检索的智能问答	Milvus + DashScope + 多轮对话
AIOps 智能运维	自动化告警分析与报告生成	多 Agent 协作 + Planner-Executor 模式
工具集成	文档检索、指标查询、日志分析	MCP + Spring AI Tool
流式输出	实时响应与进度展示	SSE (Server-Sent Events)

1.3 系统特性

本系统具备三大核心特性模块，每个模块由多个子功能组成，共同支撑 SuperBizAgent 的智能化服务能力。以下思维导图展示了系统的完整功能架构：

mindmaproot((SuperBizAgent))RAG 智能问答向量检索Milvus 向量库Top-K 相似度匹配文档处理文本分块向量化嵌入多轮对话上下文记忆历史窗口管理AIOps 智能运维多 Agent 协作Supervisor 编排Planner 规划Executor 执行告警分析根因识别故障自愈报告生成Markdown 模板SSE 流式输出企业级特性高可用部署水平扩展安全认证

核心功能说明：

功能模块	子功能	功能描述
RAG 智能问答	向量检索	基于 Milvus 向量数据库实现语义相似度匹配，通过 Top-K 算法返回最相关的文档片段
	文档处理	支持 TXT/MD 格式文档，采用 800 字符分块策略和 100 字符重叠窗口，确保语义连贯性
	多轮对话	维护会话上下文历史，采用滑动窗口机制（MAX_WINDOW=6）管理对话历史，平衡内存占用与上下文完整性
AIOps 智能运维	多 Agent 协作	采用 Supervisor-Planner-Executor 三层 Agent 架构，实现任务的智能分解与协作执行
	告警分析	自动接收 Prometheus 告警，通过多轮推理识别根因，支持故障自愈建议生成
	报告生成	基于 Markdown 模板生成结构化运维报告，支持 SSE 流式输出实时展示分析进度
企业级特性	高可用部署	支持多实例集群部署，配合负载均衡实现高可用架构
	水平扩展	无状态应用设计，支持根据负载动态扩缩容
	安全认证	集成企业级身份认证与授权机制，确保系统安全

---

2. 架构设计原则

2.1 设计原则

本系统遵循面向对象设计的四大基本原则，这些原则指导我们构建高内聚、低耦合的系统架构。以下流程图展示了各设计原则的核心要点：

graph LRsubgraph 架构设计原则direction TBP1["🎯 单一职责<br/>每个模块专注单一功能"]P2["🔓 开闭原则<br/>对扩展开放，对修改封闭"]P3["📦 依赖倒置<br/>依赖抽象而非具体实现"]P4["🔗 接口隔离<br/>使用专用接口而非通用接口"]endstyle P1 fill:#dae8fc,stroke:#6c8ebfstyle P2 fill:#fff2cc,stroke:#d6b656style P3 fill:#ffe6cc,stroke:#d79b00style P4 fill:#d5e8d4,stroke:#82b366

设计原则详解：

原则	英文名称	应用实践	收益
单一职责原则	Single Responsibility Principle	Controller 负责请求路由，Service 处理业务逻辑，Agent 负责智能决策，各层职责边界清晰	降低类之间的耦合度，提高代码可读性和可维护性，便于独立测试和修改
开闭原则	Open-Closed Principle	通过 MCP 协议扩展工具能力，基于策略模式实现不同的 Agent 协作方式	新增功能只需扩展而非修改现有代码，降低回归风险
依赖倒置原则	Dependency Inversion Principle	Service 层依赖抽象的 Tool 接口，ChatService 通过接口调用工具而非具体实现	便于单元测试时使用 Mock 对象，提高系统的灵活性和可测试性
接口隔离原则	Interface Segregation Principle	将大型接口拆分为专用的 DateTimeTools、InternalDocsTools、QueryMetricsTools 等小型接口	客户端只需依赖其需要的方法，减少不必要的依赖，提高代码的稳定性

2.2 架构分层

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#dae8fc'}}}%% graph TBsubgraph L1["L1 用户交互层"]L1_UI["🌐 Web 前端界面<br/>提供可视化交互界面"]L1_API["📡 REST API<br/>提供编程接口"]endsubgraph L2["L2 应用接入层"]L2_CTRL["🎮 Controller 层<br/>请求路由、参数校验"]endsubgraph L3["L3 业务服务层"]L3_SVC["📋 Service 层<br/>业务逻辑编排"]endsubgraph L4["L4 AI 框架层"]L4_AI["🤖 AI Agent 框架<br/>智能推理与决策"]endsubgraph L5["L5 工具服务层"]L5_TOOL["🔧 Tool 层<br/>领域能力封装"]endsubgraph L6["L6 数据存储层"]L6_DATA["💾 存储层<br/>向量库与文档库"]endsubgraph L7["L7 外部服务层"]L7_EXT["☁️ 外部服务<br/>LLM 与 MCP"]endL1_UI --> L1_APIL1_API --> L2_CTRLL2_CTRL --> L3_SVCL3_SVC --> L4_AIL4_AI --> L5_TOOLL5_TOOL --> L6_DATAL5_TOOL --> L7_EXTstyle L1 fill:#dae8fc,stroke:#6c8ebfstyle L2 fill:#fff2cc,stroke:#d6b656style L3 fill:#ffe6cc,stroke:#d79b00style L4 fill:#e1d5e7,stroke:#9673a6style L5 fill:#d5e8d4,stroke:#82b366style L6 fill:#f8cecc,stroke:#b85450style L7 fill:#f3e5f5,stroke:#9c27b0

七层架构详解：

层级	名称	核心职责	关键组件	依赖关系
L1	用户交互层	提供用户接入渠道，处理前端请求与响应	Web 前端界面、REST API	被访问层，无依赖
L2	应用接入层	请求路由、参数校验、流量控制、安全认证	Controller 层	依赖 L3 服务层
L3	业务服务层	业务逻辑编排、流程控制、事务管理	Service 层	依赖 L4 AI 框架层
L4	AI 框架层	智能推理、多 Agent 协作、决策生成	Spring AI Agent 框架	依赖 L5 工具层、L7 外部服务
L5	工具服务层	领域能力封装、第三方服务调用	Tool 层（DateTimeTools、QueryMetricsTools 等）	依赖 L6 数据存储层、L7 外部服务
L6	数据存储层	结构化与非结构化数据持久化	Milvus 向量库、文档库	被依赖层，无依赖
L7	外部服务层	第三方 AI 能力集成、MCP 协议支持	DashScope LLM、MCP Server	被依赖层，无依赖

分层设计优势：

1. 关注点分离：每层只关注自身职责，降低系统复杂度，便于理解和维护
2. 独立演进：各层可以独立升级替换，不影响其他层（如更换 LLM 提供商不影响业务逻辑）
3. 便于测试：每层可以独立进行单元测试，上层可对下层进行 Mock
4. 团队协作：不同团队可以并行开发不同层级，提高开发效率
5. 性能优化：可针对特定层级进行性能调优，如缓存、连接池等

---

3. 系统整体架构

3.1 核心架构图

以下架构图展示了 SuperBizAgent 系统的完整组件布局和模块间的交互关系。系统采用分层架构设计，从上到下依次为用户层、应用层、服务层、AI Agent 层、工具层、数据层和外部服务层。各层之间通过标准接口进行通信，确保系统的松耦合和可扩展性。

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#dae8fc'}}}%% graph TB%% 用户层subgraph USER["👤 用户层"]WEB["🌐 Web 前端<br/>index.html + app.js"]API["📡 REST API<br/>curl / SDK"]end%% 应用层subgraph APP["⚙️ 应用层 (Spring Boot 3.2.0)"]CHAT_CTL["📨 ChatController<br/>统一接口控制器"]FILE_CTL["📤 FileUploadController<br/>文件上传控制器"]MILVUS_CTL["💚 MilvusCheckController<br/>健康检查控制器"]end%% 服务层subgraph SERVICE["📋 服务层"]CHAT_SVC["💬 ChatService<br/>对话服务"]AIOPS_SVC["🔧 AiOpsService<br/>AIOps 服务"]RAG_SVC["📚 RagService<br/>RAG 服务"]DOC_SVC["✂️ DocumentChunkService<br/>文档分块"]VEC_EMBED["🔢 VectorEmbeddingService<br/>向量嵌入"]VEC_SEARCH["🔍 VectorSearchService<br/>向量检索"]VEC_IDX["📊 VectorIndexService<br/>向量索引"]end%% AI Agent 层subgraph AGENT["🤖 AI Agent 层 (Spring AI)"]SUPER["🎭 SupervisorAgent<br/>多 Agent 控制器"]PLANNER["📝 PlannerAgent<br/>规划 Agent"]EXECUTOR["⚡ ExecutorAgent<br/>执行 Agent"]REACT["🔄 ReactAgent<br/>反应式 Agent"]end%% 工具层subgraph TOOL["🔧 工具层"]DT["🕐 DateTimeTools<br/>时间工具"]DOC_TOOL["📄 InternalDocsTools<br/>文档检索"]MET_TOOL["📊 QueryMetricsTools<br/>指标查询"]LOG_TOOL["📜 QueryLogsTools<br/>日志查询"]end%% 数据层subgraph DATA["💾 数据层"]MILVUS["🗃️ Milvus 2.6.10<br/>向量数据库"]DOCS["📁 aiops-docs<br/>运维文档库"]end%% 外部服务subgraph EXTERNAL["☁️ 外部服务"]DASHSCOPE["🧠 DashScope<br/>阿里云 LLM"]MCP["🔌 MCP Server<br/>腾讯云日志服务"]end%% 连接关系WEB & API --> CHAT_CTLCHAT_CTL --> FILE_CTL & MILVUS_CTLCHAT_CTL --> CHAT_SVC & AIOPS_SVCCHAT_SVC --> REACTAIOPS_SVC --> SUPERREACT & SUPER --> PLANNER & EXECUTORREACT & SUPER --> DT & DOC_TOOL & MET_TOOL & LOG_TOOLCHAT_SVC & REACT & PLANNER & EXECUTOR --> DASHSCOPEREACT & SUPER -.-> MCPDOC_TOOL & RAG_SVC & VEC_EMBED & VEC_SEARCH & VEC_IDX --> MILVUSDOC_SVC & DOC_TOOL --> DOCS%% 样式classDef user fill:#dae8fc,stroke:#6c8ebf,stroke-width:2pxclassDef app fill:#fff2cc,stroke:#d6b656,stroke-width:2pxclassDef service fill:#ffe6cc,stroke:#d79b00,stroke-width:2pxclassDef agent fill:#e1d5e7,stroke:#9673a6,stroke-width:2pxclassDef tool fill:#d5e8d4,stroke:#82b366,stroke-width:2pxclassDef data fill:#f8cecc,stroke:#b85450,stroke-width:2pxclassDef external fill:#f3e5f5,stroke:#9c27b0,stroke-width:2pxclass USER,WEB,API userclass APP,CHAT_CTL,FILE_CTL,MILVUS_CTL appclass SERVICE,CHAT_SVC,AIOPS_SVC,RAG_SVC,DOC_SVC,VEC_EMBED,VEC_SEARCH,VEC_IDX serviceclass AGENT,SUPER,PLANNER,EXECUTOR,REACT agentclass TOOL,DT,DOC_TOOL,MET_TOOL,LOG_TOOL toolclass DATA,MILVUS,DOCS dataclass EXTERNAL,DASHSCOPE,MCP external

3.2 技术栈全景

技术栈全景图展示了系统的技术选型路径和能力映射关系。从底层开发语言到上层系统能力，形成了完整的技术支撑体系。以下图表清晰展示了技术栈的演进关系以及与系统能力的对应映射。

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#ffe6cc'}}}%% graph LRsubgraph TECH["技术栈"]direction TBJAVA["☕ Java 17<br/>开发语言"]SPRING["🌱 Spring Boot 3.2.0<br/>应用框架"]SPRING_AI["🤖 Spring AI 1.1.0<br/>AI Agent 框架"]DASHSCOPE["🧠 DashScope 2.17.0<br/>LLM 服务"]MILVUS["🗃️ Milvus 2.6.10<br/>向量数据库"]MCP["🔌 MCP Protocol<br/>模型上下文协议"]endsubgraph CAPABILITY["系统能力"]direction TBRAG["📚 RAG 智能问答<br/>向量检索 + LLM 生成"]AIOPS["🔧 AIOps 智能运维<br/>多 Agent 协作"]STREAM["📺 SSE 流式输出<br/>实时响应"]SESSION["💾 多轮会话管理<br/>上下文记忆"]endJAVA --> SPRINGSPRING --> SPRING_AISPRING_AI --> DASHSCOPESPRING_AI --> MCPSPRING --> MILVUSCAPABILITY --> RAG & AIOPS & STREAM & SESSION

技术栈详解：

技术组件	版本号	技术定位	核心价值	选型理由
Java	17 LTS	开发语言	企业级稳定选择	长期支持版本，成熟生态系统，适合高并发企业应用开发
Spring Boot	3.2.0	应用框架	快速开发与部署	生态完善starter支持，自动配置简化开发，内嵌服务器便于部署
Spring AI	1.1.0	AI Agent 框架	统一的 AI 集成能力	提供标准化的 Agent 抽象，支持多种 LLM 提供商，工具调用机制完善
DashScope	2.17.0	LLM 服务	强大的中文推理能力	阿里云千问系列模型，中文理解能力强，性价比高，国内合规
Milvus	2.6.10	向量数据库	高效向量检索	专门优化的向量检索性能，支持分布式部署，开源可私有化部署
MCP Protocol	最新版	模型上下文协议	标准化工具扩展	腾讯云日志服务集成协议，标准化接口便于扩展第三方服务

系统能力与技术支撑映射：

系统能力	依赖技术组件	实现方式	性能指标
RAG 智能问答	Milvus + DashScope	向量检索 + LLM 生成	top_k=3，chunk_size=800，overlap=100
AIOps 智能运维	Spring AI + DashScope	多 Agent 协作推理	支持 Planner-Executor 循环，MAX_WINDOW=6
SSE 流式输出	Spring Web + SSE	Server-Sent Events	支持实时流式响应，提升用户体验
多轮会话管理	Spring Session + ConcurrentHashMap	会话状态管理	线程安全的会话存储，支持历史窗口管理

技术架构优势：

1. 全栈 Java 技术栈：统一语言环境简化开发和运维，丰富的企业级库支持
2. Spring AI 抽象层：解耦 LLM 提供商，支持快速切换不同的 AI 模型
3. Milvus 向量引擎：专为向量检索优化，支持十亿级向量规模
4. MCP 协议扩展：标准化工具集成，快速接入第三方服务
5. 云原生就绪：支持 Docker 容器化部署，可集成 Kubernetes

---

4. 详细组件架构

4.1 Controller 层架构

Controller 层是系统的统一接入点，负责处理外部请求并进行路由分发。本层采用标准的 Spring MVC 模式，核心组件为 ChatController，它承担了对话交互、AIOps 分析和会话管理的全部职责。以下类图展示了 Controller 层的完整结构，包括核心类的方法签名、属性定义以及类之间的依赖关系。

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#fff2cc'}}}%% classDiagramdirection TBclass ChatController {-sessions: Map<String, SessionInfo>-MAX_WINDOW_SIZE: int = 6+chat(request: ChatRequest): ResponseEntity+chatStream(request: ChatRequest): SseEmitter+aiOps(): SseEmitter+clearChatHistory(request: ClearRequest): ResponseEntity+getSessionInfo(sessionId: String): ResponseEntity}class FileUploadController {+uploadFile(file: MultipartFile): ResponseEntity}class MilvusCheckController {+checkHealth(): ResponseEntity}class SessionInfo {-sessionId: String-messageHistory: List-createTime: long-lock: ReentrantLock+addMessage(userQuestion: String, aiAnswer: String): void+getHistory(): List+clearHistory(): void+getMessagePairCount(): int}class ChatRequest {-Id: String-Question: String}class ChatResponse {-success: boolean-answer: String-errorMessage: String+success(answer: String): ChatResponse+error(message: String): ChatResponse}class SseMessage {-type: String-data: String+content(data: String): SseMessage+error(message: String): SseMessage+done(): SseMessage}%% 接口说明（单独标注，更清晰）note for ChatController "POST /api/chat\nPOST /api/chat_stream\nPOST /api/ai_ops\nPOST /api/chat/clear\nGET /api/chat/session/{sessionId}"note for FileUploadController "POST /api/upload"note for MilvusCheckController "GET /milvus/health"%% 关系ChatController --> SessionInfoChatController --> ChatRequestChatController --> ChatResponseChatController --> SseMessage%% 功能说明note for ChatController "统一接口控制器\n负责请求路由、会话管理\nSSE 流式响应"

Controller 层核心组件说明：

组件类	类职责	核心方法	方法说明	请求路径
ChatController	统一对话接口控制器	chat()	处理普通对话请求，返回同步响应	POST /api/chat
		chatStream()	处理流式对话请求，返回 SSE Emitter 实现实时推送	POST /api/chat_stream
		aiOps()	启动 AIOps 智能分析流程，返回流式分析报告	POST /api/ai_ops
		clearChatHistory()	清空指定会话的历史记录	POST /api/chat/clear
		getSessionInfo()	获取会话的详细信息，包括历史消息数量	GET /api/chat/session/
FileUploadController	文件上传处理控制器	uploadFile()	接收并处理上传的文档文件，触发向量化和存储流程	POST /api/upload
MilvusCheckController	系统健康检查控制器	checkHealth()	检查 Milvus 连接状态，返回服务可用性信息	GET /milvus/health
SessionInfo	会话信息管理类	addMessage()	向会话添加用户问题和 AI 回答，维护历史记录	内部方法
		getHistory()	获取完整的对话历史记录	内部方法
		clearHistory()	清空会话的所有历史消息	内部方法
		getMessagePairCount()	获取当前会话的消息对数量，用于判断是否需要窗口清理	内部方法

会话管理机制详解：

ChatController 采用基于内存的会话管理方案，通过 ConcurrentHashMap 存储会话信息，使用 ReentrantLock 保证线程安全。以下是关键设计点：

1. 会话标识：每个会话通过唯一的 sessionId 标识，客户端需要在请求中携带此标识以维持会话上下文
2. 历史窗口管理：MAX_WINDOW_SIZE 设置为 6，当会话消息对数量超过此阈值时，自动清理最旧的两条消息对，保持内存占用稳定
3. 线程安全：使用 ReentrantLock 实现细粒度的会话访问控制，支持高并发场景下的安全访问
4. 消息格式：每条消息包含角色（user/assistant）和内容，支持多轮对话的上下文理解

4.2 Service 层架构

Service 层是业务逻辑的核心承载层，负责编排和处理各类业务请求。本层包含六个核心服务组件，分别承担对话服务、AIOps 分析服务、RAG 检索服务以及向量处理服务等职责。各服务之间通过依赖注入形成协作关系，共同支撑上层的 AI Agent 能力。以下类图展示了 Service 层的完整结构，包括核心方法签名和服务间的依赖关系。

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#ffe6cc'}}}%% classDiagramdirection TBclass ChatService {+createDashScopeApi(): DashScopeApi+createChatModel(api: DashScopeApi, temp: double, maxTok: int, topP: double): DashScopeChatModel+createStandardChatModel(api: DashScopeApi): DashScopeChatModel+buildSystemPrompt(history: List): String+buildMethodToolsArray(): Object[]+getToolCallbacks(): ToolCallback[]+logAvailableTools(): void+createReactAgent(model: DashScopeChatModel, prompt: String): ReactAgent+executeChat(agent: ReactAgent, question: String): String}class AiOpsService {+executeAiOpsAnalysis(model: DashScopeChatModel, callbacks: ToolCallback[]): Optional+extractFinalReport(state: OverAllState): Optional-buildPlannerAgent(model: DashScopeChatModel, callbacks: ToolCallback[]): ReactAgent-buildExecutorAgent(model: DashScopeChatModel, callbacks: ToolCallback[]): ReactAgent-buildMethodToolsArray(): Object[]-buildPlannerPrompt(): String-buildExecutorPrompt(): String-buildSupervisorSystemPrompt(): String}class RagService {+retrieveAndGenerate(question: String): String-searchRelevantDocuments(question: String): List-buildContext(docs: List): String-generateAnswer(context: String, question: String): String}class DocumentChunkService {+chunkDocument(text: String): List+chunkText(text: String, maxSize: int, overlap: int): List-shouldSplit(text: String, maxSize: int): boolean-splitBySentence(text: String): List}class VectorEmbeddingService {+embedText(text: String): float[]+embedDocuments(chunks: List): void-getEmbeddingFromDashScope(text: String): float[]}class VectorSearchService {+search(query: String, topK: int): List+searchByVector(vector: float[], topK: int): List-convertToMilvusVector(vector: float[]): FloatBuffer}class VectorIndexService {+createCollection(collectionName: String): void+createIndex(collectionName: String, fieldName: String): void+dropCollection(collectionName: String): void}ChatService --> AiOpsService : 共享 DashScopeChatService --> RagService : 对话使用 RAGRagService --> DocumentChunkService : 文档处理RagService --> VectorEmbeddingService : 向量化RagService --> VectorSearchService : 向量检索VectorEmbeddingService --> VectorIndexService : 创建索引

Service 层核心组件说明：

服务类	类职责	核心方法	方法功能	调用关系
ChatService	对话服务编排器	createDashScopeApi()	初始化 DashScope API 客户端，配置连接参数	被 Controller 调用
		createChatModel()	创建配置的 ChatModel 实例，设置温度、最大令牌数等参数	内部使用
		buildSystemPrompt()	构建系统提示词，整合历史对话上下文	内部使用
		buildMethodToolsArray()	构建可用的工具数组，供 Agent 调用	返回工具列表
		getToolCallbacks()	创建工具回调处理器，处理工具执行结果	返回 ToolCallback[]
		createReactAgent()	创建 ReactAgent 实例，配置模型和提示词	返回 Agent 实例
		executeChat()	执行对话，处理用户问题并返回回答	核心业务方法
AiOpsService	AIOps 分析服务	executeAiOpsAnalysis()	启动 AIOps 分析流程，协调多 Agent 协作	被 Controller 调用
		extractFinalReport()	从 OverAllState 中提取最终 Markdown 报告	内部使用
		buildPlannerAgent()	构建 PlannerAgent，负责任务规划分解	私有方法
		buildExecutorAgent()	构建 ExecutorAgent，负责指令执行反馈	私有方法
RagService	RAG 检索增强服务	retrieveAndGenerate()	核心 RAG 流程：检索相关文档并生成回答	对话服务调用
		searchRelevantDocuments()	在 Milvus 中搜索与问题相关的文档	私有方法
		buildContext()	将检索到的文档组装成上下文	私有方法
		generateAnswer()	调用 LLM 生成最终回答	私有方法
DocumentChunkService	文档分块服务	chunkDocument()	对整个文档进行分块处理	被上传流程调用
		chunkText()	核心分块方法，支持指定块大小和重叠长度	内部使用
		shouldSplit()	判断文本是否需要进一步分割	私有方法
		splitBySentence()	按句子边界进行智能分割	私有方法
VectorEmbeddingService	向量嵌入服务	embedText()	将单条文本转换为向量表示	被多个服务调用
		embedDocuments()	批量将文档块转换为向量	被上传流程调用
		getEmbeddingFromDashScope()	调用 DashScope API 获取文本嵌入	私有方法
VectorSearchService	向量检索服务	search()	根据文本问题进行向量检索	被 RagService 调用
		searchByVector()	根据向量进行相似度搜索	内部使用
		convertToMilvusVector()	将 float 数组转换为 Milvus 需要的格式	私有方法
VectorIndexService	向量索引服务	createCollection()	在 Milvus 中创建 Collection	被初始化流程调用
		createIndex()	为指定字段创建索引，优化检索性能	被初始化流程调用
		dropCollection()	删除指定的 Collection	管理功能

服务依赖关系说明：

Service 层各组件之间形成了清晰的依赖拓扑结构，这种分层设计确保了各服务的独立性和可测试性。从依赖关系图中可以看出，ChatService 处于服务编排的核心位置，它协调 RagService 和 AI Agent 的工作。RagService 则依赖底层的向量处理服务，形成了从业务到基础设施的完整调用链路。

4.3 AI Agent 架构

AI Agent 层是系统的核心智能决策引擎，采用多 Agent 协作架构实现复杂的推理和执行能力。本层包含四个核心 Agent 组件：SupervisorAgent 负责整体编排和流程控制，PlannerAgent 负责任务分析和步骤规划，ExecutorAgent 负责具体指令的执行和结果收集，ReactAgent 则承担通用对话的响应式推理。以下架构图展示了各 Agent 的内部结构和它们之间的协作关系。

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#e1d5e7'}}}%% graph TBsubgraph AGENT_FRAMEWORK["🤖 AI Agent 框架"]direction TBsubgraph SUPERVISOR["🎭 SupervisorAgent<br/>多 Agent 控制器"]S1["任务接收<br/>接收用户请求"]S2["Agent 调度<br/>决定调用 Planner 还是 Executor"]S3["状态管理<br/>维护 OverAllState"]S4["流程终止判断<br/>FINISH 条件检测"]endsubgraph PLANNER["📝 PlannerAgent<br/>规划器 / Replanner"]P1["任务分析<br/>理解输入任务"]P2["步骤规划<br/>生成执行步骤"]P3["决策输出<br/>PLAN | EXECUTE | FINISH"]P4["策略调整<br/>基于 Executor 反馈重新规划"]endsubgraph EXECUTOR["⚡ ExecutorAgent<br/>执行器"]E1["指令解析<br/>读取 Planner 指令"]E2["工具调用<br/>执行具体操作"]E3["证据收集<br/>汇总执行结果"]E4["反馈生成<br/>返回结构化反馈"]endendS1 --> S2S2 -->|"PLAN"| P1S2 -->|"EXECUTE"| E1P1 --> P2P2 --> P3P3 -->|"decision"| S2P3 -->|"PLANNER"| S2E1 --> E2E2 --> E3E3 --> E4E4 -->|"executor_feedback"| S2E4 -->|"feedback"| P4P4 --> P3style SUPERVISOR fill:#e1d5e7,stroke:#9673a6,stroke-width:3pxstyle PLANNER fill:#dae8fc,stroke:#6c8ebf,stroke-width:2pxstyle EXECUTOR fill:#d5e8d4,stroke:#82b366,stroke-width:2px

多 Agent 协作架构详解：

Agent 组件	核心职责	内部模块	模块功能	协作关系
SupervisorAgent	整体编排控制	任务接收	接收用户请求，初始化 OverAllState	调度中心，连接 Planner 和 Executor
		Agent 调度	根据决策决定调用 Planner 还是 Executor
		状态管理	维护 OverAllState，记录中间结果
		流程终止判断	检测 FINISH 条件，结束协作流程
PlannerAgent	任务规划分解	任务分析	理解输入任务，提取关键信息	向 Supervisor 提供决策，接收 Executor 反馈
		步骤规划	生成执行步骤列表
		决策输出	输出 PLAN/EXECUTE/FINISH 决策
		策略调整	基于 Executor 反馈重新规划
ExecutorAgent	指令执行反馈	指令解析	读取 Planner 生成的指令	向 Supervisor 提供执行反馈，向 Planner 提供重新规划依据
		工具调用	执行具体的工具操作
		证据收集	汇总工具返回结果
		反馈生成	返回结构化的 executor_feedback
ReactAgent	响应式推理	工具推理	链式思考推理，决定是否调用工具	独立使用于普通对话场景

Agent 协作决策流程：

多 Agent 协作的核心是基于状态的决策循环。SupervisorAgent 维护全局状态 OverAllState，通过循环调用 PlannerAgent 和 ExecutorAgent 实现复杂的任务分解与执行。每个循环包含以下决策分支：

1. Planner 决策分支：当 Planner 输出 PLAN 或 EXECUTE 时，Supervisor 将控制权交给相应的 Agent
2. Executor 执行分支：Executor 完成工具调用后，返回结构化反馈供 Planner 重新规划
3. 终止判断：当 Planner 输出 FINISH 时，Supervisor 生成最终报告并结束流程

ReAct 模式说明：

ReactAgent 采用 ReAct（Reasoning + Acting）模式实现通用对话能力。该模式的核心思想是将推理和行动紧密结合，通过多轮思考-行动-观察循环逐步逼近正确答案。每个循环包含三个阶段：Reasoning（思考下一步行动）、Acting（执行工具调用）、Observation（观察执行结果），直到达到目标或超时。

4.4 工具层架构

工具层是 AI Agent 与外部系统交互的桥梁，通过 @Tool 注解将各类领域能力封装为可被 Agent 调用的工具方法。本层包含四个核心工具组件：DateTimeTools 提供时间获取能力，InternalDocsTools 提供文档检索能力，QueryMetricsTools 提供指标查询能力，QueryLogsTools 提供日志查询能力。以下类图展示了工具层的完整结构，包括各个工具类的方法签名和功能说明。

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#d5e8d4'}}}%% classDiagramdirection TBclass DateTimeTools {+getCurrentDateTime(): String+getCurrentDate(): String+getCurrentTime(): String}class InternalDocsTools {+queryInternalDocs(query: String): List-searchKnowledgeBase(query: String): List-calculateRelevance(doc: Document, query: String): double}class QueryMetricsTools {+queryPrometheusAlerts(params: Map): List+getMetricValue(metricName: String): double+getMetricHistory(metricName: String, range: TimeRange): List}class QueryLogsTools {+queryLogs(params: Map): List+searchLogs(query: String, timeRange: TimeRange): List+getRecentLogs(service: String, count: int): List}class DropCollection {+dropCollection(collectionName: String): boolean}note for DateTimeTools "获取当前时间\n用于日志时间范围查询"note for InternalDocsTools "内部文档检索\n基于关键词匹配"note for QueryMetricsTools "Prometheus 指标查询<br/>告警指标获取"note for QueryLogsTools "日志查询<br/>支持 MCP 或 Mock 模式"

工具层核心组件说明：

工具类	工具用途	核心方法	方法说明	使用场景
DateTimeTools	时间获取工具	getCurrentDateTime()	获取当前完整的日期时间字符串	日志查询的时间范围设定、分析报告的时间戳
		getCurrentDate()	获取当前日期（年-月-日格式）	按日期统计、报表生成
		getCurrentTime()	获取当前时间（时:分:秒格式）	精确时间记录、性能分析
InternalDocsTools	内部文档检索工具	queryInternalDocs(query)	检索与查询词相关的内部文档	AIOps 分析、故障排除、知识问答
		searchKnowledgeBase()	在知识库中执行搜索（私有方法）	内部调用
		calculateRelevance()	计算文档与查询的相关性得分（私有方法）	结果排序
QueryMetricsTools	指标查询工具	queryPrometheusAlerts()	查询 Prometheus 告警数据	告警分析、故障诊断
		getMetricValue()	获取指定指标名称的当前值	性能监控、趋势分析
		getMetricHistory()	获取指标在时间范围内的历史数据	趋势分析、根因定位
QueryLogsTools	日志查询工具	queryLogs()	执行日志查询，支持多种过滤条件	故障排查、日志分析
		searchLogs()	根据关键词搜索日志内容	错误定位、日志审计
		getRecentLogs()	获取指定服务最近的 N 条日志	实时监控、问题复现

工具调用机制说明：

工具层的实现基于 Spring AI 的 @Tool 注解机制。Agent 在执行过程中会根据任务需要自动选择和调用相应的工具。工具调用的完整流程包括以下步骤：

1. 工具注册：在 Service 层通过 buildMethodToolsArray() 方法将工具注册到 Agent
2. 工具选择：Agent 根据当前上下文和任务需求决定调用哪个工具
3. 参数传递：Agent 生成工具调用请求，包含工具名称和参数
4. 执行反馈：工具执行完成后返回结果，Agent 根据结果继续推理或生成回答

工具扩展指南：

当需要添加新的工具能力时，需要遵循以下步骤：首先创建新的工具类并添加 @Tool 注解；然后在工具类中实现具体的方法逻辑；最后在 Service 层的 buildMethodToolsArray() 方法中注册新工具。这种设计模式确保了工具层的可扩展性，便于根据业务需求快速集成新的能力。

---

5. 核心模块设计

5.1 AIOps 多 Agent 协作流程

AIOps 多 Agent 协作流程是智能运维分析的核心执行路径。该流程通过 SupervisorAgent、PlannerAgent 和 ExecutorAgent 的协作，实现从告警接收到根因分析和报告生成的完整闭环。以下时序图展示了整个协作流程的详细步骤，包括各参与者的交互顺序、消息传递和状态转换过程。

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#e1d5e7'}}}%% sequenceDiagramautonumberparticipant User as 👤 用户participant API as 📡 /api/ai_opsparticipant Super as 🎭 SupervisorAgentparticipant Planner as 📝 PlannerAgentparticipant Executor as ⚡ ExecutorAgentparticipant Tools as 🔧 工具服务participant LLM as 🧠 DashScopeparticipant Milvus as 🗃️ Milvus%% 启动阶段User->>API: POST /api/ai_opsAPI->>Super: 启动多 Agent 编排Note over Super: Supervisor 初始化完成\n等待 Planner 指令%% 首次规划Super->>Planner: 调用 planner_agentPlanner->>LLM: 分析告警任务LLM-->>Planner: decision=PLANloop 规划-执行循环alt 规划阶段Planner->>Super: decision=PLANNote over Planner: 制定执行计划\n确定下一步操作endalt 执行阶段Planner->>Super: decision=EXECUTESuper->>Executor: 调用 executor_agentExecutor->>Tools: 1. 获取当前时间Tools-->>Executor: 当前时间Executor->>Tools: 2. 查询 Prometheus 告警Tools->>Milvus: 获取告警数据Milvus-->>Tools: 告警列表Tools-->>Executor: 告警数据Executor->>Tools: 3. 查询日志Tools-->>Executor: 日志内容Executor->>Tools: 4. 检索文档Tools->>Milvus: 向量检索Milvus-->>Tools: 相关文档Tools-->>Executor: 文档结果Executor->>LLM: 整合执行结果LLM-->>Executor: executor_feedbackExecutor->>Super: 返回执行反馈endSuper->>Planner: 提供 Executor 反馈Planner->>LLM: 重新规划LLM-->>Planner: 新决策end%% 终止阶段Planner->>Super: decision=FINISHSuper->>LLM: 生成最终报告LLM-->>Super: Markdown 报告Super->>API: 报告生成完成API->>User: SSE 流式输出报告

AIOps 协作流程详解：

流程阶段	执行步骤	参与者	核心操作	输出结果
启动阶段	步骤 1	用户 → API	POST /api/ai_ops 请求	触发分析流程
	步骤 2	API → Supervisor	启动多 Agent 编排	Supervisor 初始化
首次规划	步骤 3	Supervisor → Planner	调用 planner_agent	传递分析任务
	步骤 4	Planner → LLM	分析告警任务	LLM 推理决策
	步骤 5	LLM → Planner	返回 decision	decision=PLAN
规划-执行循环	步骤 6	Planner → Supervisor	报告决策结果	decision=PLAN 或 EXECUTE
	步骤 7	Planner → Supervisor	报告决策结果	decision=EXECUTE
	步骤 8	Supervisor → Executor	调用 executor_agent	传递执行指令
	步骤 9-16	Executor → 工具服务	循环执行多个工具调用	收集告警、日志、文档等数据
	步骤 17	Executor → LLM	整合执行结果	生成 executor_feedback
	步骤 18	Executor → Supervisor	返回执行反馈	executor_feedback
	步骤 19	Supervisor → Planner	提供反馈	触发重新规划
	步骤 20	Planner → LLM	重新规划	生成新决策
终止阶段	步骤 21	Planner → Supervisor	报告最终决策	decision=FINISH
	步骤 22	Supervisor → LLM	生成最终报告	Markdown 格式报告
	步骤 23	API → 用户	SSE 流式输出	实时展示分析进度

协作流程关键特性：

1. 循环迭代机制：通过规划-执行-反馈-再规划的循环，确保分析结果逐步完善
2. SSE 流式输出：每个执行步骤的结果都通过 SSE 实时推送给用户，提升交互体验
3. 工具链编排：Executor 按顺序调用 DateTimeTools → QueryMetricsTools → QueryLogsTools → InternalDocsTools，形成完整的数据收集链路
4. 状态维护：Supervisor 维护 OverAllState，记录每个执行步骤的结果，供最终报告生成使用
5. 异常处理：当连续 3 次工具调用失败时，进入失败终止路径，输出"无法完成"报告

5.2 RAG 检索增强生成流程

RAG（Retrieval-Augmented Generation，检索增强生成）是实现智能问答的核心技术架构。该流程包含三个主要阶段：文档摄入流程负责将原始文档转换为向量并存储到 Milvus 数据库；查询流程负责将用户问题转换为向量并在向量库中检索相关文档；生成流程负责将检索到的文档与用户问题组装成上下文，调用 LLM 生成最终回答。以下流程图展示了 RAG 系统的完整数据处理链路。

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#d5e8d4'}}}%% flowchart TBsubgraph INGEST["📤 文档摄入流程"]direction TBUPLOAD["📁 文件上传<br/>(TXT/MD)"]CHUNK["✂️ 文档分块<br/>max_size=800<br/>overlap=100"]EMBED["🔢 向量嵌入<br/>text-embedding-v4"]STORE["💾 Milvus 存储<br/>Collection: docs"]endsubgraph QUERY["❓ 查询流程"]direction TBQUESTION["用户问题"]QUERY_EMBED["🔢 问题向量化"]SEARCH["🔎 Top-K 检索<br/>top_k=3"]RERANK["📊 结果重排序"]endsubgraph GENERATE["✨ 生成流程"]direction TBCONTEXT["📋 上下文组装<br/>(问题 + 检索结果)"]LLM["🧠 LLM 推理<br/>qwen3-max"]OUTPUT["💬 生成回答"]endUPLOAD --> CHUNKCHUNK --> EMBEDEMBED --> STOREQUESTION --> QUERY_EMBEDQUERY_EMBED --> SEARCHSEARCH --> RERANKRERANK --> CONTEXTSTORE --> SEARCHCONTEXT --> LLMLLM --> OUTPUTstyle INGEST fill:#dae8fc,stroke:#6c8ebfstyle QUERY fill:#fff2cc,stroke:#d6b656style GENERATE fill:#d5e8d4,stroke:#82b366

RAG 流程各阶段详解：

流程阶段	处理步骤	核心操作	技术参数	输入输出
文档摄入流程	文件上传	接收 TXT/MD 格式文档	支持格式：TXT, MD	输入：原始文件，输出：文本内容
	文档分块	将长文本分割为小块	max_size=800 字符, overlap=100 字符	输入：长文本，输出：文本块列表
	向量嵌入	调用 DashScope text-embedding-v4 模型	嵌入维度：1536 维	输入：文本块，输出：浮点向量
	Milvus 存储	将向量和文本块存储到向量数据库	Collection: docs	输入：向量 + 元数据，输出：存储确认
查询流程	问题输入	接收用户自然语言问题	无	输入：用户问题，输出：问题文本
	问题向量化	将问题转换为向量表示	使用相同嵌入模型	输入：问题文本，输出：问题向量
	Top-K 检索	在 Milvus 中执行相似度搜索	top_k=3	输入：问题向量，输出：相似文档列表
	结果重排序	对检索结果进行相关性排序	基于余弦相似度	输入：原始排序结果，输出：优化排序
生成流程	上下文组装	将检索结果与问题组合	Prompt 模板	输入：问题 + 文档，输出：完整上下文
	LLM 推理	调用 qwen3-max 生成回答	temperature=0.8, max_tokens=2000	输入：上下文，输出：生成回答
	回答输出	返回最终回答给用户	支持流式输出	输入：LLM 输出，输出：格式化回答

RAG 关键配置参数说明：

参数名称	配置值	参数说明	调优建议
chunk_size	800 字符	文档分块的大小	较大值保留更多上下文，较小值提高检索精度
overlap	100 字符	相邻块之间的重叠长度	较大值确保跨块语义连贯，较小值减少冗余
top_k	3	检索返回的最相似文档数量	较大值提供更多上下文但增加处理时间
embedding_model	text-embedding-v4	向量嵌入模型	DashScope 提供的文本嵌入模型
generation_model	qwen3-max	回答生成模型	阿里云千问系列，中文理解能力强

RAG 流程优势分析：

1. 上下文感知：通过文档分块和重叠策略，确保检索结果包含完整的语义单元
2. 精准检索：Milvus 的向量索引支持高效的相似度计算，返回最相关的文档片段
3. 生成质量：结合检索到的真实文档片段，LLM 生成的回答具有事实依据，减少幻觉
4. 可追溯性：每个回答都可以追溯到具体的源文档，便于用户验证和深入阅读
5. 灵活扩展：支持增量更新知识库，新文档上传后自动向量化，无需全量重建

5.3 会话管理流程

会话管理是维持多轮对话上下文的核心机制，确保 Agent 能够理解和响应用户的连续对话内容。本系统采用基于内存的会话管理方案，通过滑动窗口机制控制历史消息的数量，在保证对话连贯性的同时避免内存无限增长。以下流程图展示了会话的完整生命周期管理过程。

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#ffe6cc'}}}%% flowchart TBsubgraph SESSION["💾 会话生命周期"]direction TBCREATE["创建会话<br/>SessionId 生成"]ADD["添加消息对<br/>(user + assistant)"]CHECK["检查窗口大小<br/>MAX_WINDOW=6"]COND["窗口溢出?"]CLEAN["成对清理<br/>删除最旧2条"]STORE["持久存储"]endsubgraph MANAGER["🔒 会话管理器"]direction TBMAP["ConcurrentHashMap<br/>sessions"]LOCK["ReentrantLock<br/>线程安全"]AUTO["自动清理"]endCREATE --> ADDADD --> CHECKCHECK --> CONDCOND -->|"是"| CLEANCOND -->|"否"| STORECLEAN --> STOREMAP --> CREATELOCK --> ADDAUTO --> CHECKstyle CREATE fill:#dae8fc,stroke:#6c8ebfstyle ADD fill:#fff2cc,stroke:#d6b656style CHECK fill:#ffe6cc,stroke:#d79b00style CLEAN fill:#f8cecc,stroke:#b85450style STORE fill:#d5e8d4,stroke:#82b366

会话管理机制详解：

管理阶段	处理步骤	核心逻辑	实现细节	状态变化
会话创建	SessionId 生成	为新会话分配唯一标识符	UUID 或服务端生成	null → SessionInfo 对象
	初始化存储	创建会话信息对象	初始化空消息列表、创建时间、锁对象
消息添加	用户消息录入	添加用户问题	role="user"	messageHistory.add(userMsg)
	AI 回答录入	添加 AI 回复	role="assistant"	messageHistory.add(assistantMsg)
	消息对计数	更新消息对数量	pairCount++
窗口检查	获取当前窗口大小	检查消息对数量	getMessagePairCount()
	判断是否溢出	比较与 MAX_WINDOW_SIZE	MAX_WINDOW=6
窗口清理	成对清理	删除最旧的两条消息对	保留最近的 4 对	删除最早 2 对
	清理触发条件	仅在溢出时执行	pairCount > MAX_WINDOW
持久存储	内存存储	存储到 ConcurrentHashMap	sessions.put(sessionId, info)
	后续查询准备	为下次对话提供上下文	通过 getHistory() 获取

滑动窗口机制说明：

会话管理采用滑动窗口算法平衡对话上下文完整性和内存使用效率。当会话消息对数量超过阈值时，系统自动清理最早的两条消息对，保留最近的四对。这种设计的优势包括：

1. 内存可控：无论对话进行多长时间，单个会话的内存占用保持在稳定水平
2. 上下文保留：始终保留最近 4 对消息，确保近期对话上下文完整
3. 语义连贯：清理后的对话仍然保持语义连贯，Agent 能够理解讨论主题的延续

线程安全实现：

线程安全组件	实现机制	作用	使用场景
ConcurrentHashMap	分段锁技术	存储会话映射关系	高并发会话访问
ReentrantLock	可重入互斥锁	保护会话状态修改	消息添加、窗口清理
synchronized blocks	代码块同步	批量操作的原子性	检查-执行模式

会话管理配置参数：

参数名称	配置值	参数说明	调优建议
MAX_WINDOW_SIZE	6	最大消息对数量	根据内存和上下文需求调整
清理批次大小	2	每次清理删除的消息对数	影响上下文保留量
会话超时时间	未设置	会话无操作后的超时时间	建议设置为 30-60 分钟

5.4 决策状态机

决策状态机描述了 AIOps 多 Agent 协作流程中的状态转换逻辑。系统从初始状态出发，经过等待任务、规划阶段、执行阶段的循环，最终到达终止状态或失败终止状态。以下状态图清晰展示了状态之间的转换条件、每个状态的内部子状态以及异常处理路径。

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#e1d5e7'}}}%% stateDiagram-v2[*] --> 初始化: 系统启动初始化 --> 等待任务: Supervisor 就绪等待任务 --> 规划阶段: 接收告警请求state 规划阶段 {[*] --> 分析任务分析任务 --> 制定计划: LLM 推理制定计划 --> [*]: 输出 decision}规划阶段 --> 执行阶段: decision=EXECUTEstate 执行阶段 {[*] --> 解析指令解析指令 --> 调用工具: 获取参数调用工具 --> 收集证据: 工具返回收集证据 --> 整合反馈: 格式化结果整合反馈 --> [*]: executor_feedback}执行阶段 --> 规划阶段: 提供反馈规划阶段 --> 终止:decision=FINISH状态: 规划阶段状态: 执行阶段state 终止 {[*] --> 生成报告生成报告 --> 格式校验: Markdown 模板格式校验 --> 报告输出: 流式发送报告输出 --> [*]: 完成}终止 --> [*]: 流程结束%% 失败路径分析任务 --> 失败终止: 连续3次工具失败调用工具 --> 失败终止: 连续3次工具失败失败终止 --> [*]: 输出"无法完成"报告

决策状态机详解：

状态分类	状态名称	内部子状态	状态功能	退出条件
初始状态	初始化	无	系统启动，执行必要的初始化操作	Supervisor 就绪
	等待任务	无	等待用户发起 AIOps 分析请求	接收告警请求
规划阶段	分析任务	无	理解输入任务，提取关键信息	LLM 完成推理
	制定计划	无	生成执行步骤和决策	输出 decision
执行阶段	解析指令	无	Executor 读取 Planner 的指令	获取参数完成
	调用工具	无	执行具体的工具操作	工具返回结果
	收集证据	无	汇总工具执行结果	格式化结果完成
	整合反馈	无	生成结构化的 executor_feedback	feedback 生成完成
终止状态	生成报告	无	Supervisor 调用 LLM 生成最终报告	Markdown 生成完成
	格式校验	无	验证报告格式是否符合模板	校验通过
	报告输出	无	通过 SSE 流式发送给用户	发送完成
失败终止	失败终止	无	生成错误报告	报告输出完成

状态转换条件说明：

当前状态	转换条件	目标状态	触发事件
初始化	Supervisor 组件就绪	等待任务	系统启动完成
等待任务	收到 POST /api/ai_ops 请求	规划阶段	用户发起分析
规划阶段	decision=EXECUTE	执行阶段	Planner 决策
执行阶段	执行反馈已返回	规划阶段	Executor 完成
规划阶段	decision=FINISH	终止	Planner 决策
分析任务	连续 3 次工具失败	失败终止	异常检测
调用工具	连续 3 次工具失败	失败终止	异常检测

异常处理机制：

异常场景	检测条件	处理策略	输出结果
工具调用失败	连续 3 次同一工具调用失败	进入失败终止流程	输出"无法完成"报告
LLM 推理超时	推理时间超过配置阈值	重试或终止	部分结果或错误信息
会话不存在	sessionId 对应会话不存在	创建新会话或返回错误	根据配置决定
内存溢出	会话历史超过内存阈值	强制清理或拒绝请求	错误响应

状态机设计模式优势：

1. 清晰的状态边界：每个状态都有明确的进入条件和退出条件，便于理解和维护
2. 可预测的行为：状态转换遵循预定义的规则，确保系统行为的一致性
3. 易于扩展：新增状态只需定义状态内容和转换条件，不影响现有逻辑
4. 完善的错误处理：失败终止路径确保系统在异常情况下也能给出有意义的反馈

---

6. 数据流设计

6.1 整体数据流

数据流设计描述了系统内部数据的输入、处理和输出路径。系统支持两种主要的数据处理路径：RAG 智能问答路径和 AIOps 智能运维路径。前者通过向量检索增强生成实现知识问答，后者通过多 Agent 协作实现运维分析。以下流程图展示了系统的整体数据流向，包括输入数据、处理组件和输出结果。

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#dae8fc'}}}%% flowchart LRsubgraph INPUT["📥 输入"]USER_Q["用户问题"]ALERT["告警数据"]DOC["文档数据"]endsubgraph PROCESS["⚙️ 处理"]direction TBVEC["向量化处理"]SEARCH["向量检索"]REASON["LLM 推理"]AGENT["Agent 决策"]endsubgraph OUTPUT["📤 输出"]ANSWER["回答文本"]REPORT["Markdown 报告"]ACTION["执行动作"]endUSER_Q --> VECDOC --> VECVEC --> SEARCHSEARCH --> REASONREASON --> ANSWERALERT --> AGENTAGENT --> SEARCHSEARCH --> REASONREASON --> REPORTAGENT --> ACTIONstyle INPUT fill:#dae8fc,stroke:#6c8ebfstyle PROCESS fill:#fff2cc,stroke:#d6b656style OUTPUT fill:#d5e8d4,stroke:#82b366

整体数据流说明：

数据流向	数据类型	数据来源	处理组件	处理结果
RAG 问答路径	用户问题	外部请求	向量化处理	问题向量表示
	文档数据	文件上传	向量化处理	文档向量存储
	查询向量	用户问题	向量检索	Top-K 相似文档
	检索结果	Milvus	LLM 推理	生成回答
AIOps 分析路径	告警数据	Prometheus	Agent 决策	告警分析决策
	告警查询	决策结果	向量检索	相关告警文档
	分析结果	多工具汇总	LLM 推理	分析报告
	执行动作	Agent 决策	工具服务	系统操作

数据处理路径详解：

路径类型	路径名称	数据转换过程	关键组件	输出形式
RAG 路径	问题处理流	文本 → 向量	VectorEmbeddingService	float[]
	检索流	向量 → Top-K 结果	VectorSearchService	List
	生成流	上下文 → 文本	DashScope LLM	String
AIOps 路径	告警分析流	告警 → 决策	SupervisorAgent	decision
	工具调用流	指令 → 执行结果	ExecutorAgent	executor_feedback
	报告生成流	反馈 → Markdown	SupervisorAgent	Markdown

数据流设计原则：

1. 单向数据流：数据沿单一方向流动，避免循环依赖，提高可追踪性
2. 清晰的数据边界：每个处理阶段有明确的输入和输出定义，便于模块测试
3. 异步处理支持：SSE 流式输出允许处理结果实时推送，无需等待完整处理完成
4. 数据转换透明：向量化和检索过程对上层调用透明，简化业务逻辑开发

6.2 RAG 数据流

RAG 数据流详细描述了检索增强生成系统的完整数据处理过程，包括文档数据流、查询数据流和生成数据流三个子流程。文档数据流负责将原始文档转换为向量并存储；查询数据流负责将用户问题转换为向量并执行相似度检索；生成数据流负责组装上下文并调用 LLM 生成回答。以下流程图展示了 RAG 系统的详细数据处理链路。

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#d5e8d4'}}}%% flowchart TBsubgraph DOC_FLOW["文档数据流"]direction LRDOC_FILE["原始文档<br/>(TXT/MD)"]CHUNK["文本分块<br/>800字符/块"]EMBED["向量化<br/>text-embedding-v4"]MILVUS["Milvus<br/>向量存储"]endsubgraph QUERY_FLOW["查询数据流"]direction LRUSER_Q["用户问题"]Q_EMBED["问题向量化"]SIM["相似度计算"]RETRIEVE["Top-K 检索"]endsubgraph GEN_FLOW["生成数据流"]direction LRCTX["上下文组装"]LLM["LLM 推理<br/>qwen3-max"]RESPONSE["生成回答"]endDOC_FILE --> CHUNK --> EMBED --> MILVUSUSER_Q --> Q_EMBED --> SIMMILVUS --> RETRIEVE --> SIMSIM --> CTX --> LLM --> RESPONSEstyle DOC_FLOW fill:#dae8fc,stroke:#6c8ebfstyle QUERY_FLOW fill:#fff2cc,stroke:#d6b656style GEN_FLOW fill:#d5e8d4,stroke:#82b366

RAG 子数据流详解：

数据流类型	处理节点	数据格式转换	技术实现	性能指标
文档数据流	DOC_FILE	原始文件格式	TXT/MD 文件上传	无
	CHUNK	文件 → 文本块列表	DocumentChunkService	800 字符/块
	EMBED	文本 → 向量	text-embedding-v4 API	1536 维向量
	MILVUS	向量 + 元数据 → 存储	Milvus SDK	批量插入优化
查询数据流	USER_Q	用户输入文本	HTTP POST 请求	无
	Q_EMBED	问题 → 向量	text-embedding-v4 API	1536 维向量
	SIM	向量相似度计算	Milvus IVF 索引	O(log n) 复杂度
	RETRIEVE	Top-K 结果返回	Milvus search	top_k=3
生成数据流	CTX	上下文模板组装	Prompt 工程	无
	LLM	上下文 → 回答	qwen3-max	temperature=0.8
	RESPONSE	流式文本输出	SSE	实时推送

数据格式说明：

数据节点	数据格式	数据示例	结构说明
原始文档	String	"## CPU 使用率告警\n\n### 告警信息..."	Markdown 格式文本
文本块	List[String]	["分块 1 内容...", "分块 2 内容..."]	固定长度字符串列表
向量表示	float[]	[0.123, -0.456, ...]	1536 维浮点数组
Milvus 存储	Collection		结构化文档记录
用户问题	String	"CPU 使用率过高怎么处理？"	自然语言文本
检索结果	List[Document]	[{doc1}, {doc2}, {doc3}]	相似文档列表
上下文	String	"相关文档：\n1. xxx\n\n问题：xxx"	组装后的 Prompt
生成回答	String	"根据文档，CPU 使用率过高可以..."	自然语言回答

跨数据流数据关系：

文档数据流和查询数据流通过 Milvus 向量数据库实现解耦。文档数据流将文本转换为向量后存储到 Milvus，查询数据流从 Milvus 检索相似向量，两个数据流使用相同的嵌入模型（text-embedding-v4）确保向量空间的兼容性。生成数据流接收查询数据流的检索结果作为输入，形成完整的数据处理链路。

6.3 消息数据结构

消息数据结构定义了系统中各实体之间的关系和属性。系统包含六个核心实体：ChatRequest（聊天请求）、Session（会话）、ChatMessage（聊天消息）、UserMsg（用户消息）、AssistantMsg（助手消息）、ToolCall（工具调用）和 ToolResult（工具结果）。以下 ER 图展示了各实体之间的关联关系和数据结构设计。

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#ffe6cc'}}}%% erDiagramCHAT_REQUEST ||--o| SESSION : "belongs to"SESSION ||--o{ CHAT_MESSAGE : "contains"CHAT_MESSAGE }o--|| USER_MSG : "sender"CHAT_MESSAGE }o--|| ASSISTANT_MSG : "sender"CHAT_REQUEST ||--o| TOOL_CALL : "triggers"TOOL_CALL ||--|| TOOL_RESULT : "produces"CHAT_REQUEST {string sessionId PKstring questiontimestamp timestamp}SESSION {string sessionId PKint maxWindowSizetimestamp createTime}CHAT_MESSAGE {int messageId PKstring sessionId FKstring rolestring contenttimestamp createTime}USER_MSG {string role "user"string content}ASSISTANT_MSG {string role "assistant"string contentjson toolCalls}TOOL_CALL {int callId PKstring sessionId FKstring toolNamejson parameterstimestamp createTime}TOOL_RESULT {int resultId PKint callId FKstring statusjson resultData}

实体关系详解：

实体名称	实体说明	主键	外键	核心属性
ChatRequest	聊天请求实体	sessionId	无	sessionId（会话标识）、question（问题内容）、timestamp（请求时间）
Session	会话实体	sessionId	无	sessionId（会话标识）、maxWindowSize（最大窗口大小）、createTime（创建时间）
ChatMessage	聊天消息实体	messageId	sessionId	messageId（消息标识）、sessionId（所属会话）、role（角色）、content（内容）、createTime（创建时间）
UserMsg	用户消息实体	无	ChatMessage	role 固定为 "user"、content（用户输入内容）
AssistantMsg	助手消息实体	无	ChatMessage	role 固定为 "assistant"、content（AI 生成内容）、toolCalls（工具调用列表，JSON 格式）
ToolCall	工具调用实体	callId	sessionId	callId（调用标识）、sessionId（所属会话）、toolName（工具名称）、parameters（调用参数，JSON 格式）、createTime（调用时间）
ToolResult	工具结果实体	resultId	callId	resultId（结果标识）、callId（对应调用）、status（执行状态）、resultData（结果数据，JSON 格式）

实体关系说明：

关系类型	关系名称	左实体	右实体	关系说明
归属关系	belongs to	ChatRequest	Session	每个请求属于一个会话，一个会话可以有多个请求
包含关系	contains	Session	ChatMessage	一个会话包含多条消息，一条消息属于一个会话
发送关系	sender	ChatMessage	UserMsg	用户消息由用户角色消息实体发送
发送关系	sender	ChatMessage	AssistantMsg	助手消息由助手角色消息实体发送
触发关系	triggers	ChatRequest	ToolCall	请求可能触发工具调用
生产关系	produces	ToolCall	ToolResult	每次工具调用都会产生一个结果

JSON 字段格式说明：

JSON 字段	所属实体	JSON 结构示例	字段说明
toolCalls	AssistantMsg	[{"name": "queryMetrics", "arguments": {...}}]	包含零个或多个工具调用记录
parameters	ToolCall		工具调用的参数键值对
resultData	ToolResult		工具执行结果的 JSON 表示

数据结构设计原则：

1. 规范化设计：遵循数据库第三范式，消除数据冗余，确保数据一致性
2. 灵活扩展：使用 JSON 字段存储可变结构数据，便于功能扩展
3. 时间戳追踪：所有实体都包含创建时间，便于问题排查和数据分析
4. 关系清晰：通过外键明确实体之间的关联，便于数据查询和统计

---

7. API 接口架构

7.1 接口总览

API 接口是系统对外提供服务的入口，本系统采用 RESTful 风格设计 API 接口，提供对话交互、AIOps 分析、会话管理、文件上传和健康检查五大类接口。以下架构图展示了系统的完整 API 体系，包括接口分类、路径定义和功能说明。

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#fff2cc'}}}%% graph TBsubgraph API["📡 REST API 接口"]direction TBsubgraph CHAT_API["💬 对话接口"]CHAT["POST /api/chat<br/>普通对话"]CHAT_STREAM["POST /api/chat_stream<br/>流式对话 (SSE)"]endsubgraph AIOPS_API["🔧 AIOps 接口"]AI_OPS["POST /api/ai_ops<br/>智能运维分析"]endsubgraph SESSION_API["💾 会话接口"]CLEAR["POST /api/chat/clear<br/>清空会话"]SESSION["GET /api/chat/session/{id}<br/>获取会话信息"]endsubgraph FILE_API["📤 文件接口"]UPLOAD["POST /api/upload<br/>文件上传"]endsubgraph HEALTH_API["💚 健康接口"]HEALTH["GET /milvus/health<br/>Milvus 健康检查"]endendCHAT_API --> CHAT_STREAMCHAT_API --> CHATSESSION_API --> CLEARSESSION_API --> SESSIONstyle CHAT_API fill:#dae8fc,stroke:#6c8ebfstyle AIOPS_API fill:#ffe6cc,stroke:#d79b00style SESSION_API fill:#fff2cc,stroke:#d6b656style FILE_API fill:#d5e8d4,stroke:#82b366style HEALTH_API fill:#f8cecc,stroke:#b85450

API 接口分类说明：

接口分类	接口名称	请求路径	HTTP 方法	功能说明	返回类型
对话接口	普通对话	/api/chat	POST	处理普通对话请求，返回同步响应	JSON
	流式对话	/api/chat_stream	POST	处理流式对话请求，通过 SSE 实时推送	SSE Stream
AIOps 接口	智能运维	/api/ai_ops	POST	启动 AIOps 分析流程，返回流式分析报告	SSE Stream
会话接口	清空会话	/api/chat/clear	POST	清空指定会话的历史记录	JSON
	获取会话信息	/api/chat/session/	GET	获取会话的详细信息和历史消息数量	JSON
文件接口	文件上传	/api/upload	POST	上传文档文件，触发向量化和存储	JSON
健康接口	Milvus 健康检查	/milvus/health	GET	检查 Milvus 连接状态和服务可用性	JSON

接口调用关系说明：

调用源	调用目标	调用条件	数据流向
Web 前端	普通对话接口	用户发起普通对话	请求 → 响应
Web 前端	流式对话接口	用户发起流式对话	请求 → SSE 流
Web 前端	AIOps 接口	用户发起运维分析	请求 → SSE 流
第三方系统	会话接口	查询或管理会话	请求 → 响应
管理后台	文件上传接口	上传运维文档	请求 → 响应
监控系统	健康检查接口	健康探测	请求 → 响应

接口设计规范说明：

所有 API 接口遵循以下设计规范，确保接口的一致性和易用性：

1. RESTful 风格：使用标准的 HTTP 方法（GET/POST）和资源路径，语义清晰
2. 统一响应格式：所有接口返回 JSON 格式，包含 success、answer/data、errorMessage 等字段
3. SSE 流式输出：长时处理任务采用 Server-Sent Events 实现实时推送
4. 错误处理：异常情况通过 errorMessage 字段返回，便于客户端处理

7.2 请求响应模型

请求响应模型描述了系统处理不同类型请求的完整流程。系统支持两种请求处理模式：同步请求-响应模式和流式 SSE 模式。同步模式适用于短时任务，完成后一次性返回结果；流式模式适用于长时任务，实现实时进度展示和增量结果推送。以下时序图详细展示了两种模式的数据流向和组件交互过程。

%%{init: {'theme': 'base', 'themeVariables': {'sequenceNumberBg': '#fff2cc'}}}%% sequenceDiagramparticipant Client as 📱 客户端participant API as 📡 REST APIparticipant Ctrl as 🎮 Controllerparticipant Svc as 📋 Serviceparticipant Agent as 🤖 Agentparticipant LLM as 🧠 LLMNote over Client,LLM: 普通对话流程Client->>API: POST /api/chat<br/>{"id": "xxx", "question": "..."}API->>Ctrl: chat(request)Ctrl->>Svc: createAgent()Svc->>Agent: createReactAgent()Agent->>LLM: 模型推理LLM-->>Agent: 完整响应Agent-->>Svc: fullAnswerSvc-->>Ctrl: answerCtrl-->>API: {success: true, answer: "..."}API-->>Client: 200 OKNote over Client,LLM: 流式对话流程 (SSE)Client->>API: POST /api/chat_stream<br/>{"id": "xxx", "question": "..."}API->>Ctrl: chatStream(request)Ctrl->>Svc: createAgent()Svc->>Agent: createReactAgent()Agent->>LLM: 模型推理 (流式)loop 流式输出LLM-->>Agent: chunkAgent-->>Ctrl: NodeOutputCtrl-->>Client: SSE: data: {...}endAgent-->>Svc: 完成Svc-->>Ctrl: 会话更新Ctrl-->>Client: SSE: done

请求响应流程详解：

流程类型	处理阶段	组件交互	数据内容	响应方式
普通对话流程	请求接收	Client → API → Ctrl		HTTP POST
	Agent 创建	Ctrl → Svc → Agent	创建 ReactAgent 实例	内部调用
	模型推理	Agent → LLM	完整 Prompt	同步等待
	结果返回	LLM → Agent → Svc → Ctrl	完整回答文本	fullAnswer
	响应发送	API → Client		HTTP 200 OK
流式对话流程	请求接收	Client → API → Ctrl		HTTP POST
	Agent 创建	Ctrl → Svc → Agent	创建 ReactAgent 实例	内部调用
	流式推理	Agent → LLM	完整 Prompt	流式响应
	增量推送	LLM → Agent → Ctrl	chunk 数据块	SSE: data:
	会话更新	Agent → Svc → Ctrl	更新会话历史	内部处理
	完成通知	Ctrl → Client	SSE: done	完成标记

两种模式对比说明：

对比维度	普通对话模式	流式对话模式
响应时间	需等待完整回答后返回	实时推送，用户感知更快
数据量	单次大 payload	多次小 payload
实现复杂度	较低，标准 REST	较高，需处理 SSE 流
适用场景	短时问答、快速查询	长文本生成、AIOps 分析
用户体验	等待时间长	即时反馈、进度可见
资源消耗	单次大内存	持续小内存

流式输出优势分析：

1. 即时反馈：用户无需等待完整处理即可看到中间结果，提升交互体验
2. 进度透明：SSE done 标记告知用户处理完成，便于界面状态管理
3. 长文本友好：对于 AIOps 长报告，流式输出避免超时问题
4. 资源高效：LLM 生成的同时即可推送，无需等待全部完成后一次性发送

7.3 SSE 流式响应格式

SSE（Server-Sent Events）流式响应格式是实现实时推送的标准协议。本系统使用 SSE 格式实现对话和 AIOps 分析的流式输出，包括内容片段、错误信息和完成标记三种消息类型。以下流程图展示了 SSE 消息的格式结构和消息类型的对应关系。

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#ffe6cc'}}}%% flowchart TBsubgraph SSE_MESSAGE["SSE 消息格式"]direction TBA["event: message"]B["data: {'type': 'content', 'data': '文本片段'}"]C["event: message"]D["data: {'type': 'done', 'data': null}"]endsubgraph MESSAGE_TYPE["消息类型"]direction TBT1["content<br/>增量内容片段"]T2["error<br/>错误信息"]T3["done<br/>完成标记"]end%% 正确连接方式：子图 -> 节点SSE_MESSAGE -->|对应| MESSAGE_TYPEA & B -.-> T1C & D -.-> T3style SSE_MESSAGE fill:#dae8fc,stroke:#6c8ebfstyle MESSAGE_TYPE fill:#fff2cc,stroke:#d6b656

SSE 消息格式详解：

消息组件	格式示例	字段说明	用途描述
event 字段	event: message	事件类型标识	区分不同类型的消息事件
data 字段	data:	消息数据内容	携带实际的消息负载
完成标记	空行（连续换行）	消息分隔符	SSE 协议要求每条消息以空行结束

消息类型说明：

消息类型	type 值	data 内容	使用场景	客户端处理
内容片段	content	增量文本内容	推送 LLM 生成的部分文本	追加到显示区域
错误信息	error	错误描述文本	推送错误或异常信息	显示错误提示
完成标记	done	null	推送完成通知	结束监听，清理状态

SSE 消息传输示例：

以下是一次完整的 SSE 流式响应的消息序列示例：

event: message
data: {"type": "content", "data": "根据系统分析，"}event: message
data: {"type": "content", "data": "当前 CPU 使用率达到了 95%，"}event: message
data: {"type": "content", "data": "建议您执行以下操作..."}event: message
data: {"type": "done", "data": null}

客户端处理逻辑：

客户端操作	处理逻辑	实现说明
建立连接	EventSource 连接 SSE 端点	new EventSource('/api/chat_stream')
接收消息	onmessage 回调处理	event.data 包含 JSON 字符串
解析数据	JSON.parse 解析 data 字段	获取 type 和 data 内容
类型判断	根据 type 执行不同逻辑	content/ error/ done
连接关闭	onerror 或 onclose 处理	清理资源，更新界面状态

SSE 协议优势说明：

1. 轻量级：基于 HTTP 协议，无需 WebSocket 的握手升级
2. 单向通信：服务端推送，客户端只需接收，适合本系统的场景
3. 自动重连：浏览器自动处理连接断开后的重连，降低开发复杂度
4. 标准格式：遵循 W3C SSE 标准，兼容性良好

---

8. 部署架构

8.1 生产部署架构

生产部署架构描述了系统在生产环境中的完整部署方案，包括客户端层、负载均衡层、应用集群、数据层、监控层和外部服务层。以下架构图展示了各层组件的部署关系、网络连接和数据流向。

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#f8cecc'}}}%% graph TBsubgraph CLIENT["👤 客户端层"]USER["👥 最终用户"]MOBILE["📱 移动端"]THIRD["🔗 第三方系统"]endsubgraph LB["⚖️ 负载均衡"]NGINX["Nginx<br/>负载均衡 + SSL"]endsubgraph APP["🚀 应用集群"]APP1["SuperBizAgent #1<br/>:9900"]APP2["SuperBizAgent #2<br/>:9900"]APP3["SuperBizAgent #N<br/>:9900"]endsubgraph DATA["💾 数据层"]MILVUS["🗃️ Milvus 集群<br/>:19530"]DOCS["📁 文档存储<br/>NFS/OSS"]endsubgraph MONITOR["📊 监控"]PROM["📈 Prometheus"]GRAFANA["📉 Grafana"]ALERT["🚨 Alert"]endsubgraph EXTERNAL["☁️ 外部服务"]DASHSCOPE["🧠 阿里云<br/>DashScope"]MCP["🔌 腾讯云<br/>MCP"]endUSER & MOBILE & THIRD --> NGINXNGINX --> APP1 & APP2 & APP3APP1 & APP2 & APP3 --> MILVUSAPP1 & APP2 & APP3 --> DOCSAPP1 & APP2 & APP3 --> DASHSCOPEAPP1 & APP2 & APP3 --> MCPAPP1 & APP2 & APP3 --> PROMPROM --> GRAFANA & ALERTclassDef client fill:#dae8fc,stroke:#6c8ebfclassDef lb fill:#fff2cc,stroke:#d6b656classDef app fill:#ffe6cc,stroke:#d79b00classDef data fill:#f8cecc,stroke:#b85450classDef monitor fill:#d5e8d4,stroke:#82b366classDef external fill:#e1d5e7,stroke:#9673a6class USER,MOBILE,THIRD clientclass NGINX lbclass APP1,APP2,APP3 appclass MILVUS,DOCS dataclass PROM,GRAFANA,ALERT monitorclass DASHSCOPE,MCP external

生产部署架构各层说明：

部署层级	组件名称	部署规格	核心功能	配置要点
客户端层	Web 前端	静态资源托管	可视化交互界面	CDN 加速、缓存策略
	移动端	iOS/Android 应用	移动端访问	API 网关适配
	第三方系统	API 调用方	系统集成	认证授权机制
负载均衡层	Nginx	反向代理 + 负载均衡	请求分发 + SSL 终止	upstream 配置、健康检查
应用集群	SuperBizAgent #1-#N	容器化部署	业务逻辑处理	多实例水平扩展
数据层	Milvus 集群	向量数据库集群	向量存储与检索	主从复制、读写分离
	文档存储	NFS/OSS	原始文档存储	备份策略、冷热分离
监控层	Prometheus	指标采集	系统指标收集	抓取间隔、存储周期
	Grafana	可视化仪表盘	监控数据展示	仪表盘模板
	Alertmanager	告警管理	告警路由与通知	告警规则、接收渠道
外部服务	阿里云 DashScope	LLM 服务	文本生成与推理	API 限流处理
	腾讯云 MCP	日志服务	日志接入	连接池管理

生产部署关键配置：

配置项	配置值	配置说明	调优建议
应用实例数	3-N	根据负载动态调整	CPU 利用率 70% 为扩容阈值
Nginx worker 进程数	CPU 核心数	最大化并发处理	避免过多进程消耗资源
Milvus 副本数	2-3	保证高可用	与应用实例数匹配
Prometheus 抓取间隔	15s	平衡精度与开销	重要指标可缩短至 5s
LLM 超时时间	180s	防止请求堆积	根据模型响应时间调整

8.2 Docker Compose 架构

Docker Compose 架构展示了开发环境和测试环境的容器化部署方案。通过 Docker Compose，可以一键启动完整的开发环境，包括 Spring Boot 应用、Milvus 数据库及其依赖组件（Etcd 和 MinIO）。以下架构图展示了 Docker Compose 环境的服务容器、网络和数据卷配置。

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#dae8fc'}}}%% graph TBsubgraph DOCKER["🐳 Docker Compose 环境"]direction TBsubgraph SERVICES["📦 服务容器"]APP["Spring Boot<br/>端口: 9900"]MILVUS_ETCD["Milvus Etcd<br/>端口: 2379"]MILVUS_MINIO["Milvus MinIO<br/>端口: 9000/9001"]MILVUS_SRV["Milvus Server<br/>端口: 19530"]endsubgraph NETWORKS["🌐 网络"]NET["internal-network"]endsubgraph VOLUMES["💾 数据卷"]VOL1["minio-data:/minio_data"]VOL2["milvus-data:/var/lib/milvus"]endendAPP --> MILVUS_SRVAPP --> MILVUS_MINIOMILVUS_ETCD <--> MILVUS_SRVMILVUS_MINIO <--> MILVUS_SRVSERVICES --> NETNET --> VOL1 & VOL2style APP fill:#ffe6cc,stroke:#d79b00,stroke-width:2pxstyle MILVUS_ETCD fill:#dae8fc,stroke:#6c8ebfstyle MILVUS_MINIO fill:#fff2cc,stroke:#d6b656style MILVUS_SRV fill:#d5e8d4,stroke:#82b366

Docker Compose 服务配置说明：

服务名称	服务说明	容器镜像	端口映射	依赖关系	环境配置
APP	Spring Boot 应用	本地构建镜像	9900:9900	依赖 Milvus Server	DASHSCOPE_API_KEY、MILVUS_HOST
MILVUS_ETCD	Milvus 元数据存储	milvusdb/etcd	2379:2379	无依赖	ETCD_ROOT_PASSWORD
MILVUS_MINIO	Milvus 对象存储	minio/minio	9000:9001	无依赖	MINIO_ROOT_USER/PASSWORD
MILVUS_SRV	Milvus 向量数据库	milvusdb/milvus	19530:19530	依赖 Etcd + MinIO	ETCD_ENDPOINTS

网络配置说明：

配置项	配置值	配置说明	用途描述
网络名称	internal-network	Docker 内部网络	容器间通信隔离
网络驱动	bridge	Docker 桥接网络	默认网络模式
网络模式	internal	禁用外部访问	提高安全性

数据卷配置说明：

卷名称	宿主机路径	容器内路径	用途说明	持久化策略
minio-data	./minio_data	/minio_data	MinIO 对象存储数据	重要数据，需定期备份
milvus-data	./milvus_data	/var/lib/milvus	Milvus 向量数据	重要数据，需定期备份

Docker Compose 使用指南：

操作命令	命令说明	使用场景	注意事项
docker-compose up -d	启动所有服务	开发环境启动	首次启动自动创建网络和卷
docker-compose down	停止所有服务	开发完成清理	数据卷保留
docker-compose down -v	停止并删除卷	完全重置环境	会删除所有数据
docker-compose logs -f	查看日志	问题排查	支持指定服务日志
docker-compose ps	查看服务状态	确认运行状态	查看端口映射

开发环境快速启动步骤：

1. 配置 .env 文件，设置 DASHSCOPE_API_KEY 等环境变量
2. 执行 docker-compose up -d 启动所有服务
3. 等待 Milvus 服务就绪（约 30 秒）
4. 访问 http://localhost:9900 验证应用启动
5. 使用 http://localhost:9001 访问 MinIO 控制台（可选）

8.3 高可用架构

高可用架构展示了系统的跨区域容灾部署方案。通过在 Region A（广州）和 Region B（上海）部署相同的应用集群和 Milvus 实例，实现跨区域的数据同步和故障切换。以下架构图展示了双活架构的部署配置和数据复制关系。

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#f8cecc'}}}%% graph TBsubgraph REGION_A["📍 Region A (广州)"]LB_A["负载均衡器 A"]APP_A1["应用 #1"]APP_A2["应用 #2"]MILVUS_A["Milvus 主"]endsubgraph REGION_B["📍 Region B (上海)"]LB_B["负载均衡器 B"]APP_B1["应用 #3"]APP_B2["应用 #4"]MILVUS_B["Milvus 备"]endsubgraph DR["🔄 跨区域复制"]SYNC["数据同步"]endUSER["👥 用户"] --> LB_AUSER --> LB_BLB_A --> APP_A1 & APP_A2LB_B --> APP_B1 & APP_B2APP_A1 & APP_A2 --> MILVUS_AAPP_B1 & APP_B2 --> MILVUS_BMILVUS_A -.->|"实时复制"| SYNCSYNC -.-> MILVUS_Bstyle REGION_A fill:#dae8fc,stroke:#6c8ebfstyle REGION_B fill:#fff2cc,stroke:#d6b656style DR fill:#f8cecc,stroke:#b85450

高可用架构各区域说明：

区域名称	区域位置	组件配置	角色定位	容量配置
Region A	广州	负载均衡器 A + 应用 #1-#2 + Milvus 主	主站点	承载 70% 流量
Region B	上海	负载均衡器 B + 应用 #3-#4 + Milvus 备	备站点	承载 30% 流量
跨区域复制	数据同步	实时向量数据同步	容灾保障	RPO < 1 分钟

Region A 主站点配置：

组件名称	部署规格	核心功能	性能指标	高可用策略
负载均衡器 A	主备模式	流量分发 + 健康检查	10K TPS	自动故障切换
应用 #1	容器化	业务逻辑处理	CPU 4核 8G	无状态设计
应用 #2	容器化	业务逻辑处理	CPU 4核 8G	无状态设计
Milvus 主	主从部署	向量存储与检索	百万向量/s	主从同步

Region B 备站点配置：

组件名称	部署规格	核心功能	性能指标	高可用策略
负载均衡器 B	主备模式	流量分发 + 健康检查	10K TPS	自动故障切换
应用 #3	容器化	业务逻辑处理	CPU 4核 8G	无状态设计
应用 #4	容器化	业务逻辑处理	CPU 4核 8G	无状态设计
Milvus 备	主从部署	向量存储与检索	百万向量/s	从库同步

跨区域数据复制机制：

复制模式	复制策略	复制频率	复制延迟	数据一致性
实时复制	Milvus 主备同步	连续同步	< 1 秒	最终一致性
异步复制	定时批量同步	5 分钟间隔	< 5 分钟	弱一致性

故障切换策略说明：

故障场景	检测方式	切换策略	恢复方式	RTO 指标
应用实例故障	健康检查	自动重启或切换	人工干预	< 30 秒
区域整体故障	DNS 解析切换	Region B 接管全部流量	故障恢复后回切	< 5 分钟
Milvus 主故障	主从心跳检测	自动切换到从库	故障修复后同步	< 1 分钟
网络链路故障	链路监控	切换到备用链路	人工确认恢复	< 2 分钟

高可用架构优势：

1. 地理容灾：双区域部署，单区域故障不影响整体服务
2. 负载均衡：按比例分配流量，优化资源利用率
3. 数据安全：实时数据同步，防止数据丢失
4. 快速恢复：RTO < 5 分钟，满足业务连续性要求
5. 平滑扩展：支持按需扩展区域容量