fix(ipam): 修复IP管理页面网段筛选不生效及下拉框过窄
- Ips.vue: el-select 添加 width: 280px，修复网段下拉框过窄 - Ips.vue: query 参数 networkId → network_id（与 FastAPI snake_case 一致） - Scan.vue: el-select 用 network.id 代替整个 network 对象作为 value，修复切换网段不生效 - enhanced_scan_service.py: 替换失效的 scapy ARP 扫描为 arp-scan 命令；扫描结果自动创建缺失 IP 记录
This commit is contained in:
Your Name
@@ -0,0 +1,260 @@
|
||||
# IPAM 管理系统 - 开发文档
|
||||
|
||||
## 项目概述
|
||||
|
||||
IPAM (IP Address Management) 是一个企业级IP地址管理系统，用于自动化扫描、发现和管理网络IP资产。
|
||||
|
||||
## 需求优先级划分
|
||||
|
||||
### P0 - 核心功能（必须优先实现）
|
||||
|
||||
#### 1. 项目基础架构
|
||||
- [ ] FastAPI 后端框架搭建
|
||||
- [ ] MySQL 数据库模型设计
|
||||
- [ ] Redis 缓存配置
|
||||
- [ ] Celery 异步任务框架
|
||||
- [ ] Docker & Docker Compose 容器化部署
|
||||
|
||||
#### 2. 网络与子网管理
|
||||
- [ ] 网段CRUD（支持CIDR格式）
|
||||
- [ ] 网段分组管理
|
||||
- [ ] 网段统计视图（总IP、已用、空闲、使用率）
|
||||
|
||||
#### 3. IP资产台账
|
||||
- [ ] IP地址实体模型
|
||||
- [ ] 基础字段：IP、MAC、主机名
|
||||
- [ ] IP状态管理（在线、离线、空闲、保留）
|
||||
- [ ] 自定义字段扩展框架
|
||||
|
||||
#### 4. 基础扫描引擎
|
||||
- [ ] ICMP Ping扫描
|
||||
- [ ] 手动触发扫描
|
||||
|
||||
### P1 - 重要功能（核心功能完成后实现）
|
||||
|
||||
#### 1. 高级扫描功能
|
||||
- [ ] ARP扫描获取MAC地址
|
||||
- [ ] 反向DNS解析主机名
|
||||
- [ ] 定时扫描任务调度
|
||||
|
||||
#### 2. SNMP设备集成
|
||||
- [ ] SNMP凭据池（v2c + v3）
|
||||
- [ ] 网络设备台账
|
||||
- [ ] SNMP连通性测试
|
||||
- [ ] ARP表拉取（IP-MAC映射）
|
||||
- [ ] MAC地址表拉取（MAC-端口映射）
|
||||
|
||||
#### 3. 告警与异常检测
|
||||
- [ ] IP冲突告警
|
||||
- [ ] 非授权接入告警
|
||||
- [ ] 网段耗尽预警
|
||||
|
||||
### P2 - 增强功能
|
||||
|
||||
#### 1. 厂商深度发现
|
||||
- [ ] Cisco/H3C私有MIB支持
|
||||
- [ ] LLDP/CDP邻居发现
|
||||
- [ ] 物理拓扑解析
|
||||
- [ ] OUI厂商识别
|
||||
|
||||
#### 2. 系统管理
|
||||
- [ ] 操作审计日志
|
||||
- [ ] IP历史轨迹
|
||||
- [ ] 角色权限控制
|
||||
|
||||
#### 3. 前端界面
|
||||
- [ ] Vue 3 + Element Plus
|
||||
- [ ] 网段大盘视图
|
||||
- [ ] IP台账表格
|
||||
- [ ] 网络拓扑展示
|
||||
|
||||
## 技术栈
|
||||
|
||||
### 后端
|
||||
- **Web框架**: FastAPI 0.110+
|
||||
- **数据库**: MySQL 8.0
|
||||
- **ORM**: SQLAlchemy 2.0
|
||||
- **缓存**: Redis 7.0
|
||||
- **异步任务**: Celery 5.3+
|
||||
- **SNMP**: pysnmp
|
||||
- **网络探测**: Scapy
|
||||
- **数据验证**: Pydantic 2.0
|
||||
|
||||
### 前端
|
||||
- **框架**: Vue 3
|
||||
- **UI组件**: Element Plus
|
||||
- **状态管理**: Pinia
|
||||
- **路由**: Vue Router 4
|
||||
|
||||
### 部署
|
||||
- **容器化**: Docker + Docker Compose
|
||||
- **反向代理**: Nginx
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
ipam/
|
||||
├── backend/ # 后端代码
|
||||
│ ├── app/
|
||||
│ │ ├── api/ # API路由
|
||||
│ │ │ ├── v1/
|
||||
│ │ │ │ ├── networks.py
|
||||
│ │ │ │ ├── ips.py
|
||||
│ │ │ │ ├── scan.py
|
||||
│ │ │ │ └── devices.py
|
||||
│ │ │ └── dependencies.py
|
||||
│ │ ├── core/ # 核心配置
|
||||
│ │ │ ├── config.py
|
||||
│ │ │ ├── database.py
|
||||
│ │ │ └── security.py
|
||||
│ │ ├── models/ # 数据库模型
|
||||
│ │ │ ├── network.py
|
||||
│ │ │ ├── ip.py
|
||||
│ │ │ ├── device.py
|
||||
│ │ │ └── alert.py
|
||||
│ │ ├── schemas/ # Pydantic模型
|
||||
│ │ │ ├── network.py
|
||||
│ │ │ ├── ip.py
|
||||
│ │ │ └── scan.py
|
||||
│ │ ├── services/ # 业务逻辑
|
||||
│ │ │ ├── network_service.py
|
||||
│ │ │ ├── scan_service.py
|
||||
│ │ │ └── snmp_service.py
|
||||
│ │ ├── tasks/ # Celery任务
|
||||
│ │ │ ├── celery_app.py
|
||||
│ │ │ ├── scan_tasks.py
|
||||
│ │ │ └── snmp_tasks.py
|
||||
│ │ └── main.py
|
||||
│ ├── requirements.txt
|
||||
│ ├── Dockerfile
|
||||
│ └── .env.example
|
||||
├── frontend/ # 前端代码
|
||||
│ ├── src/
|
||||
│ ├── package.json
|
||||
│ └── Dockerfile
|
||||
├── docker-compose.yml
|
||||
├── docs/ # 文档
|
||||
│ └── DEVELOPMENT.md
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## 数据库设计
|
||||
|
||||
### 核心表结构
|
||||
|
||||
#### networks（网段表）
|
||||
```sql
|
||||
id INT PRIMARY KEY
|
||||
cidr VARCHAR(50) UNIQUE -- 如: 192.168.1.0/24
|
||||
name VARCHAR(100)
|
||||
description TEXT
|
||||
group_name VARCHAR(100) -- 分组名称
|
||||
gateway VARCHAR(50)
|
||||
vlan_id INT
|
||||
total_ips INT
|
||||
used_ips INT DEFAULT 0
|
||||
reserved_ips INT DEFAULT 0
|
||||
created_at DATETIME
|
||||
updated_at DATETIME
|
||||
```
|
||||
|
||||
#### ip_addresses（IP地址表）
|
||||
```sql
|
||||
id INT PRIMARY KEY
|
||||
network_id INT FOREIGN KEY
|
||||
ip_address VARCHAR(50) UNIQUE
|
||||
mac_address VARCHAR(50) NULL
|
||||
hostname VARCHAR(255) NULL
|
||||
status ENUM('available', 'online', 'offline', 'reserved')
|
||||
owner VARCHAR(100) NULL
|
||||
business_type VARCHAR(50) NULL
|
||||
notes TEXT NULL
|
||||
custom_fields JSON -- 自定义字段
|
||||
last_seen DATETIME NULL
|
||||
created_at DATETIME
|
||||
updated_at DATETIME
|
||||
```
|
||||
|
||||
#### scan_tasks（扫描任务表）
|
||||
```sql
|
||||
id INT PRIMARY KEY
|
||||
network_id INT NULL
|
||||
task_type ENUM('ping', 'arp', 'snmp')
|
||||
status ENUM('pending', 'running', 'completed', 'failed')
|
||||
progress INT DEFAULT 0
|
||||
started_at DATETIME NULL
|
||||
completed_at DATETIME NULL
|
||||
result TEXT NULL
|
||||
created_at DATETIME
|
||||
```
|
||||
|
||||
#### snmp_credentials（SNMP凭据表）
|
||||
```sql
|
||||
id INT PRIMARY KEY
|
||||
name VARCHAR(100)
|
||||
version ENUM('v2c', 'v3')
|
||||
community_string VARCHAR(255) NULL -- v2c
|
||||
username VARCHAR(100) NULL -- v3
|
||||
auth_password VARCHAR(255) NULL -- v3
|
||||
auth_protocol VARCHAR(50) NULL -- MD5, SHA
|
||||
priv_password VARCHAR(255) NULL -- v3
|
||||
priv_protocol VARCHAR(50) NULL -- DES, AES
|
||||
created_at DATETIME
|
||||
```
|
||||
|
||||
#### network_devices（网络设备表）
|
||||
```sql
|
||||
id INT PRIMARY KEY
|
||||
name VARCHAR(100)
|
||||
ip_address VARCHAR(50)
|
||||
device_type VARCHAR(50) -- core, distribution, access
|
||||
vendor VARCHAR(100) NULL
|
||||
model VARCHAR(100) NULL
|
||||
snmp_credential_id INT FOREIGN KEY
|
||||
last_polled_at DATETIME NULL
|
||||
created_at DATETIME
|
||||
```
|
||||
|
||||
#### alerts（告警表）
|
||||
```sql
|
||||
id INT PRIMARY KEY
|
||||
alert_type ENUM('ip_conflict', 'unauthorized', 'subnet_full')
|
||||
severity ENUM('warning', 'error', 'critical')
|
||||
message TEXT
|
||||
resolved BOOLEAN DEFAULT FALSE
|
||||
resolved_at DATETIME NULL
|
||||
created_at DATETIME
|
||||
```
|
||||
|
||||
## API 接口设计
|
||||
|
||||
### 网段管理
|
||||
- `GET /api/v1/networks` - 获取网段列表
|
||||
- `POST /api/v1/networks` - 创建网段
|
||||
- `GET /api/v1/networks/{id}` - 获取网段详情
|
||||
- `PUT /api/v1/networks/{id}` - 更新网段
|
||||
- `DELETE /api/v1/networks/{id}` - 删除网段
|
||||
- `GET /api/v1/networks/{id}/stats` - 获取网段统计数据
|
||||
|
||||
### IP地址管理
|
||||
- `GET /api/v1/ips` - 获取IP列表
|
||||
- `GET /api/v1/ips/{id}` - 获取IP详情
|
||||
- `PUT /api/v1/ips/{id}` - 更新IP信息
|
||||
- `GET /api/v1/ips/export` - 导出IP台账
|
||||
|
||||
### 扫描管理
|
||||
- `POST /api/v1/scan/ping/{network_id}` - 触发Ping扫描
|
||||
- `GET /api/v1/scan/tasks/{task_id}` - 获取扫描任务状态
|
||||
|
||||
## 开发规范
|
||||
|
||||
1. **代码风格**: 遵循 PEP 8，使用 black 格式化
|
||||
2. **类型注解**: 使用 Python 类型注解
|
||||
3. **数据库迁移**: 使用 Alembic 管理数据库迁移
|
||||
4. **API文档**: FastAPI 自动生成 Swagger 文档
|
||||
5. **日志**: 使用 logging 模块记录关键操作
|
||||
6. **测试**: 每个模块完成后编写单元测试
|
||||
|
||||
## 部署说明
|
||||
|
||||
详见 `docker-compose.yml` 配置文件。
|
||||
Reference in New Issue
Block a user