AI-Agent/ipam
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases 3 Wiki Activity
Files
master
ipam/README.md
T
Your Name bca0da7c7d readme
2026-07-20 13:40:05 +08:00

11 KiB
Raw Permalink Blame History

IPAM 管理系统

企业级 IP 地址管理系统，支持自动化扫描、发现和管理网络 IP 资产。

✨ 功能特性

核心管理

  • 网段管理 - CIDR 网段创建、分组、自动生成 IP 列表、使用率监控
  • IP 资产台账 - 在线/离线/空闲/保留状态管理、MAC地址、主机名、厂商识别、使用人/业务标注
  • 搜索筛选 - 按网段、状态、IP/MAC/主机名快速搜索

智能扫描

  • 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+

一键启动所有服务

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

cd /root/ipam
./start.sh

方式二：手动启动

安装依赖环境

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
1️⃣ 启动后端 API 服务
cd /root/ipam/backend
source venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8008
2️⃣ 启动 Celery Worker（执行扫描任务）
cd /root/ipam/backend
source venv/bin/activate
celery -A app.tasks.celery_app worker --loglevel=info --concurrency=4
3️⃣ 启动 Celery Beat（定时任务调度器，自动扫描必须启动）
cd /root/ipam/backend
source venv/bin/activate
celery -A app.tasks.celery_app beat --loglevel=info
4️⃣ 启动前端
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

# 定时任务配置 (第 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,  # 单位：秒
    },
}

常用配置示例：

# 每 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 活跃任务

cd /root/ipam/backend
source venv/bin/activate
celery -A app.tasks.celery_app inspect active

查看定时任务调度

celery -A app.tasks.celery_app inspect scheduled

查看 Worker 状态

celery -A app.tasks.celery_app inspect stats

🛠️ 生产环境部署建议

使用 Systemd 管理服务（开机自启）

1. 创建 IPAM API 服务

# /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 服务

# /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 服务

# /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. 启用并启动服务

# 重新加载配置
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 Vue 前端界面
API 服务 http://服务器IP:8008 REST API
Swagger 文档 http://服务器IP:8008/docs API 在线测试文档
Redoc 文档 http://服务器IP:8008/redoc API 文档

默认管理员账号：

  • 用户名: admin
  • 密码: admin123

📊 技术栈

组件 技术选型 版本
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 参数：

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

Reference in New Issue View Git Blame Copy Permalink