mirror of
https://github.com/GNS3/gns3-server.git
synced 2026-08-31 06:20:12 +03:00
105 lines
4.2 KiB
Markdown
105 lines
4.2 KiB
Markdown
<!--
|
||
SPDX-License-Identifier: CC-BY-SA-4.0
|
||
See LICENSE file for licensing information.
|
||
-->
|
||
|
||
# GNS3-Copilot 故障注入概览
|
||
|
||
## 核心流程
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph "① 接口触发与模式切换"
|
||
A["POST /chat/inject\n用户请求注入故障"] --> B["验证项目已打开"]
|
||
B --> C["设置copilot_mode =\ntroubleshooting_injection"]
|
||
C --> D["启动Agent\n携带故障注入工具集"]
|
||
end
|
||
|
||
subgraph "② 拓扑分析与故障选型"
|
||
D --> E["GNS3TopologyTool\n获取拓扑信息"]
|
||
E --> F["ExecuteMultipleDeviceCommands\n获取设备配置"]
|
||
F --> G["InjectionSkillsTool\n查询可用故障类型"]
|
||
G --> H{"注入技能仓库\ngns3/gns3-skills"}
|
||
H --> I["返回匹配的故障定义\n含配置注入命令"]
|
||
end
|
||
|
||
subgraph "③ 故障注入"
|
||
I --> J["选择注入方式"]
|
||
J --> K["ExecuteMultipleDeviceConfigCommands\n注入配置变更"]
|
||
J --> L["GNS3PacketFilterTool\n注入链路层故障"]
|
||
end
|
||
|
||
subgraph "④ 结果确认"
|
||
K --> M["验证故障生效"]
|
||
L --> M
|
||
M --> N["记录故障详情\n含恢复命令"]
|
||
end
|
||
```
|
||
|
||
## 工具总览
|
||
|
||
| 工具 | 源文件 | 作用 | 可用模式 |
|
||
|---|---|---|---|
|
||
| `InjectionSkillsTool` | `registry.py`（skills 模块） | 查询协议级故障定义（配置变更命令） | troubleshooting_injection |
|
||
| `GNS3PacketFilterTool` | `gns3_packet_filter.py` | 链路层故障注入（延迟、丢包、损坏、BPF） | troubleshooting_injection |
|
||
| `ExecuteMultipleDeviceConfigCommands` | `config_tools_nornir.py` | 批量执行设备配置变更 | troubleshooting_injection |
|
||
| `ExecuteMultipleDeviceCommands` | `display_tools_nornir.py` | 读取设备配置（只读） | troubleshooting_injection |
|
||
| `GNS3TopologyTool` | `gns3_client` | 获取项目拓扑信息 | troubleshooting_injection |
|
||
|
||
## 故障注入 API
|
||
|
||
| 端点 | 功能 |
|
||
|---|---|
|
||
| `POST /v3/projects/{pid}/chat/inject` | 触发故障注入，设置 `troubleshooting_injection` 模式后启动 Agent |
|
||
|
||
**前置条件**：项目必须为 `opened` 状态，否则返回 403。
|
||
|
||
## GNS3PacketFilterTool 链路滤波器
|
||
|
||
| 滤波器类型 | 功能 | 参数 |
|
||
|---|---|---|
|
||
| `delay` | 延迟 + 抖动 | `[latency(0-32767), jitter(0-32767)]` |
|
||
| `packet_loss` | 丢包率 | `[chance(0-100)]` |
|
||
| `corrupt` | 包损坏率 | `[chance(0-100)]` |
|
||
| `frequency_drop` | 每 N 包丢弃一个 | `[frequency(-1~32767)]` |
|
||
| `bpf` | Berkeley Packet Filter | 表达式文本 |
|
||
|
||
## Agent 工作流（LangGraph）
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant U as User
|
||
participant API as POST /chat/inject
|
||
participant LLM as LLM Node
|
||
participant Topo as GNS3TopologyTool
|
||
participant DC as ExecuteMultipleDeviceCommands
|
||
participant CC as ExecuteMultipleDeviceConfigCommands
|
||
participant Skill as InjectionSkillsTool
|
||
participant Filter as GNS3PacketFilterTool
|
||
|
||
U->>API: 注入一个OSPF故障
|
||
API->>LLM: 设置mode=troubleshooting_injection
|
||
LLM->>Topo: 获取拓扑
|
||
Topo-->>LLM: 拓扑信息
|
||
LLM->>DC: 查看设备配置
|
||
DC-->>LLM: Running配置
|
||
LLM->>Skill: list context=["ospf"]
|
||
Skill-->>LLM: 匹配的故障类型
|
||
LLM->>Skill: get device_type=injection_ospf
|
||
Skill-->>LLM: 故障定义+注入命令
|
||
LLM->>CC: 执行配置注入
|
||
CC-->>LLM: 注入结果
|
||
LLM->>Filter: set filters={delay:[200,50]}
|
||
Filter-->>LLM: 链路延迟注入成功
|
||
LLM-->>U: 故障已注入，含恢复命令
|
||
```
|
||
|
||
## 关键设计要点
|
||
|
||
1. **专用 API 入口** — `POST /chat/inject` 端点专门用于故障注入，自动切换为 `troubleshooting_injection` 模式
|
||
2. **LLM 主导故障选型** — LLM 分析拓扑后通过 `InjectionSkillsTool` 查询匹配协议栈的故障，不硬编码故障场景
|
||
3. **双层注入** — 设备级配置变更 + 链路级网络损伤，覆盖完整排错场景
|
||
4. **故障可逆** — 每条注入均附带恢复命令，链路滤波器可通过 `action: clear` 一键清除
|
||
5. **安全前置** — BPF 语法通过 tshark 预验证，配置命令受 `command_filter` 限制
|
||
6. **上下文过滤** — `InjectionSkillsTool` 强制要求传入 `context` 参数，只返回与拓扑协议匹配的故障
|