# 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 模式（只统计不写库）

### 用法

```bash
# 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 厂商显示 -**
```bash
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 目录里执行：
```bash
cd /root/ipam/backend
python scripts/backfill_vendor.py
```

如果脚本运行后 `未识别 = 候选 IP 总数`，说明 mac_vendor_lookup 库没装或加载失败：
```bash
pip show mac-vendor-lookup     # 检查库是否装好
python -c "from mac_vendor_lookup import MacLookup; print('OK')"  # 测试导入
```

如果 OUI 数据库太旧（库自带的 IEEE OUI 文件是 2022 年的快照），新厂商识别不到，可以更新：
```bash
pip install -U mac-vendor-lookup
# 或下载最新 IEEE OUI 文件
python -c "from mac_vendor_lookup import MacLookup; MacLookup().update_vendors()"
```