# 网络设备配置自动备份平台

**Repository Path**: yys1314/test

## Basic Information

- **Project Name**: 网络设备配置自动备份平台
- **Description**: 项目描述：
基于 Python FastAPI + Vue.js 开发的网络设备配置自动备份管理系统，支持 Cisco、华为、H3C 等多品牌网络设备的配置自动备份、版本对比和集中管理。
技术栈：
后端：Python 3.8+、FastAPI、SQLAlchemy、MySQL、Netmiko
前端：Vue 3、Element Plus、Vite、Axios
其他：APScheduler（定时任务）
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-29
- **Last Updated**: 2026-06-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 网络设备配置备份平台

一个面向网络运维场景的轻量平台，用于集中管理设备、执行配置备份、查看历史版本、做差异对比，并提供基础健康检查与 AI 辅助分析能力。

技术栈：`FastAPI + SQLAlchemy + APScheduler + Netmiko/Paramiko`，前端管理台位于 `art-lnb-master`，基于 `Vue 3 + Vite + Element Plus + Element Plus X + Pinia`。

## 功能概览

- 设备管理：新增、编辑、删除网络设备，支持多厂商设备类型。
- 配置备份：支持手动触发、定时调度、历史记录查看与删除。
- 备份清理：按策略清理过期备份。
- 配置对比：支持备份差异对比、筛选、复制、下载和 AI 摘要。
- 健康检查：支持 Linux/服务器健康采集、定时任务和前端展示。
- AI 助手：支持基于最新备份或 Linux 实时快照的问答分析。
- 网络拓扑：支持表格视图和力导图视图查看邻接关系。

## 最近改动

- 新增 Linux SSH 设备类型与实时采集能力。
- AI 对话支持本次会话上下文，不落库。
- AI 支持结构化输出与诊断模式展示。
- Agent V2 新增设备连通性诊断能力，可自动调用设备测试接口输出 TCP / SSH / 配置读取三阶段结果。
- Agent V2 新增备份失败排障能力，可基于真实备份记录分析失败阶段、失败原因和排查建议。
- 优化备份对比页面与 AI 对话页面交互，AI 页面已接入 Element Plus X 组件。
- 新增健康检查页面。
- 优化网络拓扑页面，支持表格视图与力导图切换。
- 顶部头像入口已隐藏。
- `系统信息` 页面入口已移除。

## 技术栈

- 后端：FastAPI、SQLAlchemy、APScheduler、Netmiko、Paramiko
- 前端：Vue 3、Vite、Element Plus、Element Plus X、Pinia、Axios
- 数据库：当前初始化脚本按 PostgreSQL 使用

## 目录结构

- `backend`：后端服务代码
- `art-lnb-master`：前端管理台
- `backups`：备份文件目录
- `logs`：运行日志目录
- `init_db.sql`：数据库初始化脚本
- `update_db.sql`：数据库升级脚本
- `start.bat` / `start.sh`：启动脚本
- `requirements.txt`：后端依赖

## 快速开始

1. 创建数据库并执行 `init_db.sql`。
2. 复制环境变量模板并修改数据库等配置。

```bash
# Windows
copy env.example .env

# macOS/Linux
cp env.example .env
```

3. 安装并启动后端。

```bash
# Windows
python -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt
python -m backend.main
```

```bash
# macOS/Linux
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m backend.main
```

也可以直接使用启动脚本：

```bash
# Windows
start.bat

# macOS/Linux
./start.sh
```

4. 启动前端开发环境。

```bash
cd art-lnb-master
npm install
npm run dev
```

5. 生产构建。

```bash
cd art-lnb-master
npm run build
```

## 访问地址

- 后端：`http://localhost:8000`
- API 文档：`http://localhost:8000/docs`
- 前端开发地址：`http://localhost:3006` 或 Vite 控制台输出端口

## 支持的设备类型

- Cisco IOS / IOS XE / ASA
- Huawei / VRP
- H3C（Comware）
- Juniper JunOS
- Arista EOS
- Linux SSH
- 其他设备可尝试 `autodetect`

## UI 组件说明

- `Element Plus`：用于后台管理台的基础界面组件，例如表格、表单、抽屉、弹窗、标签页、统计卡片等。
- `Element Plus X`：用于 AI 对话增强场景，适合承载消息流、结构化问答展示和更贴近聊天体验的交互组件。
- 当前项目中，常规运维页面以 `Element Plus` 为主，AI 对话页在此基础上引入了 `Element Plus X`。

### Element Plus X 安装

在前端目录 `art-lnb-master` 下执行：

```bash
npm install @element-plus/icons-vue element-plus element-plus-x
```

