phpIPAM 1.8.3 Docker Compose 部署指南

目标：从零开始用 Docker Compose 部署一套可用的 phpIPAM 1.8.3 IP 地址管理系统（Web + 数据库 + 扫描三角色），完成安装向导、管理员初始化、登录验证，并覆盖数据持久化、配置挂载、备份与升级。已在 Ubuntu 22.04 + Docker 29.8.1 + Docker Compose v5.5.1 环境全流程实测通过。

一、环境信息

• 操作系统：Ubuntu 22.04（x86_64）
• Docker：29.8.1（docker version 实测）
• Docker Compose：v5.5.1（docker compose version 实测）
• phpIPAM 版本：v1.8.3（官方镜像 phpipam/phpipam-www 与 phpipam/phpipam-cron，2026-10-21 构建）
• 数据库：MariaDB 11.8（镜像内实测 11.8.9-MariaDB）
• Web 端口：宿主机 8128 → 容器 80（80 已被占用的场景下选用 8128，可自行替换为 80/8080 等空闲端口）
• 应用安装目录（容器内）：/phpipam
• 数据落盘目录（宿主机）：/opt/phpipam/db（本文示例路径，可自行调整）
• Compose 项目名：phpipam-1.8.3-stack
• 内部网络：phpipam-net，显式指定子网 10.89.62.0/24（避免与既有网络段冲突时必填）

版本选型对照（2026-10-22 实查 Docker Hub tag 列表）：

关键差异：v1.8.3 固定版本便于复现与回滚，1.8x 浮动 tag 只在修订版间移动；生产建议锁定 v1.8.3 并在升级窗口切换 tag。

二、镜像选型说明

phpIPAM 官方将应用拆成两个角色镜像，配合一个数据库镜像组成三服务栈：

• phpipam/phpipam-www：Web 角色。内含 Apache 2.4.69 + PHP 8.3.36（mod_php），入口脚本 /start_apache2 以 Alias 方式把 /phpipam/public/（或整站 /phpipam/）挂到站点根，仅暴露 80 端口。应用代码位于镜像内 /phpipam/，config.php 在镜像内是指向 config.docker.php 的软链，后者通过环境变量完成参数注入。
• phpipam/phpipam-cron：扫描角色。与 www 同代码但入口是 /start_crond：根据环境变量 SCAN_INTERVAL 生成 crontab（/etc/crontabs/apache），固定三条计划任务——discoveryCheck.php（新主机发现）、pingCheck.php（存活检测）、resolveIPaddresses.php（DNS 反解），然后前台运行 crond。该角色不需要暴露端口。
• mariadb:11.8：数据库角色。phpIPAM 1.8.x 官方要求 MySQL 5.7.7+（强制 utf8mb4），推荐 MySQL 8.0+ / MariaDB 10.2.1+ 以启用 CTE 递归查询（网段树渲染依赖）。

为什么不合并 www 与 cron：扫描计划任务与 Web 请求的生命周期不同，官方镜像拆分后可以独立重启/升级 Web 而不打断扫描，也不必在 Web 容器里常驻 crond 进程。

三、前置条件

1. 已安装 Docker 与 Docker Compose 插件，并确认版本：

docker version --format 'Docker {{.Server.Version}}'

实测输出：

Docker 29.8.1

docker compose version

实测输出：

Docker Compose version v5.5.1

2. 规划一个未被占用的 Web 端口（本文用 8128），检查端口占用：

ss -ltn | grep -w 8128 || echo "8128 free"

实测输出（空闲时无监听行）：

8128 free

3. 创建数据目录（数据库文件落盘位置）：

mkdir -p /opt/phpipam/db

4. 若目标网段可能冲突，先查看现有网络占用：

docker network ls

实测输出（节选）：

