AI-Agent/ipam
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases 3 Wiki Activity

readme

Browse Source
This commit is contained in:
Your Name
2026-07-20 13:40:05 +08:00
parent 9e34f6f0f9
commit bca0da7c7d
12 changed files with 1609 additions and 525 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+355 -234
View File
@@ -1,277 +1,398 @@
# IPAM 管理系统 - 完整功能
# IPAM 管理系统
企业级 IP 地址管理系统，支持自动化扫描、发现和管理网络 IP 资产。
## ✅ 已完成功能
---
### 🎯 P0 - 核心功能
- ✅ **FastAPI 后端框架** - 高性能 RESTful API
- ✅ **MySQL 数据库** - 持久化存储
- ✅ **Redis 缓存** - 任务队列和缓存
- ✅ **网段管理** - CIDR 网段增删改查，自动创建 IP 记录
- ✅ **IP 资产台账** - IP 地址全生命周期管理
- ✅ **Ping 扫描引擎** - ICMP 在线状态检测
## ✨ 功能特性
### 🚀 P1 - 高级功能
- ✅ **ARP 扫描** - 获取 MAC 地址
- ✅ **反向 DNS 解析** - 获取主机名
- ✅ **MAC 厂商识别** - 内置 OUI 数据库
- ✅ **Celery 异步任务** - 后台并发扫描
- ✅ **SNMP 设备集成**
- SNMP v2c/v3 支持
- 设备连接测试
- ARP 表自动采集
- 接口信息采集
- ✅ **告警与异常检测**
- IP 冲突告警
- 未授权接入检测
- 网段耗尽预警
- 设备离线告警
- 新设备发现告警
- MAC 地址白名单
### 核心管理
- **网段管理** - CIDR 网段创建、分组、自动生成 IP 列表、使用率监控
- **IP 资产台账** - 在线/离线/空闲/保留状态管理、MAC地址、主机名、厂商识别、使用人/业务标注
- **搜索筛选** - 按网段、状态、IP/MAC/主机名快速搜索
### 🎨 P2 - 前端界面
- ✅ **Vue 3 + Element Plus** - 现代化 UI 框架
- ✅ **仪表盘** - 统计概览、网段使用率、告警统计
- ✅ **网段管理** - 网段 CRUD、扫描、导出
- ✅ **IP 地址管理** - 筛选、搜索、编辑
- ✅ **扫描管理** - 综合扫描、结果导出
- ✅ **SNMP 管理** - 设备、凭据、ARP 表
- ✅ **告警中心** - 告警列表、统计、白名单
### 智能扫描
- **ICMP Ping 扫描** - 快速检测在线状态
- **ARP 扫描** - 二层网络 MAC 地址发现
- **反向 DNS 解析** - 自动获取主机名
- **MAC 厂商识别** - 内置 IEEE OUI 数据库，识别 3000+ 设备厂商
- **异步任务执行** - Celery 后台并发扫描，不阻塞 Web 服务
## 🚀 快速启动
### SNMP 网络设备集成
- **多版本支持** - SNMPv2c (Community)、SNMPv3 (认证+加密)
- **自动采集** - ARP 表、接口表、设备信息
- **设备状态** - 轮询状态监控、在线/离线检测
### 方式一：使用启动脚本（推荐）
### 告警与异常检测
- **IP 冲突告警** - 同一 IP 对应多个 MAC 地址
- **未授权接入检测** - 新接入设备不在白名单内自动告警
- **网段耗尽预警** - 网段使用率超阈值告警
- **设备离线告警** - 网络设备长时间不在线告警
- **MAC 白名单** - 可信设备免告警
### 用户与安全
- **JWT 身份认证** - Token 登录、自动刷新
- **4 级角色权限** - 只读 / 操作员 / 管理员 / 超级管理员
- **操作审计日志** - 全量操作记录、可追溯查询
- **密码加密存储** - bcrypt 加密
### 报表与导出
- **CSV 格式导出** - IP 地址表、网段汇总、告警记录、SNMP 设备、ARP 表
- **系统汇总报表** - IP 使用率、在线率、告警统计、网段分布
---
## 🚀 快速开始
### 环境要求
- Python 3.11+
- MySQL 8.0+
- Redis 6.0+
- Node.js 18+
### 一键启动所有服务
#### 方式一：使用启动脚本（推荐）
```bash
cd /root/ipam
# 启动所有服务
chmod +x start.sh
./start.sh
```
### 方式二：手动启动
#### 方式二：手动启动
**1. 启动数据库和缓存**
#### 安装依赖环境
```bash
# MySQL 已运行在 3308 端口
# Redis 已运行在 6379 端口
cd /root/ipam/backend
source venv/bin/activate
pip install "pysnmp==4.4.12" "pyasn1<0.5.0" "pysmi<0.4.0"
apt install -y celery
```
**2. 启动后端服务**
##### 1️⃣ 启动后端 API 服务
```bash
cd /root/ipam/backend
source venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8008
```
**3. 启动 Celery Worker**
##### 2️⃣ 启动 Celery Worker（执行扫描任务）
```bash
cd /root/ipam/backend
source venv/bin/activate
celery -A app.tasks.celery_app worker --loglevel=info --concurrency=4
```
**4. 启动前端服务**
##### 3️⃣ 启动 Celery Beat（定时任务调度器，自动扫描必须启动）
```bash
cd /root/ipam/backend
source venv/bin/activate
celery -A app.tasks.celery_app beat --loglevel=info
```
##### 4️⃣ 启动前端
```bash
cd /root/ipam/frontend
npm install
npm run dev -- --host 0.0.0.0 --port 3000
```
---
## ⏰ 自动扫描配置
### 扫描频率配置
系统默认配置了 **3 个定时扫描任务**：
| 任务名称 | 执行频率 | 扫描内容 | 说明 |
|----------|----------|----------|------|
| **每小时全量扫描** | 每 60 分钟 | Ping + ARP + DNS | 快速刷新在线状态 |
| **每日深度扫描** | 每天凌晨 02:00 | Ping + ARP + DNS | 每日完整扫描更新 |
| **统计更新** | 每 15 分钟 | 仅更新统计 | 更新网段使用率 |
### 如何自定义扫描频率
编辑配置文件：`/root/ipam/backend/app/tasks/celery_app.py`
```python
# 定时任务配置 (第 36-55 行)
celery_app.conf.beat_schedule = {
# 每小时执行一次全量扫描
'full-scan-every-hour': {
'task': 'app.tasks.scan_tasks.full_network_scan',
'schedule': 3600.0, # 单位：秒，修改此值调整频率
'args': (True, True, True) # (启用Ping, 启用ARP, 启用DNS)
},
# 每天凌晨2点执行深度扫描
'full-scan-daily': {
'task': 'app.tasks.scan_tasks.full_network_scan',
'schedule': crontab(hour=2, minute=0), # 修改 hour/minute 调整时间
'args': (True, True, True)
},
# 每15分钟更新统计
'update-stats-every-15min': {
'task': 'app.tasks.scan_tasks.update_all_statistics',
'schedule': 900.0, # 单位：秒
},
}
```
**常用配置示例：**
```python
# 每 30 分钟扫描一次
'schedule': 1800.0
# 每天凌晨 3:30 扫描
'schedule': crontab(hour=3, minute=30)
# 工作日上午 9 点扫描
'schedule': crontab(hour=9, minute=0, day_of_week='mon-fri')
# 仅扫描 Ping，不扫描 ARP 和 DNS
'args': (True, False, False)
```
**⚠️ 注意：修改配置后必须重启 Celery Worker 和 Celery Beat 才会生效！**
### 扫描任务包含的内容
每次完整扫描会执行以下操作：
1. **ICMP Ping** - 检测 IP 是否在线
2. **ARP 扫描** - 获取 MAC 地址（同网段有效）
3. **反向 DNS** - 解析主机名
4. **MAC 厂商识别** - 根据 MAC 地址前 3 字节识别厂商
5. **自动更新** - 更新 IP 状态、MAC、主机名、最后发现时间
6. **异常检测** - 触发 IP 冲突、未授权接入等告警检查
### 监控定时任务状态
#### 查看 Celery 活跃任务
```bash
cd /root/ipam/backend
source venv/bin/activate
celery -A app.tasks.celery_app inspect active
```
#### 查看定时任务调度
```bash
celery -A app.tasks.celery_app inspect scheduled
```
#### 查看 Worker 状态
```bash
celery -A app.tasks.celery_app inspect stats
```
---
## 🛠️ 生产环境部署建议
### 使用 Systemd 管理服务（开机自启）
#### 1. 创建 IPAM API 服务
```ini
# /etc/systemd/system/ipam-api.service
[Unit]
Description=IPAM API Service
After=network.target mysql.service redis.service
[Service]
Type=simple
User=root
WorkingDirectory=/root/ipam/backend
Environment="PATH=/root/ipam/backend/venv/bin"
ExecStart=/root/ipam/backend/venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8008
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
```
#### 2. 创建 Celery Worker 服务
```ini
# /etc/systemd/system/ipam-celery-worker.service
[Unit]
Description=IPAM Celery Worker
After=network.target redis.service
[Service]
Type=simple
User=root
WorkingDirectory=/root/ipam/backend
Environment="PATH=/root/ipam/backend/venv/bin"
ExecStart=/root/ipam/backend/venv/bin/celery -A app.tasks.celery_app worker --loglevel=info --concurrency=4
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
```
#### 3. 创建 Celery Beat 服务
```ini
# /etc/systemd/system/ipam-celery-beat.service
[Unit]
Description=IPAM Celery Beat Scheduler
After=network.target redis.service
[Service]
Type=simple
User=root
WorkingDirectory=/root/ipam/backend
Environment="PATH=/root/ipam/backend/venv/bin"
ExecStart=/root/ipam/backend/venv/bin/celery -A app.tasks.celery_app beat --loglevel=info
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
```
#### 4. 启用并启动服务
```bash
# 重新加载配置
systemctl daemon-reload
# 启用开机自启
systemctl enable ipam-api ipam-celery-worker ipam-celery-beat
# 启动服务
systemctl start ipam-api ipam-celery-worker ipam-celery-beat
# 查看服务状态
systemctl status ipam-api ipam-celery-worker ipam-celery-beat
```
---
## 🌐 访问地址
| 服务 | 地址 | 说明 |
|------|------|------|
| 前端界面 | http://服务器IP:3000 | Web 管理界面 |
| 后端 API | http://服务器IP:8008 | API 服务 |
| API 文档 | http://服务器IP:8008/docs | Swagger 在线文档 |
| MySQL | 服务器IP:3308 | 数据库 |
| Redis | 服务器IP:6379 | 缓存和任务队列 |
| 管理后台 | `http://服务器IP:3000` | Vue 前端界面 |
| API 服务 | `http://服务器IP:8008` | REST API |
| Swagger 文档 | `http://服务器IP:8008/docs` | API 在线测试文档 |
| Redoc 文档 | `http://服务器IP:8008/redoc` | API 文档 |
## 📖 API 使用示例
### 1. 创建网段
```bash
curl -X POST http://localhost:8008/api/v1/networks \
-H "Content-Type: application/json" \
-d '{
"cidr": "192.168.1.0/24",
"name": "办公网络",
"group_name": "office",
"gateway": "192.168.1.1"
}'
```
### 2. 触发扫描
```bash
curl -X POST http://localhost:8008/api/v1/scan/comprehensive/1
```
### 3. 查看统计
```bash
curl http://localhost:8008/api/v1/networks/stats
```
## 🏗️ 项目结构
```
/root/ipam/
├── backend/ # 后端代码
│ ├── app/
│ │ ├── api/ # API 路由
│ │ │ └── v1/
│ │ │ ├── networks.py # 网段管理
│ │ │ ├── ips.py # IP管理
│ │ │ ├── scan.py # 扫描管理
│ │ │ ├── enhanced_scan.py # 增强扫描
│ │ │ ├── snmp.py # SNMP管理
│ │ │ └── alerts.py # 告警管理
│ │ ├── core/ # 核心配置
│ │ │ ├── config.py # 配置文件
│ │ │ └── database.py # 数据库连接
│ │ ├── models/ # 数据模型
│ │ │ ├── network.py # 网段/IP/扫描任务
│ │ │ ├── snmp.py # SNMP设备/凭据
│ │ │ └── alert.py # 告警模型
│ │ ├── schemas/ # Pydantic 验证模型
│ │ │ └── network.py
│ │ ├── services/ # 业务逻辑
│ │ │ ├── network_service.py # 网段服务
│ │ │ ├── scan_service.py # Ping扫描服务
│ │ │ ├── enhanced_scan_service.py # ARP/DNS扫描服务
│ │ │ ├── snmp_service.py # SNMP服务
│ │ │ └── alert_service.py # 告警服务
│ │ ├── tasks/ # Celery 任务
│ │ │ ├── celery_app.py # Celery 应用
│ │ │ └── scan_tasks.py # 扫描任务
│ │ └── main.py # FastAPI 应用入口
│ ├── requirements.txt # Python 依赖
│ └── venv/ # Python 虚拟环境
├── frontend/ # 前端代码
│ ├── src/
│ │ ├── views/ # 页面组件
│ │ │ ├── Dashboard.vue # 仪表盘
│ │ │ ├── Networks.vue # 网段管理
│ │ │ ├── IPs.vue # IP地址
│ │ │ ├── Scan.vue # 扫描管理
│ │ │ ├── SNMP.vue # SNMP管理
│ │ │ └── Alerts.vue # 告警中心
│ │ ├── layout/ # 布局组件
│ │ │ └── MainLayout.vue # 主布局
│ │ ├── router/ # 路由配置
│ │ │ └── index.js
│ │ ├── api/ # API 客户端
│ │ │ └── index.js
│ │ ├── utils/ # 工具函数
│ │ │ └── api.js
│ │ ├── App.vue # 根组件
│ │ └── main.js # 应用入口
│ ├── package.json
│ └── vite.config.js # Vite 配置
├── docs/ # 文档
├── docker-compose.yml # Docker 配置
├── start.sh # 启动脚本
└── README.md
```
## 🔧 技术栈
### 后端
- **Web 框架**: FastAPI 0.110
- **ORM**: SQLAlchemy 2.0
- **数据库**: MySQL 8.0
- **缓存/队列**: Redis 7.0
- **异步任务**: Celery 5.3
- **SNMP**: PySNMP 4.4.12
- **网络探测**: Scapy 2.5.0
- **HTTP 客户端**: httpx
### 前端
- **框架**: Vue 3.5
- **UI 组件**: Element Plus 2.14
- **路由**: Vue Router 4.6
- **状态管理**: Pinia 4.0
- **HTTP 客户端**: Axios 1.18
- **构建工具**: Vite 5.0
## 📊 数据库表
| 表名 | 说明 |
|------|------|
| networks | 网段信息 |
| ip_addresses | IP 地址台账 |
| scan_tasks | 扫描任务记录 |
| snmp_credentials | SNMP 凭据配置 |
| network_devices | 网络设备列表 |
| arp_entries | ARP 表记录 |
| mac_address_table | MAC 地址表 |
| device_interfaces | 设备接口信息 |
| alerts | 告警记录 |
| alert_rules | 告警规则配置 |
| whitelisted_macs | MAC 地址白名单 |
## 🎯 核心特性
### 1. 智能扫描
- **ICMP Ping**: 快速检测在线状态
- **ARP 扫描**: 二层网络 MAC 发现
- **反向 DNS**: 自动解析主机名
- **并发扫描**: Celery 异步执行，不阻塞 Web 服务
### 2. SNMP 设备管理
- 支持 SNMP v2c/v3
- 自动采集 ARP 表、接口信息
- 设备连通性测试
- 轮询状态监控
### 3. 智能告警
- IP 冲突自动检测
- 未授权设备接入告警
- 网段使用率预警
- MAC 白名单机制
### 4. 厂商识别
- 内置 IEEE OUI 数据库
- 自动识别 3000+ 设备厂商
- 支持 Cisco、H3C、华为、华三等主流厂商
## 📝 开发计划
### 待实现功能 (P3)
- [ ] 历史趋势图表
- [ ] 报告导出
- [ ] 用户权限管理
- [ ] 邮件/钉钉/企业微信通知
- [ ] VLAN 自动发现
- [ ] 拓扑图自动生成
- [ ] 端口控制（关闭/开启）
- [ ] 资产变更审计日志
## 🔐 安全建议
1. **修改默认密码**
- MySQL root 密码
- Redis 密码配置
2. **配置防火墙**
- 仅开放必要端口：3000(前端)、8008(API)
- 限制 3308(MySQL)、6379(Redis) 访问来源
3. **HTTPS**
- 生产环境建议配置 Nginx 反向代理 + SSL
4. **访问控制**
- 配置 API 认证 (JWT)
- 限制管理后台访问来源
## 📞 技术支持
如有问题或建议，请查看 API 文档：
- Swagger UI: http://服务器IP:8008/docs
- ReDoc: http://服务器IP:8008/redoc
**默认管理员账号：**
- 用户名: `admin`
- 密码: `admin123`
---
**版本**: 1.0.0
**最后更新**: 2026-07-17
## 📊 技术栈
| 组件 | 技术选型 | 版本 |
|------|----------|------|
| Web 框架 | FastAPI | 0.115 |
| ORM | SQLAlchemy | 2.0 |
| 数据库 | MySQL | 8.0 |
| 异步任务 | Celery + Redis | 5.4 |
| SNMP | PySNMP | 4.4.12 |
| 密码加密 | Passlib + bcrypt | - |
| JWT 认证 | python-jose | - |
| 前端框架 | Vue 3 + Element Plus | 3.5 / 2.9 |
| 路由 | Vue Router | 4.4 |
| 状态管理 | Pinia | 2.4 |
| HTTP 客户端 | Axios | 1.7 |
---
## 🔐 角色权限矩阵
| 操作 | Viewer (只读) | Operator (操作员) | Admin (管理员) | Super Admin (超级管理员) |
|------|---------------|------------------|----------------|---------------------|
| 查看所有数据 | ✅ | ✅ | ✅ | ✅ |
| 编辑 IP 信息 | ❌ | ✅ | ✅ | ✅ |
| 执行扫描 | ❌ | ✅ | ✅ | ✅ |
| 确认/解决告警 | ❌ | ✅ | ✅ | ✅ |
| 网段管理 | ❌ | ❌ | ✅ | ✅ |
| SNMP 设备/凭据 | ❌ | ❌ | ✅ | ✅ |
| MAC 白名单 | ❌ | ❌ | ✅ | ✅ |
| 导出报表 | ❌ | ❌ | ✅ | ✅ |
| 查看审计日志 | ❌ | ❌ | ✅ | ✅ |
| 用户管理 | ❌ | ❌ | ❌ | ✅ |
| 系统设置 | ❌ | ❌ | ❌ | ✅ |
---
## 📋 API 端点总览
| 模块 | 端点数量 | 主要功能 |
|------|----------|----------|
| 认证 | 10 | 登录、登出、Token刷新、用户管理 |
| 网段管理 | 7 | CRUD、扫描、IP列表、统计 |
| IP 地址 | 5 | 列表、详情、编辑、扫描 |
| 扫描 | 8 | 单IP、网段、异步任务、状态查询 |
| SNMP | 13 | 凭据、设备、轮询、ARP表、接口 |
| 告警 | 11 | 列表、确认/解决/忽略、检测、白名单 |
| 审计日志 | 5 | 日志查询、用户日志、资源历史、统计、清理 |
| 报表 | 6 | CSV导出、汇总统计 |
---
## 💡 常见问题
### Q: 为什么 IP 扫描后 MAC 地址都是空的？
A: ARP 扫描只能获取**同网段**设备的 MAC 地址。跨网段需要配置 SNMP 采集核心交换机的 ARP 表。
### Q: 定时扫描没有执行？
A: 请检查 **Celery Beat** 是否正常启动，Celery Worker 是否正常运行，Redis 连接是否正常。
### Q: 如何临时禁用自动扫描？
A: 停止 Celery Beat 服务即可，不会影响手动触发扫描。
### Q: 如何调整扫描并发数？
A: 启动 Celery Worker 时调整 `--concurrency` 参数：
```bash
celery -A app.tasks.celery_app worker --concurrency=8 # 8并发
```
### Q: 扫描时间太长怎么办？
A: 1. 增加并发数 2. 关闭 DNS 解析（较慢）3. 分网段分时段扫描
---
## 📁 项目结构
```
/root/ipam/
├── backend/
│ ├── app/
│ │ ├── api/v1/ # API 路由
│ │ ├── core/ # 配置、数据库、安全
│ │ ├── models/ # 数据模型
│ │ ├── schemas/ # Pydantic 验证模型
│ │ ├── services/ # 业务逻辑层
│ │ ├── tasks/ # Celery 异步任务
│ │ └── main.py # 应用入口
│ └── venv/ # Python 虚拟环境
├── frontend/
│ ├── src/
│ │ ├── views/ # 页面组件
│ │ ├── components/ # 通用组件
│ │ ├── router/ # 路由配置
│ │ └── main.js # 应用入口
│ └── node_modules/
├── start.sh # 一键启动脚本
├── stop.sh # 停止服务脚本
├── DEV_PROGRESS.md # 开发进度文档
└── README.md # 本文件
```
---
## 📞 支持
如遇问题，请查看：
1. API 文档：`http://<服务器IP>:8008/docs`
2. 开发进度：`DEV_PROGRESS.md`
3. Celery 日志：查看 Worker 和 Beat 终端输出
---
## 📝 License
MIT License