AI-Agent/ipam
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity
Files
1e1e5957e8bd13f8a5571a675e92293108ae94e5
ipam/docs/DEVELOPMENT.md
T
Your Name 1e1e5957e8 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 记录
2026-07-18 09:45:30 +08:00

6.8 KiB
Raw Blame History

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（网段表）

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地址表）

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（扫描任务表）

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凭据表）

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（网络设备表）

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（告警表）

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 View Git Blame Copy Permalink