NETWORK ID     NAME                          DRIVER    SCOPE
5f3a1b2c4d5e   bridge                        bridge    local
a1b2c3d4e5f6   host                          host      local
0f1e2d3c4b5a   phpipam-1.8.3-stack_phpipam-net  bridge  local

⚠️ 注意：docker network inspect <name> 可查看各网络子网；多套环境共存时，compose 里的 subnet 必须取未被占用的网段，否则启动报「Pool overlaps with other one on this address space」。

四、部署步骤

本节完成 compose 文件编写、栈启动、安装向导与管理员初始化。

4.1 编写 docker-compose.yml

创建部署目录与编排文件 /opt/phpipam/docker-compose.yml（与官方三角色拓扑一致）：

name: phpipam-1.8.3-stack

services:
  phpipam-db:
    image: mariadb:11.8
    container_name: phpipam-1.8.3-db
    restart: unless-stopped
    environment:
      - MYSQL_ROOT_PASSWORD=q1w2e3r4
      - MYSQL_DATABASE=phpipam
      - MYSQL_USER=phpipam
      - MYSQL_PASSWORD=q1w2e3r4
      - TZ=Asia/Shanghai
    volumes:
      - /opt/phpipam/db:/var/lib/mysql
    networks:
      - phpipam-net

  phpipam-www:
    image: phpipam/phpipam-www:v1.8.3
    container_name: phpipam-1.8.3-www
    restart: unless-stopped
    depends_on:
      - phpipam-db
    ports:
      - "8128:80"
    environment:
      - IPAM_DATABASE_HOST=phpipam-db
      - IPAM_DATABASE_PORT=3306
      - IPAM_DATABASE_USER=phpipam
      - IPAM_DATABASE_PASS=q1w2e3r4
      - IPAM_DATABASE_NAME=phpipam
      - IPAM_DATABASE_WEBHOST=%
      - TZ=Asia/Shanghai
    networks:
      - phpipam-net

  phpipam-cron:
    image: phpipam/phpipam-cron:v1.8.3
    container_name: phpipam-1.8.3-cron
    restart: unless-stopped
    depends_on:
      - phpipam-db
    environment:
      - IPAM_DATABASE_HOST=phpipam-db
      - IPAM_DATABASE_PORT=3306
      - IPAM_DATABASE_USER=phpipam
      - IPAM_DATABASE_PASS=q1w2e3r4
      - IPAM_DATABASE_NAME=phpipam
      - SCAN_INTERVAL=1h
      - TZ=Asia/Shanghai
    networks:
      - phpipam-net

networks:
  phpipam-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.62.0/24

配置逐项说明：

• name: phpipam-1.8.3-stack：显式 Compose 项目名，生成的网络名为 <项目名>_phpipam-net，避免同名默认项目互相覆盖；
• MYSQL_DATABASE/MYSQL_USER/MYSQL_PASSWORD：MariaDB 首次初始化时预建 phpipam 库与 phpipam 用户（安装向导会用到，见 4.3 的 dropdb 说明）；
• IPAM_DATABASE_WEBHOST=%：自动安装时为 phpipam 用户授权的来源网段，% 表示任意主机（Web 与数据库分离部署时按实际 Web 地址收敛）；
• SCAN_INTERVAL=1h：扫描周期，取值见第六章环境变量表；
• subnet：按第三章前置检查选取的空闲网段，单套环境可直接删除 ipam: 段让 Docker 自动分配。

4.2 启动栈

cd /opt/phpipam && docker compose up -d

实测输出：

 Container phpipam-1.8.3-db Starting
 Container phpipam-1.8.3-db Started
 Container phpipam-1.8.3-www Starting
 Container phpipam-1.8.3-cron Starting
 Container phpipam-1.8.3-www Started
 Container phpipam-1.8.3-cron Started

确认三角色状态：

docker compose ps

实测输出：

