Logan.Li
e0d652d211
- 支持 Windows Agent 构建、安装脚本和统一上报协议 - 增强 RDP 剪贴板、虚拟盘和文件传输能力 - 新增 AIOps 上下文工具、告警 RCA trace 落库和回放接口 - 重构 docs 模块文档并补充终端、堡垒机、监控、AI Agent 设计
180 lines
5.9 KiB
Markdown
180 lines
5.9 KiB
Markdown
# 02 - 整体架构设计
|
||
|
||
> 本文描述 AIOps 当前 Agent CLI 的真实工程分层、端到端链路和模块职责。// Logan.Li
|
||
|
||
---
|
||
|
||
## 架构定位
|
||
|
||
Agent CLI 是 AIOps 平台内置的智能运维执行器，整体由四层组成：
|
||
|
||
| 层级 | 代码位置 | 职责 |
|
||
|------|----------|------|
|
||
| 前端工作台 | `frontend/src/components/aiops/AgentCLI.tsx` | 目标选择、任务输入、事件流展示、确认弹框、历史侧栏 |
|
||
| WebSocket / REST Controller | `backend/controller/agent_cli*.go` | 鉴权、目标加载、会话入库、WS 控制协议、安全确认桥接 |
|
||
| Agent 引擎库 | `backend/pkg/agentcli/` | LLM、Prompt、ReAct、工具注册、安全控制、Evolver |
|
||
| 平台底座 | `model.Server`、`LLMConfig`、K8s Client、凭证、DB | 资产、凭据、集群、模型配置、会话存储 |
|
||
|
||
核心边界：`backend/pkg/agentcli/` 不依赖 `controller` 或 `model`，只接收配置和回调；平台业务全部在 controller 层完成。
|
||
|
||
---
|
||
|
||
## 端到端调用链路
|
||
|
||
```text
|
||
浏览器 AgentCLI 页面
|
||
│
|
||
├─ host 模式: /ws/agent-cli?mode=host&id=<serverID>&token=<jwt>
|
||
└─ kubernetes 模式: /ws/agent-cli?mode=kubernetes&cluster=<code>&namespace=<ns>&pod=<pod>&container=<container>&token=<jwt>
|
||
│
|
||
▼
|
||
AgentCLIHandler.Run()
|
||
├─ JWTAuth 解析当前用户
|
||
├─ 加载 Server / KubernetesCluster
|
||
├─ 构造 SSHConfig 或 KubernetesTarget
|
||
├─ 读取启用的 LLMConfig
|
||
├─ 创建 / 续接 AgentCLISession
|
||
└─ agentcli.NewEngine()
|
||
│
|
||
▼
|
||
core.Agent.Run()
|
||
├─ BuildSystemPrompt()
|
||
├─ LLM function calling
|
||
├─ tools.Registry 查找工具
|
||
├─ safety.Controller 执行前检查
|
||
├─ EventCallback 推送事件并落库
|
||
└─ Evolver 异步学习经验
|
||
```
|
||
|
||
---
|
||
|
||
## 前端层
|
||
|
||
前端页面负责把 Agent 的执行过程做成可操作的工作台：
|
||
|
||
| 模块 | 职责 |
|
||
|------|------|
|
||
| `AgentCLI.tsx` | 页面主体、模式切换、目标选择、WebSocket 生命周期 |
|
||
| `AgentCLIMessages.tsx` | 渲染思考、工具调用、工具结果、最终答案 |
|
||
| `AgentCLIHistory.tsx` | 会话列表、回放、删除、继续追问 |
|
||
| `frontend/src/api/aiops/agent-cli.ts` | REST 会话 API 和 WebSocket URL 构建 |
|
||
|
||
前端通过 WebSocket 发送控制消息：
|
||
|
||
| type | 含义 |
|
||
|------|------|
|
||
| `start` | 开始新任务 |
|
||
| `continue` | 基于当前会话继续追问 |
|
||
| `resume` | 加载历史会话上下文 |
|
||
| `confirm` | 批准高危工具调用 |
|
||
| `reject` | 拒绝高危工具调用 |
|
||
|
||
---
|
||
|
||
## Controller 层
|
||
|
||
Controller 是平台上下文和通用 Agent 引擎之间的适配层。
|
||
|
||
### 主机模式
|
||
|
||
`runHostWS()` 完成：
|
||
|
||
1. 从 `id` 查询 `model.Server`。
|
||
2. 通过资产和凭据构造 `remoteexec.SSHConfig`。
|
||
3. 读取启用的 `model.LLMConfig`。
|
||
4. 建立 WebSocket 连接。
|
||
5. 组装 `agentcli.EngineConfig{Mode: host, SSH: ...}`。
|
||
|
||
### Kubernetes 模式
|
||
|
||
`runKubernetesWS()` 完成：
|
||
|
||
1. 从 `cluster`、`namespace`、`pod`、`container` 解析目标。
|
||
2. 加载 Kubernetes 集群配置。
|
||
3. 构造轻量 K8s Client。
|
||
4. 组装 `agentcli.EngineConfig{Mode: kubernetes, Kubernetes: ...}`。
|
||
|
||
### 会话与事件
|
||
|
||
Controller 负责将事件写入数据库：
|
||
|
||
| 表 | 内容 |
|
||
|----|------|
|
||
| `agent_cli_sessions` | 一次 AI 任务的用户、目标、模型、状态、轮次、耗时、token |
|
||
| `agent_cli_messages` | 用户输入、思考、工具调用、工具输出、最终答案、错误 |
|
||
|
||
---
|
||
|
||
## 引擎层
|
||
|
||
`agentcli.NewEngine()` 组装以下组件：
|
||
|
||
| 组件 | 代码位置 | 说明 |
|
||
|------|----------|------|
|
||
| LLM Client | `pkg/agentcli/llm/` | 支持 OpenAI 兼容接口和 Anthropic Messages |
|
||
| Registry | `pkg/agentcli/tools/registry.go` | 线程安全工具注册中心 |
|
||
| Safety Controller | `pkg/agentcli/safety/safety.go` | 高危确认、危险命令硬拒 |
|
||
| Core Agent | `pkg/agentcli/core/agent.go` | 16 轮 ReAct 主循环 |
|
||
| Evolver | `pkg/agentcli/evolver/` | 经验、事实、流程记忆 |
|
||
|
||
引擎接收两个关键回调：
|
||
|
||
| 回调 | 说明 |
|
||
|------|------|
|
||
| `EventCallback` | 推送 `progress/thought/tool_call/tool_result/done/error` 并落库 |
|
||
| `ConfirmFn` | 高危工具调用时由 controller 推送确认事件，等待前端响应 |
|
||
|
||
---
|
||
|
||
## 工具集
|
||
|
||
工具按运行模式注册，避免模型看到不该用的工具。
|
||
|
||
| 模式 | 工具 |
|
||
|------|------|
|
||
| host | `ssh_execute`、`analyze_output` |
|
||
| kubernetes | `kubernetes_get`、`pod_logs`、`pod_execute`、`kubernetes_action`、`analyze_output` |
|
||
|
||
`ssh_execute` 和 `pod_execute` 支持动态风险评估，会根据实际命令计算风险等级。
|
||
|
||
---
|
||
|
||
## 数据流
|
||
|
||
```text
|
||
用户输入 query
|
||
→ 写入 agent_cli_messages(type=session, role=user)
|
||
→ BuildSystemPrompt(mode, targetInfo, toolDescs, evolveContext)
|
||
→ LLM Complete(function calling)
|
||
→ tool_call event
|
||
→ safety.Check()
|
||
→ tool.Execute()
|
||
→ tool_result event
|
||
→ LLM 观察工具输出继续推理
|
||
→ done / error event
|
||
→ 更新 agent_cli_sessions 状态
|
||
→ Evolver 后台学习
|
||
```
|
||
|
||
---
|
||
|
||
## 当前架构优点
|
||
|
||
1. **平台权限可控**：WebSocket 入口走 JWT，目标资产由后端加载。
|
||
2. **引擎可复用**：`pkg/agentcli` 是纯库，后续可接自动化任务或告警处置。
|
||
3. **过程可审计**：每一步工具调用和输出都有数据库记录。
|
||
4. **工具面收敛**：主机和 K8s 模式互斥注册工具，减少误调用。
|
||
5. **失败可降级**：Evolver 初始化失败不影响主流程。
|
||
|
||
---
|
||
|
||
## 待演进点
|
||
|
||
| 方向 | 建议 |
|
||
|------|------|
|
||
| 权限剪枝 | 按用户权限动态注册工具，例如无 K8s 变更权限则不注册 `kubernetes_action` |
|
||
| 审计统一 | 工具调用同步写入安全审计中心，关联审批、资产、用户 |
|
||
| 记忆 DB 化 | 将 `data/agentcli` 文件记忆迁移到数据库，支持查看和清理 |
|
||
| 输出脱敏 | 对密钥、Token、Cookie、连接串做落库前脱敏 |
|
||
| 审批接入 | 高危动作不只弹确认，支持企业审批流 |
|