IPAM 地址管理教程：自动化扫描、SNMP 与告警的企业级 IP 管理
公司网段越来越多，IP 靠 Excel 表格记，哪个 IP 空闲、哪个冲突、哪个设备是新冒出来的，全靠人工对账——这就是 IPAM 要解决的问题。这个项目是一个企业级 IP 地址管理系统：网段和 IP 台账、Ping/ARP/DNS 自动扫描、SNMP 采集交换机 ARP 表、IP 冲突和未授权接入告警、MAC 白名单、四级角色权限，全部在一个 Web 界面里。这篇教程从一键部署讲到定时扫描配置和日常运维。
一、项目简介
ipam 是 git.cnbugs.com 上 AI-Agent 组织的一个开源项目（仓库地址 https://git.cnbugs.com/AI-Agent/ipam），定位是企业级 IP 地址管理（IP Address Management）系统。它把“IP 台账 + 自动发现 + 异常告警”做在一起：网段按 CIDR 建，IP 列表自动生成，定时扫描刷新在线状态，SNMP 从交换机拿 ARP 表，冲突和未授权接入自动告警。
后端是 FastAPI + SQLAlchemy + MySQL 8.0，异步任务用 Celery + Redis，前端是 Vue 3 + Element Plus。部署上很有特点：一个 start.sh 就能完成 venv 创建、依赖安装、MySQL/Redis 容器启动、systemd 服务生成和前端启动，目录自适应，放到哪里都能跑。
二、功能特性
核心管理
- 网段管理：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 使用率、在线率、告警统计、网段分布。
三、技术架构
| 组件 | 技术选型 | 版本 |
|---|---|---|
| Web 框架 | FastAPI | 0.115 |
| ORM | SQLAlchemy | 2.0 |
| 数据库 | MySQL | 8.0 |
| 异步任务 | Celery + Redis | 5.4 / 6.0+ |
| 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 |
运行时是四个进程：后端 API（uvicorn，8008 端口）、Celery Worker（执行扫描任务）、Celery Beat（定时任务调度器）、前端（Vite dev server，3000 端口）。MySQL 和 Redis 跑在 Docker 容器里。数据流是：Celery Beat 按计划触发扫描任务 → Worker 并发 Ping/ARP/DNS 扫网段 → 结果写 MySQL → 前端从 API 读展示；SNMP 设备轮询也是 Beat 每 60 秒触发一次。
四、适用场景
- 企业内网 IP 治理：几百到几万个 IP，Excel 管不过来，需要台账 + 自动发现 + 冲突告警。
- 新设备接入管控：未授权设备一接入就告警，配合 MAC 白名单做准入管理。
- 机房/实验室网络：网段多、设备换得勤，定时扫描自动刷新在线状态，不用人工巡检。
- IP 资源规划：网段使用率一目了然，哪个网段快满了提前预警，避免新业务没 IP 可分。
五、环境准备
- Python 3.11+
- MySQL 8.0+
- Redis 6.0+
- Node.js 18+
- Docker（start.sh 会用它起 MySQL/Redis 容器）
- root 权限（start.sh 要写 systemd 服务）
注意：PySNMP 对依赖版本很敏感，手动安装时要按 README 的版本钉住：
pip install "pysnmp==4.4.12" "pyasn1<0.5.0" "pysmi<0.4.0"六、一键部署：start.sh（推荐）
start.sh 是目录自适应的：不硬编码路径，自动以脚本所在目录为项目根，无论部署在 /opt/ipam、/usr/local/ipam、/root/ipam 还是其它任意目录都能工作。运行时会自动创建 Python venv、安装后端依赖、启动 MySQL/Redis 容器、生成 3 个 systemd 服务并 enable 开机自启、启动前端。
# 1. 前置：Python3 / Node.js / Docker 需已安装
# 2. git clone 代码（放到你想要的任何目录）
git clone https://git.cnbugs.com/AI-Agent/ipam.git /opt/ipam
cd /opt/ipam
# 3. 一键启动（需 root 权限）
bash start.sh启动成功后访问：管理界面 http://服务器IP:3000，API 文档 http://服务器IP:8008/docs。默认管理员账号是 admin / admin123，首次登录后立刻改密码。
start.sh 自动生成的 3 个 systemd 服务（开机自启 + 崩溃自动重启，Restart=always），日志写到 /var/log/ipam/*.log：
| 服务名 | 内容 | 说明 |
|---|---|---|
ipam-backend | uvicorn :8008 | 后端 API |
ipam-celery-worker | celery worker | 执行扫描/轮询任务 |
ipam-celery-beat | celery beat | 定时任务调度器（每 60 秒触发 SNMP 设备自动轮询） |
# 服务管理
bash start.sh
bash stop.sh
# 查看状态（应为开机自启 + 运行中）
systemctl status ipam-backend ipam-celery-worker ipam-celery-beat
# 查看日志
tail -f /var/log/ipam/ipam-backend.log
tail -f /var/log/ipam/ipam-celery-worker.log
tail -f /var/log/ipam/ipam-celery-beat.log七、手动部署（仅开发调试）
手动方式仅供开发调试用，生产环境推荐用 start.sh（自动生成 systemd 服务、开机自启、崩溃自动重启）。四个进程各开一个终端：
# 1. 启动后端 API 服务
cd <项目目录>/backend
source venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8008
# 2. 启动 Celery Worker（执行扫描任务）
cd <项目目录>/backend
source venv/bin/activate
celery -A app.tasks.celery_app worker --loglevel=info --concurrency=4
# 3. 启动 Celery Beat（定时任务调度器，自动扫描必须启动）
cd <项目目录>/backend
source venv/bin/activate
celery -A app.tasks.celery_app beat --loglevel=info
# 4. 启动前端
cd <项目目录>/frontend
npm install
npm run dev -- --host 0.0.0.0 --port 3000注意：自动扫描依赖 Celery Beat，如果只起了 Worker 没起 Beat，定时扫描永远不会触发，这是最常见的新手问题。
八、自动扫描配置
系统默认配了 3 个定时扫描任务：
| 任务名称 | 执行频率 | 扫描内容 | 说明 |
|---|---|---|---|
| 每小时全量扫描 | 每 60 分钟 | Ping + ARP + DNS | 快速刷新在线状态 |
| 每日深度扫描 | 每天凌晨 02:00 | Ping + ARP + DNS | 每日完整扫描更新 |
| 统计更新 | 每 15 分钟 | 仅更新统计 | 更新网段使用率 |
每次完整扫描会执行：ICMP Ping 检测在线 → ARP 扫描拿 MAC（同网段有效）→ 反向 DNS 解析主机名 → MAC 厂商识别（前 3 字节查 OUI 库）→ 更新 IP 状态、MAC、主机名、最后发现时间 → 异常检测（IP 冲突、未授权接入等告警检查）。
改扫描频率要编辑 <项目目录>/backend/app/tasks/celery_app.py 里的 beat_schedule：
# 定时任务配置
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 才会生效。监控定时任务状态用这几个命令：
cd <项目目录>/backend
source venv/bin/activate
# 查看 Celery 活跃任务
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
# 调整扫描并发数（Worker 启动时）
celery -A app.tasks.celery_app worker --concurrency=8 # 8 并发九、SNMP 网络设备集成
Ping + ARP 只能看到同网段的设备，跨网段的 MAC 就拿不到了——这时候要靠 SNMP。把核心交换机加进来，系统会定期采集它的 ARP 表和接口表，跨网段设备的 MAC 和 IP 对应关系就有了。支持 SNMPv2c（Community）和 SNMPv3（认证+加密），SNMPv3 建议用 authPriv（认证+加密）模式。
操作路径：界面里先加 SNMP 凭据（v2c 填 Community，v3 填用户名、认证协议/密码、加密协议/密码），再加设备（IP + 凭据 + 轮询间隔），系统每 60 秒由 Celery Beat 触发一次自动轮询，设备在线/离线状态、ARP 表、接口表都会更新。设备长时间不在线会触发离线告警。
十、告警与异常检测
告警是这个系统最有价值的部分，四种检测都是扫描或轮询完成后自动跑的：
- IP 冲突：同一 IP 在扫描里对应了多个 MAC 地址，说明有人手动配了重复 IP 或有私接设备。
- 未授权接入：新发现的设备 MAC 不在白名单里，自动告警；可信设备先加进 MAC 白名单就免告警。
- 网段耗尽预警：网段使用率超过阈值就告警，提醒提前规划新网段。
- 设备离线：SNMP 设备长时间轮询不到，说明交换机挂了或者网络断了。
告警处理流程是：列表里看到告警 → 确认是真实问题还是误报 → 确认/解决/忽略。误报（比如测试设备）可以把 MAC 加进白名单，下次不再告警。所有告警记录都可以 CSV 导出，方便做周报。
十一、角色权限矩阵
| 操作 | Viewer（只读） | Operator（操作员） | Admin（管理员） | Super Admin（超级管理员） |
|---|---|---|---|---|
| 查看所有数据 | ✅ | ✅ | ✅ | ✅ |
| 编辑 IP 信息 | ❌ | ✅ | ✅ | ✅ |
| 执行扫描 | ❌ | ✅ | ✅ | ✅ |
| 确认/解决告警 | ❌ | ✅ | ✅ | ✅ |
| 网段管理 | ❌ | ❌ | ✅ | ✅ |
| SNMP 设备/凭据 | ❌ | ❌ | ✅ | ✅ |
| MAC 白名单 | ❌ | ❌ | ✅ | ✅ |
| 导出报表 | ❌ | ❌ | ✅ | ✅ |
| 查看审计日志 | ❌ | ❌ | ✅ | ✅ |
| 用户管理 | ❌ | ❌ | ❌ | ✅ |
| 系统设置 | ❌ | ❌ | ❌ | ✅ |
给一线运维开 Operator，给网络管理员开 Admin，Super Admin 只给一两个人。审计日志会记录所有操作，谁改了哪个 IP、谁确认了哪条告警都能追溯。
十二、API 端点总览
| 模块 | 端点数量 | 主要功能 |
|---|---|---|
| 认证 | 10 | 登录、登出、Token 刷新、用户管理 |
| 网段管理 | 7 | CRUD、扫描、IP 列表、统计 |
| IP 地址 | 5 | 列表、详情、编辑、扫描 |
| 扫描 | 8 | 单 IP、网段、异步任务、状态查询 |
| SNMP | 13 | 凭据、设备、轮询、ARP 表、接口 |
| 告警 | 11 | 列表、确认/解决/忽略、检测、白名单 |
| 审计日志 | 5 | 日志查询、用户日志、资源历史、统计、清理 |
| 报表 | 6 | CSV 导出、汇总统计 |
完整路径和在线测试见 http://<服务器IP>:8008/docs（Swagger）或 /redoc。健康检查：
# 后端健康
curl -s http://localhost:8008/health
# 前端是否正常
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000
# 三个服务是否都在跑
systemctl is-active ipam-backend ipam-celery-worker ipam-celery-beat
# 应输出 3 个 active十三、常见问题
| 问题 | 原因与处理 |
|---|---|
| IP 扫描后 MAC 地址都是空的 | ARP 扫描只能获取同网段设备的 MAC；跨网段要配 SNMP 采集核心交换机的 ARP 表 |
| 定时扫描没有执行 | 检查 Celery Beat 是否正常启动、Worker 是否运行、Redis 连接是否正常 |
| 如何临时禁用自动扫描 | 停掉 Celery Beat 服务即可，不影响手动触发扫描 |
| 如何调整扫描并发数 | Worker 启动时加 --concurrency=8 |
| 扫描时间太长 | 增加并发数；关闭 DNS 解析（较慢）；分网段分时段扫描 |
十四、生产更新与运维
生产代码是 git clone 放上去的，日常更新用 git pull 拉最新代码再重启服务。推荐流程：
cd /你的部署目录 # 例如 /opt/ipam
# 1.（可选）备份当前脚本，防止意外
cp start.sh /tmp/start.sh.bak
# 2. 拉取远端最新代码
git pull origin master
# 3. 重启服务让新代码生效（需 root）
# 后端 / Celery Worker / Celery Beat 是 systemd 管理，重启它们即可
systemctl restart ipam-backend ipam-celery-worker ipam-celery-beat
# 前端 vite dev server 是 nohup 方式，需手动重启
pkill -f "vite" ; sleep 2
cd frontend && nohup npm run dev -- --host 0.0.0.0 --port 3000 > /tmp/ipam-frontend.log 2>&1 &
# 4. 全量一键启动（更省心：自动检测目录重新生成 systemd + 拉起全部服务）
# bash start.sh
# 5. 验证服务全部正常
systemctl is-active ipam-backend ipam-celery-worker ipam-celery-beat
curl -s http://localhost:8008/health
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000更新要点：后端和 Celery 是 systemd 管理，重启三个服务就行；前端是 nohup 的 vite dev server，要 pkill -f vite 后重新起；依赖变了要重装（后端 venv/bin/pip install -r requirements.txt，前端 npm install --include=dev）；如果换了部署目录，直接在新位置跑一次 bash start.sh，它会自动按新目录重写 systemd 单元。
总结一下：ipam 把 IP 台账、自动扫描、SNMP 采集和告警做成了一个闭环——网段建好之后，Ping/ARP/DNS 定时扫、交换机 ARP 表定时采，冲突和未授权接入自动告警，报表一键导出。部署记住一条：生产用 start.sh 一键起，三个 systemd 服务加前端；扫描想调频率改 celery_app.py 的 beat_schedule，改完重启 Worker 和 Beat；默认密码 admin/admin123 首次登录立刻改掉。
