Docker Compose部署phpipam：企业IP地址管理的容器化实践

1. 部署前的思路与规划1.1 为什么选择用Docker跑phpipam做运维和网络管理的人对IP地址管理这事应该都不陌生。公司设备一多网络一复杂Excel表格记IP的方式基本就是灾难谁改的、什么时候改的、网段里还空着哪些地址全靠人工维护到头来对不上账是常态。早期我也试过用自建的轻量应用去管但功能太弱连个子网自动划分都做不到。后来接触到phpipam这个开源项目一个基于PHP的IP地址管理平台界面清爽、功能扎实子网划分、IP分配、状态跟踪、VLAN管理、设备关联这些常见的需求都有覆盖而且它还带API和自定义字段能跟内部系统做联动基本就是轻量版的商业IPAM工具。phpipam的部署方式其实有好几种可以源码装到一台机器上也可以直接容器化。我这边经历了几次环境迁移之后彻底转向了Docker部署这条路线。原因很直接phpipam依赖的环境不算复杂但要装对也有一堆细节Apache、PHP版本、MySQL连接、扩展模块哪个版本配不对就会踩坑。用Docker以后整个平台被封装成独立的容器本地跑、服务器上跑、迁移的时候跑依赖关系全部交给镜像去管理需要关心的就只剩下数据本身。特别是测试环境和生产环境要保持一致的时候Docker Compose一把拉起省掉了大量重复劳动。另一个很多人忽略的点是回滚。phpipam升级的时候如果走传统方式直接在服务器上覆盖代码一旦新版有问题很难退回去风险比较高。用了容器镜像之后启动新容器之前保留旧镜像随时可以切回去。这种可回滚的能力对于管理核心网络资产的工具来说非常重要。1.2 部署形态选择单机Compose还是集群方案初学或者中小规模网络环境我推荐直接用Docker Compose跑一套单机方案这是目前最主流也最省心的方式。phpipam官方提供两个关键镜像一个跑Web前端一个跑数据库基于MariaDB。Compose文件把这两个服务管理起来数据卷做持久化端口映射到局域网加一个健康检查这就可以用了。如果是几百人的公司、上千台设备的网络规模其实单机Compose也完全撑得住。phpipam对硬件的要求不高PHP进程和数据库都在一台机器上跑日常查询和操作的数据量并不大。需要横向扩展的场景极少除非你要对接多个地域、多条链路的大量自动探测任务那才考虑拆分部署或者用容器编排平台把Web节点和数据库节点分开扩容。调研阶段我对比过几种方案裸金属源码安装、单机Docker、Kubernetes部署。裸金属安装的劣势最明显升级和备份都要自己手动管理文件不方便。Kubernetes部署phpipam有点杀鸡用牛刀虽然能实现节点调度和滚动更新但引入的复杂度远大于收益除非公司本来就有成熟的K8s平台否则不建议为了phpipam单独搭一套。折中下来Docker Compose方案是性价比最高的选择安装快、可迁移、结构清晰、时间成本低。2. 快速部署实操从零到可用2.1 准备环境与获取镜像部署前需要准备的东西并不多一台Linux服务器或者一台虚拟机就够建议给个2核4G的配置磁盘空间尽量给足30GB以上因为后面还有日志、备份、镜像缓存这些占空间。操作系统可以用Debian、Ubuntu这种主流发行版CentOS Stream也可以关键在于要装好Docker Engine和Docker Compose插件。我这里用一个全新的Ubuntu Server 22.04环境做示例。# 安装Docker Engine Compose插件 sudo apt update sudo apt install -y docker.io docker-compose-v2 sudo systemctl enable --now docker docker --version docker compose versionDocker装好之后可以从Docker Hub拉取phpipam相关镜像。官方镜像名是phpipam/phpipam-www和phpipam/phpipam-mariadb一个带Web服务一个带数据库。不必急着先拉直接写Compose文件然后统一拉取也行。需要注意的是网络环境有时拉取镜像会比较慢可以在Docker的daemon.json里配置国内镜像加速地址这算是大家在实操中都会遇到的经验点。我用的是官方镜像稳定版标签。镜像标签可以选择分支构建版本比如latest就代表当前最新稳定发布。用官方镜像的好处是phpipam的源码打包、PHP扩展、Apache配置都已经处理好了不用自己动手改环境真正需要关注的只是数据库和站点配置。2.2 编写docker-compose.yml文件这里我直接贴一份完整可用的Compose配置文件稍微做一些注释说明方便你根据实际情况调整。services: phpipam-web: image: phpipam/phpipam-www:latest container_name: phpipam-web hostname: ipam ports: - 8080:80 environment: TZ: Asia/Shanghai IPAM_DATABASE_HOST: phpipam-db IPAM_DATABASE_USER: phpipam IPAM_DATABASE_PASS: your_strong_password IPAM_DATABASE_NAME: phpipam IPAM_DATABASE_PORT: 3306 volumes: - phpipam_assets:/var/www/html - ./backup:/srv/backup restart: unless-stopped depends_on: phpipam-db: condition: service_healthy networks: - ipam-net phpipam-db: image: phpipam/phpipam-mariadb:latest container_name: phpipam-db environment: TZ: Asia/Shanghai MYSQL_ROOT_PASSWORD: your_root_password MYSQL_DATABASE: phpipam MYSQL_USER: phpipam MYSQL_PASSWORD: your_strong_password volumes: - phpipam_db:/var/lib/mysql restart: unless-stopped healthcheck: test: [CMD, healthcheck.sh, --connect, --innodb_initialized] interval: 15s timeout: 5s retries: 3 networks: - ipam-net volumes: phpipam_db: phpipam_assets: networks: ipam-net: driver: bridge简单拆解一下这份文件背后的设计考虑。Web容器里最关键的环境变量是数据库连接信息。phpipam安装向导会读取这些变量去连接后端的MariaDB容器。这里的IPAM_DATABASE_HOST不能写localhost因为Web容器和数据库容器是分开的必须是用Docker网络内的服务名也就是phpipam-db来解析。数据库容器里设置了MYSQL_ROOT_PASSWORD、MYSQL_DATABASE、MYSQL_USER和MYSQL_PASSWORD。phpipam默认使用独立用户连接数据库这里就顺手创建了phpipam库和phpipam用户。需要提醒一句不要省掉MYSQL_ROOT_PASSWORDMariaDB官方镜像如果不给root密码会在首次初始化时自动生成一个随机密码后面排查问题会非常麻烦。数据持久化方面数据库数据放在phpipam_db这个Docker卷里即使容器删除重建数据也不会丢。Web资产目录phpipam_assets则保存上传的文件、图标或后续插件。backup目录挂载到Web容器里方便在网页后台或命令行执行备份时把备份文件写出来。端口映射选了8080是因为80端口可能已经被其他服务占用你可以根据自己的实际情况改成任意端口比如8000、8081。容器内部Web服务监听的是80端口这是phpipam镜像固定的不需要修改。依赖关系和健康检查这块要注意。Web容器加depends_on条件并且要求数据库容器通过service_healthy状态才启动。如果没有这个条件第一次启动的时候Web容器可能比数据库先跑起来安装向导连接数据库就会报错。数据库容器的healthcheck用了MariaDB镜像自带的健康检查脚本仅通过TCP端口探测是不够的因为MySQL/MariaDB容器在初始化期间也监听端口但还没准备好接受连接。用这个脚本可以真正等到数据库初始化完成。2.3 启动与安装向导配置文件里写到容器之间的协同执行启动命令其实就一步cd /path/to/your/compose/dir docker compose up -d第一次执行的时候会拉取镜像耐心等一段时间。看到容器状态为Up之后访问 http://你的服务器IP:8080/ 就会出现phpipam的安装向导页面。安装向导第一个界面是语言选择支持中文可以直接切到中文界面后面维护的人看着也更舒服。第二步是数据库连接配置这部分是本项目的核心要点数据库主机填写phpipam-db就是Compose文件里数据库服务的名称数据库管理员用户名填写root密码填Compose文件里MYSQL_ROOT_PASSWORD对应的值。填好之后点测试数据库连接等待提示OK再进行下一步。接下来向导会提示创建phpipam管理员账号。这里的管理员账号是Web界面登录用的跟数据库的root用户是两回事。建议用户名不要用默认的admin改动一下更安全密码也尽量设置得长一些毕竟它管理着整个公司的网络地址规划信息重要性不亚于一个内部系统的管理员权限。安装向导跑完之后就能直接登录后台了。登录成功后后台首页会展示当前的一些状态信息包括数据库版本、PHP版本、IP分配情况统计等。到此部署已经完成整个下来不超过15分钟这就是容器化部署最大的优势。3. 核心配置与优化让平台更贴合实际需求3.1 Web服务器与时区参数调优很多人在部署完phpipam之后就直接用了其实有几步优化能让整个平台更顺手、更稳定。首先是时区问题。Compose文件里虽然设置了TZ为Asia/Shanghai但phpipam自身的PHP配置默认时区可能是UTC。如果不去调整后台记录的操作时间、检测历史、IP分配时间都会比本地时间差8小时排查问题的时候非常容易混淆。通过后台管理界面的设置路径可以改PHP的date.timezone参数或者修改容器内php.ini文件后重启容器。我的建议是直接把时区参数注入到环境变量里比较省事但phpipam官方镜像并不直接读取TZ来设置PHP时区所以需要在安装完成后去后台系统的管理设置里调整。具体路径是管理员登录后点右上角菜单进入系统管理找到首选项设置把时区字段改成Asia/Shanghai。保存之后系统的时间记录就和本地时间一致了。这个操作建议部署完成之后第一时间做免得后续数据混乱。Web服务器层面Apache默认的KeepAlive和并发配置其实可以适当调整。访问量不大就不用动但当你有上百个用户同时在线操作时默认参数可能显得不够。phpipam官方文档也提到了可以修改Apache的MPM配置来提高并发上限在容器里可以通过挂载自定义的appache配置来实现。不过对于绝大多数场景保持默认配置已经够用真正会遇到的瓶颈更多还是在数据库连接数这边。3.2 数据库备份策略与自动化phpipam这类工具最怕的就是数据丢失。IP地址规划、子网划分信息、设备关联记录都是长期积累的资产一旦丢失恢复成本极高甚至可能直接导致网络梳理工作回到原点。所以备份策略必须在部署完成后立刻规划好不要等出了事故再补救。最简单的备份方式是使用phpipam后台自带的备份功能。登录Web界面后进入管理页面里的服务器管理可以设置定期备份任务。备份文件会写到容器里的/srv/backup目录也就是上面Compose文件中挂载到宿主机./backup目录的位置所以宿主机上就能直接看到备份文件。这种方式备份的是数据库内容生成的是压缩SQL文件用于恢复已经足够了。如果要自动化宿主机上写一个cron任务即可。这里给一个参考的shell脚本#!/bin/bash BACKUP_DIR/your/backup/path DATE$(date %Y%m%d_%H%M%S) docker exec phpipam-db sh -c exec mariadb-dump --all-databases -uroot -p$MYSQL_ROOT_PASSWORD $BACKUP_DIR/phpipam_$DATE.sql find $BACKUP_DIR -name phpipam_*.sql -mtime 30 -delete这个脚本每天凌晨执行一次将数据库全部导出并清理30天以上的旧备份。脚本里需要把密码变量改成自己的环境变量写法。需要注意的一点是容器内如果用了环境变量直接在脚本里引用比较麻烦可以用env命令在容器内输出环境变量但更稳妥的方式是直接在宿主机上读取Compose配置或者把密码写到脚本里并保证文件权限为600。为了安全我会把数据库密码提取到宿主机的一个.env文件里这样docker compose本身可以读取备份脚本也可以引用避免多处维护密码。自动备份脚本写好后加到croncrontab -e 0 2 * * * /usr/local/bin/backup_phpipam.sh /dev/null 21每周最好还做一次异地备份或者复制到对象存储这是额外的一道保险。备份文件一定要定期做恢复演练我之前就遇到过SQL文件生成成功但恢复时因为字符集问题失败的情况不演练根本发现不了。 phpipam的数据库字符集默认是utf8mb4恢复时指定一下字符集能少很多坑。3.3 通过VLAN子网规划把平台用起来部署和基础配置完成后就该往平台里导入真实的网络数据了。phpipam的强大之处在于它的子网划分和层次结构。首先创建机房或者区域这些顶层分类然后在分类下增加网段。比如公司有两个办公区每个办公区有多个VLAN就可以按区域建文件夹再在文件夹里建子网子网还能继续划分子文件夹形成树状结构。如果是已有网络迁移到phpipam可以使用CSV导入功能。做好网段CSV文件包含子网地址、掩码、描述、VLAN号等字段后台直接导入非常高效。导入之前建议先看官方提供的CSV模板格式对不上会报错。我在做数据迁移时的经验是先导入一个测试网段验证格式确认没问题后再批量导入避免一次性导入几千条数据后发现字段错位。phpipam对IPv4和IPv6都支持。IPv6的规划比IPv4更复杂因为前缀长度和地址空间的概念完全不同。phpipam的IPv6子网计算是基于二进制跟分割的用图形化界面操作比手工计算省太多时间。对于做企业网络规划的同行来说这是提升工作效率的利器。IP状态管理操作上分配地址给设备时可以选择状态比如used、reserved、DHCP等还能关联到具体设备、用户或者自定义字段。这些状态数据对于日常排障很有帮助比如你看到一个IP状态为reserved就不会再把它拿去分配了避免冲突。4. 常见问题与排查技巧实录4.1 安装向导连接数据库失败用Docker Compose部署很多人第一次跑安装向导时在数据库连接这一步卡住报错信息提示无法连接MySQL服务或者连接超时。这个问题的原因绝大多数出在数据库主机名写错或者Web容器和数据库容器不在同一个网络里。检查思路很清晰。先确认两个容器是否都在运行docker compose ps再确认两个容器是否在同一个Docker网络里docker network inspect ipam-net在Web容器里测试能否ping通数据库主机名docker exec phpipam-web ping phpipam-db如果网络正常、服务正常还是连不上就看一下数据库容器的日志docker logs phpipam-db如果日志里出现权限错误之类的提示可能是因为之前跑过不同配置的数据库容器旧卷里保留了初始化信息新密码没有生效。这种情况需要把旧的Docker卷删掉重新初始化。处理命令是docker compose down -v但注意这会清空所有数据只适合首次安装失败的场景生产环境不要轻易用。安装失败多次时我会选择换一个卷名或者手动清理旧的docker volume而不是直接顺手down -v。4.2 容器一直重启或陷入CrashLoopBackOff状态Compose进程启动后如果Web容器一直处于Restarting状态多半是环境变量配置问题。比如IPAM_DATABASE_PASS和数据库容器的MYSQL_PASSWORD不一致phpipam启动时验证不了数据库连接就会不断重试。这种问题要靠日志来判断docker logs phpipam-web如果日志中明确出现了Access denied for user那说明用户名密码确实对不上。只要把两边环境变量改成一致然后重建容器即可。这里有一个小技巧环境变量比较多的时候专门维护一个.env文件docker compose会自动读取文件内容填充变量比在yml里硬编码密码更规范也更好管理。4.3 升级过程中的备份与回滚方法phpipam官方每个季度会发布新版本升级操作听起来复杂但其实容器化之后非常机械。整个流程我总结为四步备份数据库、拉取新镜像、重建容器、检查页面。第一步是备份上面已经提到过用mariadb-dump导出所有数据库升级前一定要做这一步不能跳过。第二步拉取新镜像可以把compose文件里的tag改成新版本或者直接保持latest然后执行docker compose pull。第三步重建容器docker compose up -d会让容器用新镜像重新创建。第四步检查后台功能是否正常尤其是子网计算、IP分配这些核心操作可以随手做一个小测试。万一升级后发现界面异常或者功能报错回滚也很简单。旧镜像还留着把compose文件里镜像tag改回原来的版本再docker compose up -d容器就能启动到旧版本。数据库方面如果升级脚本修改了数据库结构回滚代码后数据库可能不兼容旧版本这种情况下就需要通过之前备份的SQL来恢复了。所以备份这一步无论多熟练都应该保留。4.4 探测功能不生效的排查phpipam中的子网扫描和状态探测依赖ICMP和SNMP。如果在后台点扫描子网返回结果一直为空或者一直显示超时通常不是phpipam自身的问题而是容器内的工具链缺失或者网络限制。phpipam的Web镜像里包含了一些基础工具但某些高级探测可能依赖于主机的网络权限。最简单的测试方法是在Web容器里执行ping命令docker exec phpipam-web ping -c 4 8.8.8.8如果容器内无法ping通外网说明Docker网络的出站规则或者宿主机的iptables有阻隔。另外扫描使用的是Web容器发出的ICMP包宿主机防火墙如果禁掉了ICMP也会导致探测失败。针对常见环境我更推荐用后台的IPv4扫描方式它会先计算子网内主机的ARP表这个消息对同网段的设备更有效。还有一个常见坑是扫描目标设备开启了防火墙禁ping禁SNMP那不管怎么配都探测不到。这不算是部署问题但需要先确认目标设备本身的策略。4.5 使用体验相关的实用优化进阶一点可以考虑开启phpipam的API功能。在管理后台的用户设置里配置API权限创建App账号然后就可以通过REST API来查询和分配IP地址。比如在内部服务器上写一个脚本自动为新建的虚拟机分配IP并把对应的DNS记录和备注信息回填到phpipam这样就能实现IP地址的自动化闭环管理。我这边已经用脚本实现了新设备上线时自动申请IP从申请到记录全流程无人参与效率提升明显。另一个值得做的是配置邮件通知。phpipam支持在子网分配、IP变更时发送邮件通知。配置方法在后台的邮件设置里填上SMTP服务器、账号密码测试发送即可。对于多人团队运维的场景这个功能可以让成员实时知晓地址变化避免信息不对称造成冲突。最后建议打开登录二次验证phpipam支持TOTP双因素认证。网络管理后台属于敏感系统开启双因素认证之后即使账号密码泄露也能从身份验证层面多一道防线。在后台管理用户的地方可以强制管理员开启OTP非常实用。5. 后续扩展与长期维护建议5.1 自定义字段与资产关联phpipam支持自定义字段这是很多团队忽略但它特别好用的功能。默认的IP和子网字段只有描述、VLAN、设备这些基础项。你可以通过后台自主添加字段比如“负责人”、“资产编号”、“工单号”、“上架日期”。这样IP地址表就变成了一张可以追踪完整生命周期的资产表。我的一个实际做法是给每个IP添加的自定义字段包括“所属项目”、“到期日期”、“变更单号”。每次网络调整都能追溯到源头后续审计排查省了很多翻阅聊天记录和工单系统的时间。自定义字段在导入CSV时也能一并导入适合在迁移时扩展数据维度。5.2 容器健康与磁盘空间监控跑了一段时间后发现容器所在宿主机的磁盘空间被Docker卷占满的情况很常见。特别是数据库卷随着网络信息量增大增长速度虽然不快但日积月累也需要注意。建议用df -h定期查看磁盘使用率或者配置一个简单的监控脚本当磁盘使用率超过80%时推送告警。Docker自身的日志文件也可能占用空间。容器默认的日志驱动如果不做轮转长时间运行会产生很大的日志文件。在/etc/docker/daemon.json里可以设置log-driver和log-opts来做日志轮转限制每个容器的日志文件大小和数量。举一个我正在用的配置{ log-driver: json-file, log-opts: { max-size: 20m, max-file: 5 } }配置完成后重启Docker服务。这个操作对运行中的容器需要重建才生效建议在维护窗口期处理。5.3 与CMDB或工单系统联动phpipam提供了完善的API完全可以跟现有的配置管理系统或工单系统对接。比如当IT工单系统里创建了一个新网络需求系统自动调用phpipam的API去查找可用的IP段并预留一段空间给该项目然后在phpipam上创建对应的子网并打上工单号标签完成网络资源分配的自动化流程。这个方向的潜力很大尤其是团队规模大、每天有新设备上线的情况。虽然接入过程需要一点开发工作但API文档写得很清楚用Curl就能快速测试基础接口。我从一个简单的脚本开始逐渐扩展到了工单自动绑定、IP自动回收清理整体运维工作比之前减轻了一大截。我自己当时踩过一个坑API调用频率过高超出了phpipam对每个用户的请求配额导致脚本报错。解决方案是在API应用设置里把这个用户设置成无限制同时增加脚本中的sleep间隔减少不必要的请求。API联调阶段一定不要在生产环境上直接暴力测试可以先在测试实例上跑通再切到生产。6. 写在容器化部署之后从我最初在一台旧虚拟机上手工装环境到后来用Docker Compose一键拉起phpipam的部署体验完全换了一种模式。现在给我的客户或者团队搭一套新的IPAM环境基本就是复制一份compose文件改下密码和端口十分钟内就能交付一个干净可用的平台。维护成本也大幅下降不再需要为PHP版本或者Apache配置操心容器镜像统一管理升级只需换tag。要说有什么特别想提醒的就是容器化不等于万能保险数据备份和恢复演练仍然是整个体系里最需要重视的部分。环境可以随时重建但IP规划数据一旦丢失就真的没有任何妥协余地。我在一次模拟故障演练中故意停掉数据库容器然后从备份恢复整个过程发现备份脚本里没考虑到字符集问题恢复出来的数据全部乱码当场冷汗直流。所以最后再分享一个心得备份不是目的能正常恢复才叫备份。定期做恢复演练把备份文件放到一个独立目录确保脚本在无人值守时也能稳定执行这些基本功比任何花哨的部署方式都重要。这套Docker部署方法在单机场景非常稳健如果后续网络规模扩大需要多节点部署也可以基于这套Compose做改造把数据库容器换成高可用的数据库集群或者将Web容器扩容运行多实例前端通过负载均衡接入。那又是另一套方案了但对于大多数场景一套容器化的phpipam已经能帮你把IP资产管理这摊事处理得明明白白。