phpIPAM 1.8.3 配置参数详解

目标：逐项讲清 phpIPAM 1.8.3 的两个参数体系——应用配置文件 config.php（含官方模板 config.dist.php 全量参数）与数据库 settings 表（Web 界面 Administration 背后的参数），并给出生产可用的配置模板。已在 Ubuntu 22.04 + phpIPAM 1.8.3 + MariaDB 11.8 环境实测核对。

一、环境信息

• 操作系统：Ubuntu 22.04（x86_64）
• phpIPAM：v1.8.3（应用目录 /opt/phpipam，config.php 位于 /opt/phpipam/config.php）
• 数据库：MariaDB 11.8.9（实测 mariadb-dump 文件头）
• PHP：8.3.36（实测 php -v）
• 参数溯源：config.dist.php 官方模板全文实查（214 行）+ settings 表实查（SHOW COLUMNS 与 SELECT 实测）+ v1.8.3 官方 config.docker.php（环境变量入口文件）实查

💡 说明：phpIPAM 的参数分两层——文件层（config.php，改完即时生效，PHP 每次请求重新加载）与数据库层（settings 表，经 Web 界面 Administration → phpIPAM settings 修改）。文件层管「应用怎么连数据库、怎么渲染页面」，数据库层管「扫描怎么跑、功能开关与主题」。

二、前置条件

1. 已按部署指南完成 phpIPAM 1.8.3 安装并能登录（见《phpIPAM 1.8.3 Docker Compose 部署指南》）；
2. 能读取应用目录：本文所有文件路径以源码安装目录 /opt/phpipam 为例；
3. 数据库侧核对参数需要只读账号，能执行 SELECT/SHOW COLUMNS。

三、参数查看与修改方式

3.1 查看文件层参数

官方参数模板就是应用目录下的 config.dist.php（含全部默认值与注释）：

grep -nE "^\$" /opt/phpipam/config.dist.php | head -20

实测输出（节选，每行一个参数定义）：

6:$disable_installer = false;
11:$db['host'] = '127.0.0.1';
12:$db['user'] = 'phpipam';
13:$db['pass'] = 'phpipamadmin';
14:$db['name'] = 'phpipam';
15:$db['port'] = 3306;
26:$db['webhost'] = '';
39:$db['ssl']        = false;
47:$db['tmptable_engine_type'] = "MEMORY";
48:$db['use_cte'] = 1;
64:$trust_x_forwarded_headers = false;
71:$config['ping_check_send_mail']        = true;
72:$config['ping_check_method']           = false;
74:$config['discovery_check_send_mail']   = true;
75:$config['discovery_check_method']      = false;
77:$config['removed_addresses_send_mail'] = true;
78:$config['removed_addresses_timelimit'] = 86400 * 7;
80:$config['resolve_emptyonly']           = true;
81:$config['resolve_verbose']             = true;
82:$config['disable_main_login_form']     = false;

生效中的 config.php 是从 config.dist.php 拷贝修改而来（安装文档标准步骤）。核对实际生效值：

php -r 'require "/opt/phpipam/config.php"; var_dump($db["host"], $config["footer_message"]);'

实测输出（示例环境）：

string(10) "phpipam-db"
string(30) "演示环境，请勿录入真实地址"

3.2 修改文件层参数

编辑 /opt/phpipam/config.php 后保存即可，无需重启任何服务（PHP 每请求加载配置）。修改后用上面的 php -r 方式复核生效值。

⚠️ 注意：以官方编排镜像部署（见部署篇）时 config.php 是指向 config.docker.php 的软链，挂载自定义配置必须写完整自包含文件，否则 PHP 自引用死循环（陷阱与写法详见部署篇第八章）。

3.3 查看数据库层参数

settings 表一行存全部界面参数（id=1）：

mariadb -uphpipam -pq1w2e3r4 phpipam -e \
  "SELECT updateTags, scanPingType, scanPingPath, scanFPingPath, scanMaxThreads, pingStatus, inactivityTimeout, enableChangelog, log, version, dbversion, theme FROM settings WHERE id=1 \G"