NAME                 IMAGE                         COMMAND                   SERVICE        CREATED          STATUS          PORTS
phpipam-1.8.3-cron   phpipam/phpipam-cron:v1.8.3   "/sbin/tini -- /bin/…"   phpipam-cron   13 seconds ago   Up 12 seconds   80/tcp
phpipam-1.8.3-db     mariadb:11.8                  "docker-entrypoint.s…"   phpipam-db     13 seconds ago   Up 12 seconds   3306/tcp
phpipam-1.8.3-www    phpipam/phpipam-www:v1.8.3    "/sbin/tini -- /bin/…"   phpipam-www    13 seconds ago   Up 12 seconds   0.0.0.0:8128->80/tcp, [::]:8128->80/tcp

验证 Web 服务已监听并跳转到安装向导：

curl -s -D- -o /dev/null http://127.0.0.1:8128/ | head -6

实测输出：

HTTP/1.1 302 Found
Date: Thu, 22 Oct 2026 10:12:36 GMT
Server: Apache
X-Powered-By: PHP/8.3.36
Cache-Control: no-store, no-cache, must-revalidate
Pragma: no-cache
Location: /index.php?page=install

💡 说明：返回 302 且 Location 指向 ?page=install，说明应用检测到数据库为空、自动进入安装向导；Server: Apache 与 PHP/8.3.36 也印证了 www 角色的运行时。

4.3 完成安装向导（浏览器操作）

浏览器打开 http://<服务器IP>:8128/，按以下步骤操作：

1. 欢迎页点击 New phpipam installation（全新安装；Migrate 用于迁移旧库）；
2. 数据库安装方式选择 Automatic database installation（由应用用 root 凭据自动建表授权）；
3. 表单填写（实测表单字段）：
   • MySQL username：root
   • MySQL password：q1w2e3r4（compose 中 MYSQL_ROOT_PASSWORD 的值）
   • MySQL database location：phpipam-db（页面自动带出，即 DB 服务名）
   • MySQL database name：phpipam（自动带出）
   • 勾选 drop existing database、create database、create grants 三项；
4. 点击 Install phpipam database，等待结果。

实测成功回显（页面提示框）：

Database installed successfully!  Continue

⚠️ 注意：因为 compose 里 MYSQL_DATABASE=phpipam 已让 MariaDB 预建了同名空库，必须勾选 drop existing database，否则安装报错（实测回显）：

SQLSTATE[HY000]: General error: 1007 Can't create database 'phpipam'; database exists

若不想用 root 凭据，也可以选 Manual database installation：手工执行 db/SCHEMA.sql 导入后继续。

5. 进入第二步 postinstall 配置页：设置管理员密码与站点信息——
   • Admin password / Re-type password：q1w2e3r4（不少于 8 位，两次一致）
   • Site title：phpipam
   • Site URL：http://<服务器IP>:8128/
6. 点击 Save settings，实测成功回显：

Settings updated, installation complete!  Proceed to login.

4.4 登录验证

浏览器访问 http://<服务器IP>:8128/，用 Admin / q1w2e3r4 登录（用户名首字母大写 A）。等价的接口级验证方式（浏览器登录失败排障时可用）：

curl -s -c /tmp/ck.txt "http://127.0.0.1:8128/index.php?page=login" -o /dev/null
curl -s -b /tmp/ck.txt -H "X-Requested-With: XMLHttpRequest" \
  -X POST "http://127.0.0.1:8128/app/login/login_check.php" \
  --data-urlencode "ipamusername=admin" --data-urlencode "ipampassword=q1w2e3r4"

实测输出：

<div class='alert alert-success'>Login successful</div>

登录成功后再查一次用户表确认落库（容器内执行）：

docker exec phpipam-1.8.3-db mariadb -uphpipam -pq1w2e3r4 phpipam \
  -e "SELECT username, lastLogin FROM users WHERE username='Admin';"

实测输出：

username        lastLogin
Admin   2026-10-22 18:16:34

至此 phpIPAM 1.8.3 部署完成，可开始建分区、录网段。

