ipam/backend/scripts

IPAM 运维脚本

存放 IPAM 平台的一次性运维脚本。所有脚本都假定从 backend/ 目录执行，且 venv 已激活。

回填厂商 / 主机名 — backfill_vendor.py

用途

在某些情况下（升级前扫描失败、OUI 库没装、依赖 bug 等）IP 表里 mac_address 有值但 vendor/hostname 是空。本脚本会：

• 找出所有 mac_address IS NOT NULL AND vendor IS NULL 的 IP
• 调用 EnhancedScanService.get_mac_vendor() 重新识别厂商（基于 IEEE OUI 数据库）
• 可选：调用 reverse_dns_lookup() 回填主机名
• 支持 dry-run 模式（只统计不写库）

用法

# 1. 确保依赖装了（首次或升级后必做）
pip install mac-vendor-lookup

# 2. 干跑：只统计能识别的 IP 数量，不写库
python scripts/backfill_vendor.py --dry-run

# 3. 实际回填
python scripts/backfill_vendor.py

# 4. 同时回填主机名（用反向 DNS，会慢一些）
python scripts/backfill_vendor.py --with-hostname

# 5. 加 --yes 跳过确认提示（cron 用）
python scripts/backfill_vendor.py --yes

# 6. 限制处理数量（测试用）
python scripts/backfill_vendor.py --dry-run --limit 100

参数

参数	说明
--dry-run	只统计，不写库
--with-hostname	同时回填 hostname（DNS 解析）
--timeout N	DNS 解析超时秒数（默认 2）
--limit N	最多处理 N 条，0 = 不限
--yes / -y	跳过确认提示

常见场景

场景 1：升级后 IP 厂商显示 -

pip install mac-vendor-lookup    # 装新依赖
python scripts/backfill_vendor.py --dry-run   # 先看数量
python scripts/backfill_vendor.py             # 实际回填

场景 2：扫描能拿到 MAC，但扫描时 vendor 字段没写 说明扫描代码逻辑有 bug，应该改 enhanced_scan_service.py 的 update_ip_from_scan_result() 而不是用本脚本。脚本只是数据修复。

场景 3：所有 IP 都没有 MAC 说明扫描本身没成功，根因在网络层（防火墙、扫描不到、ICMP/ARP 都被禁）。需要先解决扫描链路问题。

依赖

• mac-vendor-lookup（IEEE OUI 官方数据库，约 17 万条记录）
• 项目本身的依赖（FastAPI、SQLAlchemy、PyMySQL 等）
• 可选：pynmblookup（NetBIOS 主机名发现，仅 Windows 设备需要）

注意事项

• 脚本会直接写库，建议先 dry-run
• hostname 反向 DNS 可能比较慢（取决于目标设备是否配置了 PTR 记录）
• 不会改写已经存在的 vendor/hostname（只填空值）
• 不影响扫描逻辑本身（不会自动重新扫描）

故障排查

如果脚本运行时报 ImportError: No module named 'app'，说明 sys.path 没找到 backend 目录。在 backend 目录里执行：

cd /root/ipam/backend
python scripts/backfill_vendor.py

如果脚本运行后 未识别 = 候选 IP 总数，说明 mac_vendor_lookup 库没装或加载失败：

pip show mac-vendor-lookup     # 检查库是否装好
python -c "from mac_vendor_lookup import MacLookup; print('OK')"  # 测试导入

如果 OUI 数据库太旧（库自带的 IEEE OUI 文件是 2022 年的快照），新厂商识别不到，可以更新：

pip install -U mac-vendor-lookup
# 或下载最新 IEEE OUI 文件
python -c "from mac_vendor_lookup import MacLookup; MacLookup().update_vendors()"