实测输出：

*************************** 1. row ***************************
       updateTags: 0
     scanPingType: ping
     scanPingPath: /bin/ping
    scanFPingPath: /bin/fping
   scanMaxThreads: 128
       pingStatus: 1800;3600
inactivityTimeout: 3600
  enableChangelog: 1
              log: Database
          version: 1.83
        dbversion: 46
            theme: dark

日常不建议直改数据库层参数（绕过校验），应通过 Web 界面 Administration → phpIPAM settings 修改；直接 SELECT 用于核对与排障。

四、参数总览

文件层参数按用途分七类（默认值均实查 v1.8.3 config.dist.php）：

数据库层（settings 表）核心字段分四类：

💡 说明：settings 表还有 IPfilter、IPrequired、vlanDuplicate、vlanMax、autoSuggestNetwork、decodeMAC、hiddenCustomFields、permissionPropagate、subnetView、maintaneanceMode 等次级开关（实测 SHOW COLUMNS 全字段清单归纳），含义可在界面对应设置页看到，本文不逐项展开。

五、核心参数分类详解

5.1 数据库连接类（$db 数组）

安装必改的一组。config.php 中实际形态（安装时填写）：

$db['host'] = '127.0.0.1';
$db['user'] = 'phpipam';
$db['pass'] = 'q1w2e3r4';
$db['name'] = 'phpipam';
$db['port'] = 3306;
$db['webhost'] = '';

• host/port/user/pass/name：连接五要素。host 写数据库地址；应用与库同机时 127.0.0.1（走本地 socket，实测源码安装场景）或 localhost；
• webhost：仅在「自动安装/手工补授权」时使用——自动安装用 root 建业务用户时按它授权（'' 按 localhost 授权，% 任意主机，写 Web 服务器 IP 最收敛）。安装完成后不再参与运行；
• $db['ssl']（默认 false）：数据库连接 SSL 总开关。启用前先配好以下五项（默认全部注释态，路径为示例）：ssl_key（客户端私钥）、ssl_cert（客户端证书）、ssl_ca（CA 证书）、ssl_capath（CA 目录）、ssl_cipher（密码套件，默认建议 HIGH:!PSK:!SHA:!MD5:!RC4:!aNULL）、ssl_verify（是否校验 CN，默认 true）；
• $db['tmptable_engine_type']（默认 MEMORY）：复杂查询（大网段树、统计页）构造临时表的引擎。MEMORY 快但受内存限制，超大结果集报「table is full」时改 InnoDB；
• $db['use_cte']（默认 1）：递归 CTE 查询开关，用于网段树渲染。0=禁用，1=自动探测（MySQL 8.0+/MariaDB 10.2.1+ 生效），2=强制启用。数据库版本偏低且网段量小可设 0 换取兼容性，代价是大数据量时树渲染变慢。

💡 技术拓展：数据库连接加密方案不止 SSL 一条路。常见选项对比——

方案	原理	适用
$db['ssl'] 单向 TLS	客户端验证服务端证书	通用，最简单
双向 TLS（ssl_key+ssl_cert）	服务端同时验证客户端证书	合规要求高
ssh 隧道 / 专线	网络层隔离	无法改库端配置时
unix socket（host=localhost）	同机 socket 无网络暴露	应用与库同机

phpIPAM 同机部署（实测拓扑）走本地 socket，天然无需 SSL；跨机部署建议至少单向 TLS。

5.2 扫描与邮件类（$config['check' 系列]）

控制三个 CLI 扫描脚本的探测器与邮件通知（脚本本身见《phpIPAM 1.8.3 常用 CLI 命令与工具详解》）：