五、数据持久化说明

phpIPAM 的全部业务数据都在 MariaDB 中（应用本身无状态），因此持久化只针对数据库目录。compose 中：

    volumes:
      - /opt/phpipam/db:/var/lib/mysql

验证数据确实落在宿主机：

ls /opt/phpipam/db | head -8

实测输出（MariaDB 数据文件，节选）：

aria_log.00000001
aria_log_control
ib_buffer_pool
ibdata1
ib_logfile0
ib_logfile1
ibtmp1
multi-master.info
phpipam

重启验证持久化：docker compose restart phpipam-db phpipam-www 后重新登录，网段与用户数据不丢（lastLogin 等字段均保留在 /var/lib/mysql 的 InnoDB/Aria 文件中）。

六、环境变量表

6.1 phpIPAM 应用变量（www 与 cron 通用）

以下变量由镜像内 config.docker.php 读取（getenv() 映射，实查 v1.8.3 镜像），除注明外均为可选：

💡 说明：所有变量都支持 Docker secrets 语法——设置 IPAM_DATABASE_PASS_FILE=/run/secrets/dbpass 时，应用会从文件读取值（镜像内 file_env() 实现，实查 config.docker.php）。

6.2 cron 角色专用变量

SCAN_INTERVAL=1h 时镜像生成的计划任务（实查 /start_crond 逻辑）为：

0 *  *  *  * /usr/bin/php /phpipam/functions/scripts/discoveryCheck.php
0 *  *  *  * /usr/bin/php /phpipam/functions/scripts/pingCheck.php
0 *  *  *  * /usr/bin/php /phpipam/functions/scripts/resolveIPaddresses.php

6.3 MariaDB 变量

七、配置参数说明

环境变量只覆盖常用项；完整参数体系在应用配置文件中。镜像内应用目录为 /phpipam/，参数文件两个：

• config.dist.php：官方参数模板（全量默认值与注释，214 行，v1.8.3 实测）；
• config.docker.php：Docker 形态的入口配置，先 require('config.dist.php') 再用环境变量覆盖；config.php 是指向它的软链。

除环境变量外，以下高频参数只能改文件（默认值实查 config.dist.php）：

修改方式见下一章配置文件挂载。数据库侧的运行参数（updateTags、scanPingType、pingStatus 阈值、主题等）不用改文件，在 Web 界面 Administration → phpIPAM settings 中调整，落库于 settings 表。

八、配置文件挂载

想覆盖环境变量之外的参数时，把自写 config.php 挂进应用目录。用 compose override 追加：

services:
  phpipam-www:
    volumes:
      - ./conf/config.php:/phpipam/config.php:ro

⚠️ 重要陷阱（实测踩坑）：镜像内 /phpipam/config.php 是指向 /phpipam/config.docker.php 的软链。单文件 bind mount 挂到 /phpipam/config.php 时，Docker 会解析软链、把文件落到软链目标 config.docker.php 上。因此自定义 config.php 必须写成完整自包含配置（复制 config.docker.php 全文再追加覆盖项）；如果写成 require('config.docker.php') 的补丁式文件，PHP 会无限自引用，Apache 全部 worker 卡死，症状为页面从「空白响应」恶化为「连接超时」。

实测的正确写法（全文以 config.docker.php 内容开头，末尾追加）：

<?php
/* ……此处为镜像 config.docker.php 原文全文（file_env 函数与全部 IPAM_* 变量映射，勿省略）…… */

/* 实验覆盖项 */
$config['footer_message'] = '演示环境，请勿录入真实地址';

修改挂载文件后无需重建服务（bind mount 内容实时可见，PHP 每次请求重新加载配置），验证生效：

docker exec phpipam-1.8.3-www php -r 'require "/phpipam/config.php"; echo $config["footer_message"], "\n";'

实测输出：

演示环境，请勿录入真实地址

