内容
# giorria
**giorria** (爱尔兰语：*hare*) 是一个完全可复制的网络自动化实验室，它将全 Arista cEOS 拓扑结构与一个基于 [模型上下文协议（MCP）](https://modelcontextprotocol.io/) 构建的 AI 驱动的操作平台配对。
该实验室演示了如何在开源基础设施上构建自然语言网络操作工具 - 离线配置分析、实时遥测、结构化审计跟踪和 AAA 会计 - 将它们连接起来，以便语言模型可以回答诸如 *"哪些 BGP 会话未建立？"* 或 *"自上次有意义的更改以来，请显示配置差异"* 之类的问题，并使用真实的网络数据。
---
## 内容列表
| 组件 | 技术 | 目的 |
|---|---|---|
| 网络实验室 | Containerlab + Arista cEOS 4.35.1F | 6 节点脊叶结构，两台 AS，fabric 互联对等 |
| 离线分析 | [Batfish](https://www.batfish.org/) + pybatfish | 配置验证，BGP 拓扑，访问性，路由表 |
| 事实存储 | PostgreSQL | 由摄入管道填充的标准化网络状态 |
| 配置备份 | [Oxidized](https://github.com/ytti/oxidized) | 轮询所有设备，在更改时触发 Batfish 管道 |
| 对象存储 | MinIO | 快照存档（ZIP） |
| 遥测 | gNMIc + Prometheus | OpenConfig 接口计数器，系统状态 |
| 日志记录 | Grafana Loki | 结构化管道审计跟踪，TACACS+ 会计 |
| 仪表盘 | Grafana | 预配置的数据源（Prometheus + Loki） |
| AAA | TACACS+ | 所有 6 台设备的身份验证和命令会计 |
| MCP 服务器 | FastMCP（Python） | 上述所有 LLM 可访问的工具 |
---
## 拓扑结构
```
结构 A （AS 65100 / 65101 / 65102） 结构 B （AS 65200 / 65201 / 65202）
arista-spine1 172.100.100.2 arista-spine2 172.100.100.3
Eth1 10.1.1.0/31 Eth1 10.2.0.0/31
Eth2 10.1.2.0/31 Eth2 10.2.0.2/31
Eth3 10.99.0.0/31 --- fabric 互联 --------- Eth3 10.99.0.1/31
| |
+---------+ +---------+---------+
| | | |
arista- arista- arista-leaf3 arista-leaf4
leaf1 leaf2 （AS 65201） （AS 65202）
（65101） （65102）
```
管理网络：`172.100.100.0/24`（由 Containerlab 创建为 `clab-mgmt`）
---
## 快速入门
### 1. 先决条件
- Docker + Docker Compose
- [Containerlab](https://containerlab.dev/install/)
- Arista cEOS 4.35.1F 镜像（参见 [lab/README.md](lab/README.md) 以获取如何获取它）
### 2. 导入 cEOS 镜像
```bash
docker import cEOS-lab-4.35.1F.tar.xz ceos:4.35.1F
```
### 3. 配置环境变量
```bash
python3 configure.py
```
脚本询问实验室密码和 TACACS+ 共享密钥（或为您生成两者），然后编写所有 `.env` 文件，并使用选择的密码修补设备启动配置、Oxidized 凭证和 gNMIc 凭证。
> **重要：** 在部署实验室之前运行此操作 - 它修补了 Containerlab 绑定安装到每个容器中的设备启动配置。
### 4. 部署网络实验室
```bash
cd lab/
sudo containerlab deploy -t topology.yml --reconfigure
cd ..
```
> `--reconfigure` 标志强制 cEOS 容器从绑定的 `.cfg` 文件中重新应用其启动配置。 如果没有它，容器将重用从以前部署中保留在闪存中的内容，并且配置更改将被静默忽略。
这创建了 `clab-mgmt` Docker 网络，所有服务都连接到该网络。
### 5. 启动堆栈
```bash
docker compose \
--profile core \
--profile observability \
--profile oxidized \
--profile tacacs \
up -d
```
### 6. 运行 MCP 服务器
```bash
cd network-mcp/
# 使用 uv 安装（推荐）
uv sync
uv run network-mcp
# 或使用 pip
pip install -e .
network-mcp
```
服务器监听 `http://localhost:8080/mcp`（可流式 HTTP 传输）。 将 Claude Desktop 或任何 MCP 兼容的客户端指向该 URL。
---
## 服务端口
| 服务 | 端口 | 备注 |
|---|---|---|
| MCP 服务器 | 8080 | 可流式 HTTP -- `http://localhost:8080/mcp` |
| pgAdmin | 8006 | PostgreSQL 浏览器 |
| MinIO 控制台 | 8005 | 对象存储 UI |
| MinIO S3 API | 8004 | |
| Oxidized | 8888 | Web UI + REST API |
| Grafana | 3000 | 仪表盘 |
| Prometheus | 9090 | 指标 |
| Loki | 3100 | 日志聚合 |
| Batfish | 9996 | 配置分析 API |
| PostgreSQL | 5432 | 事实存储 |
| TACACS+ | 49/tcp | AAA |
---
## Compose 配置文件
| 配置文件 | 服务 |
|---|---|
| `core` | Batfish, PostgreSQL, pgAdmin, MinIO, 摄入管道 |
| `observability` | Loki, Prometheus, gNMIc, Grafana |
| `oxidized` | Oxidized 配置备份守护进程 |
| `tacacs` | TACACS+ 服务器 + Promtail 日志分发器 |
---
## 管道工作原理
```
Arista 设备配置更改
|
v
Oxidized 轮询并存储在 git 中
| 存储后钩子
v
export-to-batfish.sh
将 .cfg 写入共享卷
| HTTP POST
v
摄入（FastAPI）
+-- 存档配置
+-- 运行 Batfish 分析
+-- 将事实写入 PostgreSQL
+-- 将快照 ZIP 上传到 MinIO
| 结构化事件
v
Loki（审计跟踪）
```
MCP 服务器首先查询 PostgreSQL（无需联系设备），仅当需要实时状态时才会升级到实时 eAPI 调用。
---
## MCP 工具类别
| 前缀 | 源 | 使用场景 |
|---|---|---|
| `netlab_*` | PostgreSQL 事实存储 | 库存、接口、BGP、路由 - 首先使用 |
| `arista_*` | 实时 eAPI | 实时计数器、运行配置、任意显示命令 |
| `batfish_*` | Batfish | 可达性、配置验证、离线拓扑分析 |
| `loki_*` | Loki | 管道审计跟踪、故障分析、按节点历史记录 |
| `prometheus_*` | Prometheus | gNMI 接口计数器、系统遥测 |
| `tacacs_*` | Loki（TACACS 流） | AAA 审计 - 谁登录了，运行了哪些命令 |
---
## 仓库布局
```
giorria/
+-- compose.yml # 所有服务，配置文件控制
+-- configure.py # 一次性设置：生成 .env 文件，修补配置
+-- .env.example # 根环境模板
+-- lab/ # Containerlab 拓扑结构 + 设备配置
+-- ingest/ # FastAPI 管道协调器 + Dockerfile
+-- oxidized/ # Oxidized 配置示例，router.db，钩子脚本
+-- collector/ # Prometheus、Loki、gNMIc、Grafana 配置
| +-- gnmic.example.yml # gNMIc 模板（configure.py 生成 gnmic.yml）
+-- tacacs/ # TACACS+ 服务器（Python RFC 8907 实现）
+-- network-mcp/ # MCP 服务器（FastMCP，Python，pyproject.toml）
+-- src/network_mcp/
+-- server.py # 工具定义
+-- config.py # 环境驱动的配置
+-- arista_tools.py # 实时 eAPI 查询
+-- batfish_tools.py # 离线配置分析
+-- postgres_tools.py# 事实存储查询
+-- loki_tools.py # 审计跟踪查询
+-- prometheus_tools.py # gNMI 遥测
+-- tacacs_tools.py # AAA 审计查询
```
---
## 文档
| 指南 | 描述 |
|---|---|
| [代理说明](docs/agent-instructions.md) | MCP 客户端的推荐系统提示 - 工具优先级和故障排除工作流 |
| [Grafana 查询参考](docs/grafana-queries.md) | 用于 Grafana Explore 的示例 Loki 和 Prometheus 查询 |
---
## 许可证
MIT - 参见 [LICENSE](LICENSE)。