$config['ping_check_send_mail']        = true;   // pingCheck 结果是否发邮件
$config['ping_check_method']           = false;  // false/ping/pear/fping，强制指定探测器
$config['discovery_check_send_mail']   = true;   // discoveryCheck 是否发邮件
$config['discovery_check_method']      = false;  // 同上，作用于发现扫描
$config['removed_addresses_send_mail'] = true;   // remove_offline_addresses 是否发邮件
$config['removed_addresses_timelimit'] = 86400 * 7; // 失联多少秒后删除地址（默认 7 天）
$config['resolve_emptyonly']           = true;   // DNS 反解只补空缺主机名
$config['resolve_verbose']             = true;   // 反解脚本输出详细结果（cron 邮件可读）

• *_check_method：默认 false 表示跟随界面设置（settings.scanPingType）。有特殊需要时在文件里强制覆盖，例如服务器装了 fping 且网段大：设为 fping（实测 phpipam 运行环境自带 fping 5.5，路径 /usr/sbin/fping；社区版系统需自行安装）；
• removed_addresses_timelimit：默认 7 天。若未设置该参数，remove_offline_addresses.php 直接拒绝运行（实测脚本第 28 行 die 提示 Please set timelimit for address removal!）；
• $php_cli_binary（注释态）：多 PHP 版本共存时指定扫描脚本用的 php 解释器，默认取 PHP_BINDIR 的 php；
• $mysqldump_cli_binary（注释态）：指定备份用的 dump 二进制路径，MariaDB 11 环境注意可执行名是 mariadb-dump（mysqldump 别名已不存在，实测镜像内 mysqldump: not found）。

5.3 API 安全类

phpIPAM 自带 REST API（/api/），相关参数三个：

// $api_crypt_encryption_library = "mcrypt";   // 注释态，默认 openssl-128-cbc
$api_allow_unsafe = false;                     // 是否允许 HTTP 明文调用 API
$api_stringify_results = false;                // API 结果数值是否转字符串（兼容老消费者）

• $api_crypt_encryption_library：API 加密传输的密码库，1.3.2 起默认 openssl-128-cbc，可选 openssl-256-cbc（别名 openssl-256）与遗留 mcrypt；新建 App 建议显式写 openssl-256-cbc；
• $api_allow_unsafe（默认 false）：true 时允许无 TLS 的 HTTP 调用 security=none 的 App——仅限内网联调，生产保持 false；
• $api_stringify_results（默认 false）：PHP 8.1 起预处理语句返回原生 int/float，老脚本若按字符串比较会出错；可全局 true 或在单请求加 api-stringify-results: 0|1 头覆盖。

5.4 会话与 Cookie 类

$phpsessname = "phpipam";        // 会话 cookie 名
$cookie_samesite = "Lax";        // None / Lax(默认) / Strict
$session_storage = "database";   // database / files

• $cookie_samesite：Lax 兼顾安全与常规跳转；SAML2 部分拓扑要求 None（None 必须 HTTPS，自动带 Secure 属性）；内嵌 iframe 场景需评估 Strict 的影响；
• $session_storage：默认 database（多 Web 节点共享会话的前提）；files 形态仅适合单机且需自配 PHP session 目录权限。

5.5 部署形态类

define('BASE', "/");                    // 子路径部署改如 "/phpipam/"，须尾斜杠
define('MCUNIQUE', "section");          // 组播唯一性按 section 或 vlan
$trust_x_forwarded_headers = false;     // 反代场景 true
$disable_installer = false;             // true 禁用 /app/install/
$config['disable_main_login_form'] = false; // true 隐藏本地登录表单（纯 SAML/LDAP 场景）
$private_subpages = array();            // /app/tools/custom/ 下的私有应用白名单

• BASE：应用挂在域名子路径时必改（如 https://example.com/phpipam/ → "/phpipam/"）；根路径部署保持 "/"；
• $trust_x_forwarded_headers：1.6.0 起默认不信任转发头（官方 README 明示，防伪造）；挂 Nginx 反代后不开会产生「登录后无限跳回登录页」，开启后须确保反代覆写 X-Forwarded-* 全系列头；
• $disable_installer：安装完成、确认不再需要 /app/install/ 后设 true（1.7.0 起官方提供该开关加固安装脚本；编排镜像部署对应环境变量 IPAM_DISABLE_INSTALLER）；
• $disable_main_login_form：接入 SAML2/LDAP 做唯一认证入口时隐藏用户名密码表单，避免绕道本地认证。