刷新登录页可见页脚文本已变更（grep 计数 1，实测）。

九、等价 docker run

与上述 compose 等价的 docker run 命令（便于理解栈结构与单机手工拉起）：

# 1. 创建内部网络
docker network create --subnet 10.89.62.0/24 phpipam-net

# 2. 数据库
docker run -d --name phpipam-1.8.3-db \
  --network phpipam-net \
  -e MYSQL_ROOT_PASSWORD=q1w2e3r4 \
  -e MYSQL_DATABASE=phpipam \
  -e MYSQL_USER=phpipam \
  -e MYSQL_PASSWORD=q1w2e3r4 \
  -e TZ=Asia/Shanghai \
  -v /opt/phpipam/db:/var/lib/mysql \
  mariadb:11.8

# 3. Web
docker run -d --name phpipam-1.8.3-www \
  --network phpipam-net \
  -p 8128:80 \
  -e IPAM_DATABASE_HOST=phpipam-db \
  -e IPAM_DATABASE_PORT=3306 \
  -e IPAM_DATABASE_USER=phpipam \
  -e IPAM_DATABASE_PASS=q1w2e3r4 \
  -e IPAM_DATABASE_NAME=phpipam \
  -e IPAM_DATABASE_WEBHOST=% \
  -e TZ=Asia/Shanghai \
  phpipam/phpipam-www:v1.8.3

# 4. 扫描/计划任务
docker run -d --name phpipam-1.8.3-cron \
  --network phpipam-net \
  -e IPAM_DATABASE_HOST=phpipam-db \
  -e IPAM_DATABASE_PORT=3306 \
  -e IPAM_DATABASE_USER=phpipam \
  -e IPAM_DATABASE_PASS=q1w2e3r4 \
  -e IPAM_DATABASE_NAME=phpipam \
  -e SCAN_INTERVAL=1h \
  -e TZ=Asia/Shanghai \
  phpipam/phpipam-cron:v1.8.3

日常仍建议用 compose 管理（down/up 不会因漏带参数导致配置漂移）。

十、常用运维命令

cd /opt/phpipam

# 查看三角色状态
docker compose ps

# 实时日志（Web 报错、扫描调度）
docker compose logs -f phpipam-www
docker compose logs -f phpipam-cron

# 重启单个角色
docker compose restart phpipam-www

# 拉取新镜像（升级前）
docker compose pull

docker compose pull 实测输出（已是最新 tag 时）：

 Image phpipam/phpipam-www:v1.8.3 Pulled
 Image phpipam/phpipam-cron:v1.8.3 Pulled
 Image mariadb:11.8 Pulled

10.1 备份与恢复

备份用 mariadb-dump（MariaDB 11.8 镜像内没有 mysqldump 命令，实测 mysqldump 报 sh: 1: mysqldump: not found，须用 mariadb-dump）：

docker exec phpipam-1.8.3-db mariadb-dump -uphpipam -pq1w2e3r4 phpipam > /opt/phpipam/phpipam-backup.sql

实测：导出文件 68935 字节（全新安装库，1822 行，含 70 条 CREATE TABLE/INSERT 语句），文件头：

/*M!999999\- enable the sandbox mode */
-- MariaDB dump 10.20-11.8.9-MariaDB, for debian-linux-gnu (x86_64)
--
-- Host: localhost    Database: phpipam

恢复（导入到空库）：

docker exec -i phpipam-1.8.3-db mariadb -uphpipam -pq1w2e3r4 phpipam < /opt/phpipam/phpipam-backup.sql

另注：/opt/phpipam/db 本身就是完整数据目录，停栈状态下做文件级备份（tar）亦可。

10.2 升级

phpIPAM 镜像升级按「先备份、后切 tag、Web 内完成数据库升级」三步（流程依据官方升级文档 phpipam.net/documents/upgrade/）：

