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+

一键启动所有服务

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

start.sh 目录自适应，无论部署在 /opt、/usr/local、/root 还是其它任意目录， 直接以脚本所在目录为项目根运行即可（需 root 权限）：

cd /你的部署目录     # 例如 /opt/ipam，跟随你实际的部署路径
bash start.sh

运行时会自动：创建 Python venv → 安装后端依赖 → 启动 MySQL/Redis 容器 → 生成 3 个 systemd 服务（backend / celery-worker / celery-beat）并 enable 开机自启 → 启动前端。更多细节见下文「生产环境部署建议」。

方式二：手动启动

⚠️ 仅供开发调试用。生产环境推荐使用方式一（start.sh），可自动生成 systemd 服务、开机自启、崩溃自动重启。

安装依赖环境

# 以下 <项目目录> 均指你实际的部署路径，例如 /opt/ipam
cd <项目目录>/backend
source venv/bin/activate
pip install "pysnmp==4.4.12" "pyasn1<0.5.0" "pysmi<0.4.0"

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

---

⏰ 自动扫描配置

扫描频率配置

系统默认配置了 3 个定时扫描任务：

任务名称	执行频率	扫描内容	说明
每小时全量扫描	每 60 分钟	Ping + ARP + DNS	快速刷新在线状态
每日深度扫描	每天凌晨 02:00	Ping + ARP + DNS	每日完整扫描更新
统计更新	每 15 分钟	仅更新统计	更新网段使用率

如何自定义扫描频率

编辑配置文件：<项目目录>/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 <项目目录>/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

---

🛠️ 生产环境部署建议

推荐方式：使用 start.sh（自动化，目录自适应）

start.sh 已内置完整的生产级部署逻辑，无需手动创建任何 systemd 单元：

• 目录自适应：不硬编码路径，自动以脚本所在目录为项目根。无论部署在 /opt/ipam、/usr/local/ipam、/root/ipam 还是其它任意目录都能工作。

• systemd 自动生成：运行 start.sh 时自动生成并 systemctl enable 如下 3 个服务，实现开机自启 + 崩溃自动重启（Restart=always）：

  服务名	内容	说明
  ipam-backend	uvicorn :8008	后端 API
  ipam-celery-worker	celery worker	执行扫描/轮询任务
  ipam-celery-beat	celery beat	定时任务调度器（每60秒触发 SNMP 设备自动轮询）

  日志写入 /var/log/ipam/*.log。

首次部署（全新机器）

# 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 权限，自动装依赖 + 起 MySQL/Redis 容器 + 生成 systemd + 启前端）
bash start.sh

启动成功后即可访问：

• 管理界面 http://服务器IP:3000
• API 文档 http://服务器IP:8008/docs

💡 首次运行 start.sh 会自动创建 Python venv、安装前端依赖（含 vite）、 启动 MySQL/Redis Docker 容器、生成 3 个 systemd 服务并 enable 开机自启， 全程无需人工干预。若部署目录想换到别处，把项目整个复制过去再跑一次 bash start.sh 即可自动重写 systemd 单元。

服务管理命令

# 启动 / 停止 / 重启
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

---

生产服务器更新流程（git 部署时）

生产代码是通过 git clone 放上去的，日常更新用 git pull 拉取远端最新代码， 再重启服务即可。推荐更新流程：

cd /你的部署目录            # 例如 /opt/ipam，跟随你实际的部署路径

# 1.（可选）备份当前脚本，防止意外
cp start.sh /tmp/start.sh.bak

# 2. 拉取远端最新代码（含全部修复：单IP扫描、SNMP自动轮询、告警检测、部署脚本）
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   # 应输出 3 个 active
curl -s http://localhost:8008/health                                   # 后端健康
curl -s -o /dev/null -w "%{http_code}" http://localhost:3000           # 前端 200

更新要点：

1. 后端 / Celery 是 systemd 管理（ipam-backend / ipam-celery-worker / ipam-celery-beat），更新代码后只需 systemctl restart 这三个服务， 它们会保持开机自启和崩溃自动重启。
2. 前端是 nohup 方式（vite dev server，开发服务不纳入 systemd），需要 pkill -f vite 后重新 npm run dev 启动。
3. 依赖变更时：若 git pull 拉取后要求新 Python 包，执行 cd backend && venv/bin/pip install -r requirements.txt； 前端依赖变化则 cd frontend && npm install --include=dev。
4. 若你切换了部署目录（从 /opt 挪到 /usr/local 等），直接在新位置跑一次 bash start.sh，它会自动按新目录重新生成 systemd 单元，无需手动改任何配置。
5. 首次部署到新机器建议直接跑 bash start.sh（一键全自动），日常增量更新 用第 2~4 步的重启方式即可，两者效果一致。

---

🌐 访问地址

服务	地址	说明
管理后台	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. 分网段分时段扫描

---

📁 项目结构

<项目目录>/            # 例如 /opt/ipam、/usr/local/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