5.6 代理与离线类

$proxy_enabled  = false;                     // 出站代理总开关
$proxy_server   = 'myproxy.something.com';
$proxy_port     = '8080';
$proxy_user     = 'USERNAME';                // $proxy_use_auth=false 时忽略
$proxy_pass     = 'PASSWORD';
$proxy_use_auth = false;
$offline_mode   = false;                     // true 禁用一切服务端外网请求
$disable_geoip_lookups = false;              // 关闭 OpenStreetMap 地址定位
// $failed_access_message = '';              // 登录失败写入 Web 日志的文本，可含 %u

• 内网隔离环境把 $offline_mode 设 true，一举关闭代理、地图与外部查询（避免页面卡在超时上）；
• $failed_access_message 配合 Fail2Ban 使用：写一条固定格式日志（%u 替换为尝试登录的用户名），供日志侧封禁。

5.7 UI 与杂项类

$debugging = false;                          // true 显示全部 PHP 错误（排障临时开）
$config['logo_width']             = 220;     // 左上角 logo 宽度像素
$config['requests_public']        = true;    // 登录页展示「IP 申请」入口
$config['split_ip_custom_fields'] = false;   // IP 编辑页自定义字段独立成表
$config['footer_message']         = "";      // 每页页脚文本（实测可自定义）

5.8 数据库层参数详解（settings 表，Web 界面）

以下参数在 Administration → phpIPAM settings 中修改，实测默认值照抄：

• 扫描参数：
  • scanPingType=ping：探测器 ping/fping/pear（大网段换 fping 提速）；
  • scanPingPath=/bin/ping、scanFPingPath=/bin/fping：探测器二进制路径（实测运行环境 fping 实际在 /usr/sbin/fping 时需按实际路径改此处，否则探测失败）；
  • scanMaxThreads=128：并发探测线程上限；
  • pingStatus=1800;3600：地址状态阈值——30 分钟未见标记「离线」、60 分钟未见标记「失联」（秒数对）；
  • updateTags=0：实测默认 0——扫描只刷新 lastSeen，不把地址状态标签翻成 Offline/Online；开启后 pingCheck 才会自动打标（配合 ipTags 表 updateTag 位，实测四个内置标签 Offline/Used/Reserved/DHCP 均允许自动更新）；
• 会话与安全：inactivityTimeout=3600（空闲 1 小时踢出登录）、2fa_provider（TOTP 双因子）、passkeys（1.7.0 起无口令登录）、passwordPolicy（口令复杂度策略）、enforceUnique（强制唯一地址）；
• 功能开关族：enableChangelog=1（地址/网段变更审计）、log=Database（日志落库，另有 syslog 选项）、enablePowerDNS/enableNAT/enableRACK/enableCircuits/enableRouting/enableCustomers/enableVaults/enableLocations 等模块开关，按需启用；
• 展示：theme=dark（另有 default 亮色）、visualLimit（网段树折叠阈值）、subnetOrdering、prettyLinks（友好 URL，Web 服务器需对应重写规则）。

六、生产配置模板

适用场景：2C4G 虚机、百级网段、千级地址、内网隔离（无外网）、MariaDB 与应用同机。文件 /opt/phpipam/config.php 在官方模板基础上只列改动项：

<?php
/* ===== 数据库连接（同机 socket） ===== */
$db['host'] = 'localhost';
$db['user'] = 'phpipam';
$db['pass'] = 'q1w2e3r4';
$db['name'] = 'phpipam';
$db['port'] = 3306;
$db['webhost'] = '';                 // 安装期已用，装完不影响
$db['use_cte'] = 1;                  // MariaDB 10.2.1+ 保持自动探测