# 1. 备份数据库（见 10.1）
docker exec phpipam-1.8.3-db mariadb-dump -uphpipam -pq1w2e3r4 phpipam > /opt/phpipam/pre-upgrade.sql

# 2. 修改 compose 中两个 phpipam 镜像 tag（www 与 cron 必须同步改）
#    image: phpipam/phpipam-www:v1.8.4   （以发布页最新修订版为准）
#    image: phpipam/phpipam-cron:v1.8.4

# 3. 拉取并滚动重建
docker compose pull && docker compose up -d

若目标版本包含数据库结构变更，升级镜像后访问 http://<服务器IP>:8128/index.php?page=upgrade，页面会列出待执行的 DB 版本差异并一键升级（phpIPAM 的 DB 版本号存于 settings 表 dbversion 字段，v1.8.3 实测值为 46）。回滚：compose tag 改回 v1.8.3 执行 up -d，并用 pre-upgrade.sql 恢复数据库。

10.3 卸载

cd /opt/phpipam
docker compose down            # 停止并移除三服务与网络（数据目录保留）
rm -rf /opt/phpipam/db         # 彻底清除数据（不可逆，先确认备份）

十一、常见问题（FAQ）

Q1：安装向导报 1007 Can't create database 'phpipam'; database exists？ compose 里 MYSQL_DATABASE=phpipam 已预建同名库。勾选向导中的 drop existing database 再装（实测验证），或初始就不设 MYSQL_DATABASE 只设 root 密码。

Q2：接口/脚本方式提交安装报 Invalid request？ 安装与登录接口校验 X-Requested-With: XMLHttpRequest 头（实测，缺失即报 Invalid request）。浏览器操作不受影响；用 curl 复现浏览器行为时补上该头即可（见 4.4）。

Q3：容器里找不到 mysqldump？ MariaDB 11.8 镜像只带 mariadb-dump/mariadb 命令（实测 mysqldump: not found），全部换用 mariadb-dump 与 mariadb 客户端。

Q4：挂载自定义 config.php 后整站无响应？ 单文件挂载落在软链目标 config.docker.php 上，补丁式 require('config.docker.php') 造成自引用死循环（实测症状：空白响应→连接超时）。改用完整自包含配置（见第八章陷阱说明）。

Q5：挂在 Nginx 反代后登录页无限跳转？ 1.6.0 起应用默认不信任 X-Forwarded-* 头，反代场景在 www 与 cron 上加 IPAM_TRUST_X_FORWARDED=true（官方 README 明示），并确保反代覆写这些头防止伪造。

Q6：建了网段但扫描迟迟无结果？ 三件事都要满足：网段编辑页勾选 check subnet for new hosts / status updates（对应 subnets 表 discoverSubnet/pingSubnet）；Administration → settings 中 updateTags 开启（实测默认 0，关闭时只刷新 lastSeen 不改状态标签）；地址 lastSeen 为 1970-01-01（从未见过）的记录不参与状态翻转（v1.8.3 源码 update_address_tag 明确豁免）。CLI 细节见命令篇。

Q7：Web 与数据库分离（非 compose）时自动安装授权失败？ 设置 IPAM_DATABASE_WEBHOST 为 Web 服务器实际地址或 %，否则自动安装按 localhost 授权，Web 连不上库。

十二、参考链接

• 官方安装文档：https://phpipam.net/documents/installation/
• 官方升级文档：https://phpipam.net/documents/upgrade/
• 官方 Docker 镜像：https://hub.docker.com/r/phpipam/phpipam-www
• GitHub 仓库（docker/ 目录含镜像构建文件）：https://github.com/phpipam/phpipam
• 本站相关文档：《phpIPAM 1.8.3 介绍与选型指南》（认知与选型）、《phpIPAM 1.8.3 配置参数详解》（参数逐项说明）、《phpIPAM 1.8.3 常用 CLI 命令与工具详解》（扫描脚本与命令行）