Your Name
1e1e5957e8
- 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 记录
261 lines
6.8 KiB
Markdown
261 lines
6.8 KiB
Markdown
# 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` 配置文件。
|