如果你已经安装了 `element-plus`，也可以只安装 `element-plus-x`：

```bash
cd art-lnb-master
npm install element-plus-x
```

安装完成后重新启动前端开发环境：

```bash
cd art-lnb-master
npm run dev
```
## AI 能力说明

- AI 接口：`/api/ai/ask`
- 支持来源：最新备份、指定备份、Linux 实时采集
- 支持模式：自动、结构化、诊断、纯文本
- 当前会话上下文仅保存在前端会话中，不写入数据库

## Agent 能力说明

- Agent V2 运行接口：`/api/agent/v2/run`
- Agent V2 会话恢复接口：`/api/agent/v2/session/{session_id}`
- Agent V2 审批接口：
  - `POST /api/agent/v2/approve`
  - `POST /api/agent/v2/reject`
- 当前定位：基于真实设备数据的受控只读编排器，不是开放式闲聊机器人

### Agent 框架说明

当前项目已经内置一套面向网络运维场景的 `Agent V2` 框架，不是单纯把大模型问答接口直接暴露给前端。

### Agent 与 LLM 的关系说明

当前项目中同时存在两类 Agent 形态，它们和 LLM 的关系不同：

- 旧版 Agent：
  - 入口：`/api/agent/run`
  - 实现位置：`backend/agent_service.py`
  - 运行方式：`LLM + Tool Calling`
  - 特点：由模型决定下一步调用哪个工具，适合通用型多步问答与工具编排
  - 是否依赖 LLM：`是`
- Agent V2：
  - 入口：`/api/agent/v2/run`
  - 实现位置：`backend/agent/runtime.py`、`backend/agent/nodes.py`、`backend/agent/tools.py`
  - 运行方式：`规则驱动 + 状态驱动 + 工具编排`
  - 特点：优先依赖真实设备数据、规则识别和受控工具执行，强调可解释和可控
  - 是否依赖 LLM：`当前主流程不强依赖`

也就是说：

- 旧版 Agent 是 `LLM 驱动 Agent`
- Agent V2 是 `规则驱动 Agent`

当前项目主推的是 `Agent V2`，因为它更符合网络运维场景对“真实数据依据、结果可控、拒绝百科式回答”的要求。

后续推荐演进方向是：

- 保持 Agent V2 的受控执行框架不变
- 在 Agent V2 前面增加 `LLM 辅助理解层`
- 让 LLM 主要负责：
  - 设备名称识别
  - 意图识别
  - 关键词提取
  - 结构化总结
  - 证据解释
- 让规则、工具和审批继续负责：
  - 数据取证
  - 风险控制
  - 工具执行
  - 变更审批

### Agent 架构流程图（ASCII）

```text
+----------------------+
|      Frontend UI     |
|  AI Chat / Agent UI  |
+----------+-----------+
           |
           v
+----------------------+
|      FastAPI API     |
| /api/ai/ask          |
| /api/agent/run       |
| /api/agent/v2/run    |
+----------+-----------+
           |
           +----------------------------------+
           |                                  |
           v                                  v
+----------------------+        +------------------------------+
|  旧版 Agent          |        |  Agent V2                    |
| backend/agent_service|        | backend/agent/runtime.py     |
|                      |        | backend/agent/nodes.py       |
| LLM + Tool Calling   |        | Rule + State + Tools         |
+----------+-----------+        +---------------+--------------+
           |                                    |
           v                                    v
+----------------------+        +------------------------------+
|  LLM Client Router   |        |   Device Resolve / Intent    |
| backend/ollama_service|       |   Tool Plan / Run Tools      |
+----------+-----------+        |   Finalize / Approval        |
           |                    +---------------+--------------+
           |                                    |
     +-----+------+                             |
     |            |                             |
     v            v                             v
+---------+   +----------------+     +--------------------------+
| Ollama  |   | Online LLM     |     | Agent Tools              |
| Local   |   | OpenAI-compatible |  | list_devices             |
+---------+   +----------------+     | get_device_latest_config |
                                      | search_in_latest_config |
                                      | compare_backups         |
                                      | get_latest_health       |
                                      | test_device_connectivity|
                                      | diagnose_backup_failure |
                                      +------------+-------------+
                                                   |
                                                   v
                                      +--------------------------+
                                      | Real Data Sources        |
                                      | PostgreSQL               |
                                      | Backups                  |
                                      | Health Checks            |
                                      | Netmiko / Paramiko       |
                                      | Real Devices             |
                                      +--------------------------+
```

说明：

- 左侧是 `旧版 Agent`，核心是 `LLM 驱动`
- 右侧是 `Agent V2`，核心是 `规则驱动 + 工具编排`
- `LLM Client Router` 已支持在 `Ollama` 和 `Online LLM` 之间切换
- `Agent V2` 当前直接依赖真实数据源和工具结果，不依赖开放式模型自由推理