/* ===== 部署形态 ===== */
if(!defined('BASE'))
define('BASE', "/");                 // 根路径部署
$trust_x_forwarded_headers = false;  // 无反代；挂反代改 true
$disable_installer = true;           // 安装已完成，禁用安装脚本
$debugging = false;

/* ===== API 安全 ===== */
$api_allow_unsafe = false;           // 禁 HTTP 明文 API
$api_stringify_results = false;

/* ===== 会话 ===== */
$phpsessname = "phpipam";
$cookie_samesite = "Lax";
$session_storage = "database";       // 多 Web 节点共享会话必选 database

/* ===== 扫描与邮件（大网段换 fping） ===== */
$config['ping_check_method']           = false;      // 跟随界面 scanPingType
$config['discovery_check_method']      = false;
$config['removed_addresses_timelimit'] = 86400 * 30; // 失联 30 天再删地址
$config['resolve_emptyonly']           = true;
$config['resolve_verbose']             = true;
// $config['footer_message'] = '内网资产管理平台';

/* ===== 离线环境 ===== */
$offline_mode = true;                // 关闭全部外网请求（地图/代理）
$disable_geoip_lookups = true;

数据库层建议（界面 Administration → settings）：updateTags=1（自动打标）、pingStatus=1800;3600 保持默认、scanMaxThreads 网段大且 CPU 富余时可提到 256、theme 按喜好、inactivityTimeout 内网可放宽到 7200。

修改后复核生效（文件层实测方式）：

php -r 'require "/opt/phpipam/config.php"; var_dump($offline_mode, $config["removed_addresses_timelimit"]);'

预期输出形态（值随模板）：

bool(true)
int(2592000)

七、常见问题（FAQ）

Q1：改了 config.php 不生效？ 先核对改的是生效文件：源码安装看 /opt/phpipam/config.php；确认无 OPcache 缓存 CLI 场景（CLI 默认无）；用 3.1 的 php -r 方式读值复核。编排镜像部署注意软链陷阱（见部署篇 Q4）。

Q2：开启扫描后地址状态标签不变化？ updateTags 实测默认 0（只刷新 lastSeen 不打标），到 Administration → settings 打开；同时注意 lastSeen 为 1970-01-01 的「从未见过」地址被源码豁免，不参与状态翻转（实测验证，见命令篇 pingCheck 一节）。

Q3：removed_offline 脚本报 Please set timelimit for address removal!？ config.php 未定义 $config['removed_addresses_timelimit']（从旧版本模板拷贝的 config 缺该键），按 5.2 补上即可（实测脚本对该参数硬校验）。

Q4：启用 BASE 子路径后样式丢失/跳转 404？ BASE 必须带尾斜杠（"/phpipam/"），且 Web 服务器的 Alias/重写规则要与之一致；prettyLinks 开启后还需对应的 URL 重写支持。

Q5：挂在反向代理后登录死循环？ $trust_x_forwarded_headers = true;（编排镜像部署用环境变量 IPAM_TRUST_X_FORWARDED=true），同时确保反代覆写 X-Forwarded-For/Host/Port/Proto 等头（官方 README 警告不覆写会被客户端伪造）。

Q6：大网段树渲染超时/临时表报错？ 优先确认 $db['use_cte']=1 且数据库为 MariaDB 10.2.1+/MySQL 8.0+（CTE 生效）；仍报「table is full」则 $db['tmptable_engine_type'] 改 InnoDB。

八、参考链接

• 官方参数模板（v1.8.3 config.dist.php）：https://github.com/phpipam/phpipam/blob/v1.8.3/config.dist.php
• 官方环境变量映射入口（config.docker.php）：https://github.com/phpipam/phpipam/blob/v1.8.3/config.docker.php
• 官方安装文档：https://phpipam.net/documents/installation/
• 本站相关文档：《phpIPAM 1.8.3 介绍与选型指南》（认知与选型）、《phpIPAM 1.8.3 Docker Compose 部署指南》（部署与环境变量）、《phpIPAM 1.8.3 常用 CLI 命令与工具详解》（扫描脚本实测）