马伯庸前阵子公司新园区上线，网络拓扑图定稿之后，分到我手上的是一张四百多行的 Excel 表：VLAN 编号、名称、归属区域、网关、IP 子网、每个终端固定的地址……摊开看一目了然，但要把这些数据真正灌进 phpipam，靠鼠标在 Web 界面里一个个点，那我加班加到几点是小问题，点错一个、前后对不上，上线之后排查能让人崩溃。所以我花了一个下午把 phpipam 的 API 从认证到写接口完整摸了一遍，写了套批量导入脚本，把 VLAN 和 IP 一次性灌进去，后续几个月的网络变更也都是同一套流程在跑。
这篇就聊聊这段实操里最有价值的部分：phpipam 的 API 是怎么认证的、VLAN 批量创建怎么写、IP 批量导入为什么必须先搞定 subnet、以及我在踩坑过程中总结出的一套排查思路。适合正在用 phpipam、被初始数据折磨的运维，也适合想把网络资产纳入 CMDB 自动同步体系的开发同学。
1. 为什么我放弃了 Web 界面手工录入：VLAN 和 IP 的初始化场景
1.1 手工录入的隐性成本：我在一次大规模上线中踩的坑
第一次需要往 phpipam 里灌大量 VLAN 和 IP 的时候，我最初的方案确实是在界面上手工录。因为那时候觉得 phpipam 的表单很友好，创建 VLAN 也就是填个编号和名称，创建 IP 也就是在子网页面点两下"添加地址"，看起来并不复杂。
但实际录到一百多个的时候，问题就全暴露出来了。首先是操作次数太多，每个 IP 都要经历"打开子网页面 -> 点添加地址 -> 填 IP、主机名、说明 -> 保存"这条链路，四百个地址就是两千多次页面切换，中间还得穿插 VLAN 创建和子网创建，手一快字段就串了。其次是出错之后极难定位，有一次我把某个 VLAN 的 number 填成了 4096 之外的非法值，页面当时没报错，等到把子网关联上去之后才发现整个子网列表里那条记录是残缺的，排查花了一个多小时。最让人头疼的是重复性劳动带来的麻木感，录到后面真的会看错行。
那次之后我做了个对比记录，同样一份 400 条地址的数据，手工录入了大概三个多小时，中途错了好几条，而且没有任何可追溯的日志。用 API 脚本跑的话，从准备 CSV 到灌完数据，总共不到十分钟，导入结果和失败记录全部打在本地日志里。这个差距在一次性初始化的时候还不算致命，但如果每周围绕工单系统新增几十条 IP，手工方式的成本就是持续累积的。
1.2 批量导入真正解决的三个问题
API 批量导入不是炫技，它解决的是几个非常实际的问题。
第一是效率。脚本遍历 CSV 里的每一行，自动完成 VLAN 创建、子网创建、IP 创建，速度取决于你设不设请求延迟。我在内网环境实测，逐条 POST 一个地址大约几十毫秒，跑完几百条不过是喝完一杯水的时间。
第二是一致性。数据全部来自预先整理好的 CSV 或 CMDB 导出，而不是人手工在表单里敲，天然规避了手滑填错、字段串位这类问题。只要是源表正确的数据，落到 phpipam 里就是一致的。
第三是可重复、可审计。脚本执行完，哪些 VLAN 成功了，哪些 IP 因为重复被跳过，全部有日志。哪天数据被误删，或者换了套测试环境要重新灌，同一套命令再跑一遍就行，不用重新在界面里点一遍。
顺便说一句，phpipam 官方其实有 CSV 导入模块，需要额外装扩展，但它对 CSV 格式要求比较死板，出错的时候你只能在界面上看到一个笼统的提示，配合不了复杂的数据清洗逻辑。API 方式的好处是逻辑完全掌握在自己手里，数据清洗、字段映射、失败重试都可以用代码精确控制。
1.3 什么时候不该用 API 批量导入
这里说点反的。不是所有场景都值得写脚本。
如果只是临时加三五个 VLAN、十几条 IP，那直接在 Web 界面点，反而比写脚本快。如果源数据的质量本身很差——Excel 里一堆空行、IP 格式五花八门、VLAN 编号和实际需求都对不上——那第一步应该是跟数据负责人把表格理干净，而不是急着写导入脚本，否则脚本只是把垃圾数据搬进 phpipam，后面的维护成本只会更高。
还有一个容易被忽略的问题：脚本是需要人维护的。如果你们团队没有人能长期维护这