- Agent 框架使用的核心技术：
  - 后端框架：`FastAPI`
  - 数据访问：`SQLAlchemy`
  - 数据库存储：`PostgreSQL`
  - 设备连接与命令执行：`Netmiko`、`Paramiko`
  - 定时能力与任务基础设施：`APScheduler`
  - Agent 编排技术：`LangGraph`
  - Agent 当前运行方式：项目内顺序编排器，已与 `LangGraph` 状态模型和图骨架保持兼容
  - 大模型接入方式：当前默认对接本地 `Ollama`，并已预留在线 `LLM` 适配层
  - 前端页面技术：`Vue 3`、`Vite`
  - 前端 UI 组件：`Element Plus`、`Element Plus X`
  - 前后端通信：`Axios + REST API`

- 框架核心流程：
  - `设备解析`：先识别用户问题对应的目标设备
  - `意图识别`：判断是配置读取、关键字检索、备份对比、健康检查、连通性诊断还是备份失败排障
  - `工具规划`：根据意图生成受控工具调用计划
  - `工具执行`：调用现有后端能力和真实业务接口
  - `结果格式化`：把原始结果整理成结构化表格、摘要、证据和建议
  - `审批闭环`：高风险请求进入审批状态，由前端确认后继续
- 框架设计原则：
  - 只基于真实设备数据回答，不输出脱离现场数据的百科式结论
  - 优先复用现有接口、备份服务、健康检查和设备测试能力
  - Agent 当前以只读分析和诊断编排为主，不直接执行真实配置下发
  - 所有能力都以可扩展工具形式接入，便于后续继续增加新 Agent 场景
  - 当前代码已经预留 `LangGraph` 图编排入口，后续可逐步从顺序执行迁移到图执行
- 当前框架适合继续扩展的方向：
  - 配置证据问答
  - 拓扑诊断
  - 健康异常总结
  - 基线核查
  - 变更提案与审批执行

### 在线 LLM 预留接入

项目已经预留在线模型适配文件：

- `backend/llm/online_provider.py`

该文件当前用于统一在线模型接入方式，主要特点：

- 采用统一的 `request / response` 数据结构
- 默认按 `OpenAI-compatible Chat Completions` 协议封装
- 可作为以下在线模型的统一入口：
  - `OpenAI`
  - `通义千问在线版`
  - `DeepSeek 在线版`
  - 其他兼容 OpenAI 协议的模型网关
- 已接入统一模型路由，支持与本地 `Ollama` 进行切换

已预留环境变量：

- `ONLINE_LLM_ENABLED`
- `ONLINE_LLM_BASE_URL`
- `ONLINE_LLM_API_KEY`
- `ONLINE_LLM_MODEL`
- `ONLINE_LLM_TIMEOUT`
- `ONLINE_LLM_TEMPERATURE`

如果后续要正式切换到在线模型，建议方式是：

1. 在 `.env` 中配置上述 `ONLINE_LLM_*` 参数
2. 通过 `ONLINE_LLM_ENABLED=true` 打开在线模型
3. 保留本地 `Ollama` 作为回退模型，避免在线服务不可用时影响平台能力

### 模型切换说明

当前项目默认使用本地 `Ollama`。如果后续要切换到在线 `LLM`，建议按下面方式操作。

#### 1. 使用本地 Ollama

在 `.env` 中保持或设置以下参数：

```env
OLLAMA_BASE_URL=http://127.0.0.1:11434
OLLAMA_MODEL=deepseek-r1:1.5b
OLLAMA_API_KEY=
OLLAMA_TIMEOUT=120
OLLAMA_TEMPERATURE=0.2
ONLINE_LLM_ENABLED=false
```

说明：

- 当 `ONLINE_LLM_ENABLED=false` 时，系统会继续走本地 `Ollama` 链路
- 适合离线环境、内网环境和低成本本地部署场景

#### 2. 切换到在线 LLM

在 `.env` 中配置以下参数：

```env
ONLINE_LLM_ENABLED=true
ONLINE_LLM_BASE_URL=https://your-llm-gateway.example.com/v1
ONLINE_LLM_API_KEY=your_api_key
ONLINE_LLM_MODEL=your_model_name
ONLINE_LLM_TIMEOUT=60
ONLINE_LLM_TEMPERATURE=0.2
```

说明：

- `ONLINE_LLM_BASE_URL` 当前按 `OpenAI-compatible` 协议预留
- 实际请求地址会拼接为：
  - `{ONLINE_LLM_BASE_URL}/chat/completions`
