ipam/README.md

# 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 地址白名单

### 🎨 P2 - 前端界面
- ✅ **Vue 3 + Element Plus** - 现代化 UI 框架
- ✅ **仪表盘** - 统计概览、网段使用率、告警统计
- ✅ **网段管理** - 网段 CRUD、扫描、导出
- ✅ **IP 地址管理** - 筛选、搜索、编辑
- ✅ **扫描管理** - 综合扫描、结果导出
- ✅ **SNMP 管理** - 设备、凭据、ARP 表
- ✅ **告警中心** - 告警列表、统计、白名单

## 🚀 快速启动

### 方式一：使用启动脚本（推荐）

```bash
cd /root/ipam

# 启动所有服务
chmod +x start.sh
./start.sh
```

### 方式二：手动启动

**1. 启动数据库和缓存**
```bash
# MySQL 已运行在 3308 端口
# Redis 已运行在 6379 端口
```

**2. 启动后端服务**
```bash
cd /root/ipam/backend
source venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8008
```

**3. 启动 Celery Worker**
```bash
cd /root/ipam/backend
source venv/bin/activate
celery -A app.tasks.celery_app worker --loglevel=info --concurrency=4
```

**4. 启动前端服务**
```bash
cd /root/ipam/frontend
npm run dev -- --host 0.0.0.0 --port 3000
```

## 🌐 访问地址

| 服务 | 地址 | 说明 |
|------|------|------|
| 前端界面 | http://服务器IP:3000 | Web 管理界面 |
| 后端 API | http://服务器IP:8008 | API 服务 |
| API 文档 | http://服务器IP:8008/docs | Swagger 在线文档 |
| MySQL | 服务器IP:3308 | 数据库 |
| Redis | 服务器IP:6379 | 缓存和任务队列 |

## 📖 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

---

**版本**: 1.0.0  
**最后更新**: 2026-07-17