- 可用于接入：
  - `OpenAI`
  - `通义千问在线版`
  - `DeepSeek 在线版`
  - 其他兼容 OpenAI 协议的模型服务

#### 3. 推荐切换策略

- 开发环境：默认使用本地 `Ollama`
- 生产环境：优先接在线 `LLM`
- 生产环境建议保留本地 `Ollama` 作为回退模型
- 在线模型不可用时，建议自动回退到本地模型，避免 AI/Agent 能力整体不可用

#### 4. 当前代码状态说明

目前仓库已经完成：

- 在线模型适配文件预留：`backend/llm/online_provider.py`
- 在线模型配置项预留：`backend/config.py`
- 在线模型环境变量模板预留：`env.example`
- 模型统一路由已接入：`backend/ollama_service.py`
- AI 问答与旧版 Agent 已接入统一 `build_client()` 切换逻辑

当前切换规则：

- `ONLINE_LLM_ENABLED=true` 且在线模型配置完整时，优先走在线 `LLM`
- 否则自动回退到本地 `Ollama`

### 当前已实现的 Agent 能力

- 设备识别：
  - 支持前端手动选择设备
  - 支持在问题中写设备名称或 hostname 进行自动识别
  - 未锁定设备时，可先返回设备列表供用户确认
- 意图识别：
  - 读取最近配置
  - 检索配置关键字
  - 对比最近两次备份
  - 读取最新健康检查
  - 识别高风险变更类请求并进入审批流
- 只读工具编排：
  - `list_devices`
  - `get_device_latest_config`
  - `search_in_latest_config`
  - `compare_latest_two_backups`
  - `get_latest_health`
  - `test_device_connectivity`
  - `diagnose_backup_failure`
- 结构化结果输出：
  - 设备列表表格
  - 配置元信息表格
  - 关键字命中表格
  - 备份差异摘要表格
  - 健康检查摘要表格
  - 设备连通性诊断表格
  - 配置预览与片段展示
- 设备连通性诊断：
  - 可直接通过自然语言触发，例如 `测试 AR1 能不能连`
  - 推荐问法示例：
    - `测试 AR1 能不能连`
    - `检查 OpenClaw 的 SSH 是否正常`
    - `看一下核心交换机现在能不能通过 SSH 登录`
    - `帮我诊断 R1 的 22 端口、SSH 和配置读取是否正常`
    - `测试一下 BRAS-01 的设备连通性并给出排查建议`
  - Agent 会自动调用已有接口 `POST /api/devices/{id}/test`
  - 输出 `TCP 22 是否通`、`SSH 登录是否成功`、`配置读取是否成功`
  - 返回失败阶段、失败原因和排查建议
- 备份失败排障：
  - 可直接通过自然语言触发，例如 `为什么 AR1 最近备份失败`
  - 推荐问法示例：
    - `为什么 AR1 最近备份失败`
    - `排查 OpenClaw 最近一次备份失败原因`
    - `分析这台设备最近备份异常`
    - `帮我看下这台设备备份失败在哪个阶段`
  - Agent 会读取最近失败备份记录和最近 5 次备份状态
  - 自动判断失败阶段，例如 `TCP 连通性`、`SSH 认证`、`配置读取`
  - 会识别是否为单次失败、持续失败或失败后未恢复
  - 对连接类或认证类问题，会自动追加一次当前连通性复测
  - 返回失败类别、失败原因、诊断证据和排查建议
- 会话能力：
  - 每次 Agent 运行生成 `session_id`
  - 页面刷新后可恢复最近一次 Agent V2 会话
  - 当前恢复的是最近一次 Agent 任务，不是完整多轮历史
- 审批状态管理：
  - 支持 `pending / approved / rejected`
  - 前端支持对高风险会话进行批准或拒绝
  - 审批结果会写回当前会话状态并同步显示到页面

### 当前约束

- Agent 回答仍然以真实设备数据为依据：
  - 有真实备份、实时采集或健康检查数据时才回答
  - 没有真实依据时，会拒绝输出通用百科式内容
- 当前 Agent V2 仍以只读分析为主
- 审批闭环已打通，但批准后暂未执行真实配置下发
- 真实配置生成、真实设备变更执行、自动回滚链路仍属于后续阶段

## 运行说明

- 备份目录可通过 `BACKUP_DIR` 配置。
- 健康检查周期可通过 `HEALTH_CHECK_INTERVAL_HOURS` 配置。
- 生产环境应修改 `SECRET_KEY` 并限制 CORS 来源。
- 后端热重载已排除 `logs/*.log`，避免日志变化触发反复重载。

## License

This project is licensed under the Apache License 2.0.
See `LICENSE` for details.