Poweradmin v4.4.3 配置参数详解

目标：把 Poweradmin v4.4.3 的配置体系一次讲透——两层配置文件的覆盖顺序、各组参数的含义与默认值，以及对每个关键参数执行的「修改 → 验证 → 恢复」实测闭环。本文全部回显取自一台按《Poweradmin v4.4.3 Docker Compose 部署指南》部署好的服务器，配合源码与官方镜像内出厂配置交叉验证。

一、配置体系与实验环境

1.1 两层配置文件与覆盖顺序

Poweradmin 的配置由两层 PHP 文件构成，后者覆盖前者中的同名键：

关键结论（决定排障思路）：官方部署形态下 settings.php 是生成物——修改它而不改环境变量，重启后会被重新生成覆盖。持久生效的唯一途径是改环境变量。

1.2 实验环境

1.3 验证方法

每个关键参数按两级验证，全部在上述服务器上执行：

1. 文件级：修改环境变量并重建服务后，读取生成的 settings.php，确认键值；
2. 行为级：用 curl 访问 Web 页面或 REST API，确认行为变化。

1.4 生成结果快照（本栈基线）

部署篇栈启动后生成的 settings.php 关键段实测（节选自 docker exec poweradmin-4.4.3-app cat /app/config/settings.php，下同）：

'database' => [
    'type' => 'mysql',
    'host' => 'db',
    'port' => '3306',
    'user' => 'poweradmin',
    'password' => 'q1w2e3r4',
    'name' => 'powerdns',
    'file' => '/db/pdns.db',
    'pdns_db_name' => '',
    ...
],
'dns' => [
    'backend' => 'sql',
    'hostmaster' => 'hostmaster.example.com',
    'ns1' => 'ns1.example.com',
    'ns2' => 'ns2.example.com',
    ...
],
'misc' => [
    'display_stats' => false,
    'timezone' => 'Asia/Shanghai',
    ...
],

misc.timezone 取值 Asia/Shanghai 来自环境变量 PA_TIMEZONE；database.password 等来自 DB_PASS。环境变量 → 配置键的完整映射规则见第十节。

二、数据库连接参数（database 组）

2.1 参数总表

2.2 两个 schema 的初始化

DB_NAME 库里会同时容纳两类表：Poweradmin 自身的 17 张表（users、perm_items、perm_templ、api_keys、log_api、log_zones 等）与 PowerDNS 的 7 张表（domains、records、cryptokeys、domain_metadata、comments、supermasters、tsigkeys）。部署篇实测：首次启动时 Poweradmin 自动灌入自己的表；设置 PA_INIT_PDNS_SCHEMA=true 后还会顺带灌入 PowerDNS 的 gmysql 表（合计 24 张，SHOW TABLES 回显见部署篇 3.2 节）。PA_INIT_PDNS_SCHEMA 在设置了 PA_PDNS_DB_NAME 时自动跳过（此时 PowerDNS 库由 PowerDNS 自己初始化）。

2.3 密码字符限制（实测坑）

出厂配置 settings.defaults.php 对 database.password 的注释原文：

'password' => 'your_password',  // AVOID: quotes, backslashes, line breaks

单引号、双引号、反斜杠、换行会导致启动时的配置文件生成失败。本栈示例密码 q1w2e3r4 即刻意避开了全部特殊字符。LDAP 绑定密码（PA_LDAP_BIND_PASSWORD）有同样的限制。

三、DNS 数据通路参数（dns 组）

3.1 dns.backend：两种数据通路

sql 模式下 Poweradmin 仍需要 PowerDNS API 连接用于 DNSSEC 操作（见第六节）；api 模式下 Poweradmin 自身表仍需要一个数据库（用户、权限模板存在本地库），但 zone 数据不再直连。

3.2 新建 zone 的默认值

这组参数决定「新建 zone」表单与自动生成 SOA 的初始值，全部被部署篇的 example.com 实测覆盖（创建后 SOA 回显 ns1.example.com hostmaster.example.com ...）：

注意部署篇实测坑：zone 类型下拉提交的是大写 MASTER/NATIVE，小写会被 Invalid or unexpected input given. 拒绝——PA_DNS_ZONE_TYPE_DEFAULT 同样必须写大写。

3.3 输入校验类参数

txt_auto_quote 默认关闭，与部署篇实测坑 4 直接相关：TXT 内容必须自带双引号，否则报 TXT record content must be enclosed in quotes.。内网环境批量录 TXT 时可设 PA_DNS_TXT_AUTO_QUOTE=true 免去手工引号。

3.4 实测闭环：TTL 与 zone 类型默认值

修改环境变量（节选）：

      PA_DNS_TTL: "3600"
      PA_DNS_ZONE_TYPE_DEFAULT: NATIVE

重建后读取生成结果（实测回显）：

        'ttl' => 3600,
        'zone_type_default' => 'NATIVE',

验证通过后已恢复为默认值 86400 / MASTER。

四、DNSSEC 参数（dnssec 组）

4.1 dnssec.enabled 与环境变量名

4.2 排障实录：PA_DNSSEC 是无效变量

第一轮实验把变量写成 PA_DNSSEC: "true"，重建后读生成结果（实测回显）：

    'dnssec' => [
        'enabled' => false,
    ],

服务不报任何错，变量被静默忽略。查官方镜像内启动脚本 /usr/local/bin/docker-entrypoint.sh 第 807 行：

    dnssec_enabled=$(to_php_bool "${PA_DNSSEC_ENABLED:-false}")

正确变量名是 PA_DNSSEC_ENABLED。改为该名后重建（实测回显）：

    'dnssec' => [
        'enabled' => true,
    ],

4.3 行为验证：界面入口变化

dnssec.enabled=false 时，zone 编辑页（/zones/1/edit）没有任何 DNSSEC 区块。设为 true 后同一页面渲染出 DNSSEC 区块（HTML 实测节选）：

<!-- DNSSEC -->
<div class="col-md-4">
    <h6 class="text-muted mb-3">DNSSEC</h6>
    <form method="post" action="" class="d-inline">
        <input type="hidden" name="_token" value="...">
        <button class="btn btn-outline-success btn-sm" type="submit" name="sign_zone">
            <i class="bi bi-shield-check me-1 text-success"></i>Sign zone
        </button>
    </form>
</div>

源码依据：/app/templates/default/edit.html 以 {% if pdnssec_use %} 控制该区块，控制器传入 'pdnssec_use' => $isDnsSecEnabled（取自 dnssec.enabled）。另经 OpenAPI 规范核验：Poweradmin 自身 REST API（v2）没有 DNSSEC 端点，签名操作只能在 Web 界面完成，或直接调用 PowerDNS 的 API（见第六节与 API 使用篇）。

实验后已把 PA_DNSSEC_ENABLED 移除，恢复默认关闭。

五、会话与安全参数（security 组）

5.1 security.session_key：最关键的安全项

该 key 用于会话数据加密与密码恢复令牌派生，必须改为 ≥32 字符的随机串。出厂默认值在源码里被显式列入黑名单（/app/lib/BaseController.php）：

private const MIN_SESSION_KEY_LENGTH = 32;
...
if (!is_string($key) || in_array($key, ['p0w3r4dm1n', 'change_this_key'], true)) {
    return _('Default session encryption key is used, please set it in your configuration file.');
}
if (strlen($key) < self::MIN_SESSION_KEY_LENGTH) {
    return _('Session encryption key is too short, please set a longer one in your configuration file.');
}

实测闭环：把 PA_SESSION_KEY 设为 12 字符的 pa-short-key 后重建。服务照常启动、启动日志显示 Configuration loaded successfully——短 key 不阻断启动。用 admin 登录后，页面头部渲染出告警横幅（实测回显）：

Session encryption key is too short, please set a longer one in your configuration file.

该告警仅对管理员可见（源码：'session_key_error' => $perm_is_godlike ? ... : false）。恢复 37 字符 key 后横幅消失。结论：生产部署若忘记改 key，唯一的暴露面就是管理员登录后的横幅，务必在上线检查清单里加入此项。

5.2 密码策略（password_policy）

实测闭环：设 PA_PASSWORD_MIN_LENGTH: "10" 后重建（实测回显）：

            'min_length' => 10,

注意部署篇管理员 q1w2e3r4（8 位）创建于该参数变更之前；策略只约束改密/新建用户时的输入，不追溯已有口令。

5.3 登录表单令牌：脚本化访问的前置条件

两者默认开启（3.9.0 引入）：登录表单和全部后台表单都要求一次性 CSRF 令牌。部署篇实测坑的直接原因即此——不先取令牌直接 POST 登录，一律被 302 打回登录页。脚本化登录的正确三步：

$ curl -s -c cookies.txt http://127.0.0.1:8131/login | grep -o 'name="_token" value="[^"]*"' | head -1 | sed 's/.*value="//;s/"//'
NM5M3TyMhTKS80fPm6I0--6gZv_xcjPGf-1sjgPL
$ curl -s -b cookies.txt -c cookies.txt -o /dev/null -X POST http://127.0.0.1:8131/login \
    --data-urlencode "_token=NM5M3TyMhTKS80fPm6I0--6gZv_xcjPGf-1sjgPL" \
    --data-urlencode "query_string=" --data-urlencode "userlang=en_EN" \
    --data-urlencode "username=admin" --data-urlencode "password=q1w2e3r4" \
    --data-urlencode "authenticate=Sign in"
$ curl -s -b cookies.txt -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8131/
200

生产环境不建议关闭这两项；仅在内网自动化测试且网络受控时考虑 PA_LOGIN_TOKEN_VALIDATION=false。

5.4 账户锁定（account_lockout）

公网可达的实例建议 PA_LOCKOUT_ENABLED=true。默认关闭，本轮未实测修改。

5.5 会话有效期

闲置超过该时长后需要重新登录。

六、PowerDNS API 集成参数（pdns_api 组）

本栈实测取值（生成结果）：

'pdns_api' => [
    'display_name' => 'PowerDNS',
    'url' => 'http://pdns:8081',
    'key' => 'pa-pdns-api-key-4.4.3',
    'server_name' => 'localhost',
    'timeout' => 10,
    ...
],

与部署篇 pdns.conf 中 api-key=pa-pdns-api-key-4.4.3 对应。用途分两种场景：dns.backend='sql' 时仅 DNSSEC 签名/rectify 操作走该 API；dns.backend='api' 时它是唯一数据通路，此组参数变成必填。

七、REST API 开关参数（api 组）

7.1 api.enabled：总开关

API key 的签发入口在 Web 界面「账户 → API Keys」（管理员可为自己或他人签发，pwa_ 前缀 64 位十六进制串）。注意 api.enabled 默认 false——部署篇与 API 使用篇能调通 /api/v2/* 的前提都是显式设了 PA_API_ENABLED=true。

实测闭环：把 PA_API_ENABLED 改为 "false" 重建后，携带有效 key 请求（实测回显）：

$ curl -s -w '\nHTTP:%{http_code}\n' -H "X-API-Key: pwa_a5b5...(略)" http://127.0.0.1:8131/api/v2/zones
{"error":true,"message":"The API feature is disabled in the system configuration."}
HTTP:403

同一时刻 /api/docs 仍返回 200、Web 界面正常——docs_enabled 与 enabled 相互独立。恢复 "true" 后带 key 请求回到 200：

{"success":true,"data":{"zones":[{"id":1,"name":"example.com","type":"MASTER","created_at":null}]},"message":"Zones retrieved successfully","meta":{"timestamp":"2026-10-26 15:10:59"}}

7.2 排障对照表

八、界面显示参数（interface 组）

8.1 标题与品牌

实测闭环：设 PA_APP_TITLE: PA-Lab 重建后，生成结果与页面双验证（实测回显）：

        'title' => 'PA-Lab',

<title>PA-Lab</title>

多套环境（生产/演练）共用同一套部署模板时，改标题是最快的区分手段。实验后已恢复默认。

8.2 语言与时区

8.3 列表与记录表单开关（节选）

实测闭环：设 PA_ROWS_PER_PAGE: "25" 后（实测回显）：

        'rows_per_page' => 25,

九、Poweradmin REST API 一览（配合 api 组）

api.enabled=true 且签发 key 后可用的全部端点（实查自本实例 /api/docs/v2/json 返回的 OpenAPI 规范，Poweradmin API V2 / 2.0.0，共 13 组资源）：

/v2/zones                          get post
/v2/zones/{id}                     delete get put
/v2/zones/{id}/metadata            get
/v2/zones/{id}/metadata/{kind}     delete get put
/v2/zones/{id}/owners              get post
/v2/zones/{id}/owners/{user_id}    delete
/v2/zones/{id}/records             get post
/v2/zones/{id}/records/bulk        post
/v2/zones/{id}/records/{recordId}  delete get put
/v2/zones/{id}/rrsets              get patch post put
/v2/zones/{id}/rrsets/{name}/{type}  delete get
/v2/users  /v2/groups  /v2/permissions  /v2/permission-templates
/v2/zone-templates（含 /records 子资源）

鉴权统一走 X-API-Key 请求头；zone 的增删改查、记录与 rrsets 批量操作、用户/组/权限模板管理全部 API 化。完整的请求/响应实测与 curl 脚本见《Poweradmin v4.4.3 API 使用详解》。

十、其余分组参数速览

以下分组本轮未逐项实测修改，默认值实查自官方镜像内 settings.defaults.php（855 行，v4.4.3），标注「引入版本」便于评估升级影响：

10.1 logging 组（审计与诊断两套日志）

审计与诊断是两套独立系统：前者记录「谁改了什么」（增删改、登录登出），后者记录应用错误。合规要求留操作痕迹的部署开 database_enabled 或 syslog_enabled。

10.2 mail 组（密码重置/通知依赖）

密码重置（security.password_reset.enabled，默认 false）与用户名找回依赖邮件通路；transport=logger 时邮件内容写 error_log，是调试重置流程的免 SMTP 手段。

10.3 认证扩展：LDAP / OIDC / SAML

三家默认全关；双因子认证 security.mfa.enabled（PA_MFA_ENABLED）同样默认 false，app_enabled/email_enabled 子开关默认 true。

10.4 modules 组与通知

十一、环境变量全量清单与无效变量排障

11.1 全量变量从哪里核对

官方镜像内 /usr/local/bin/docker-entrypoint.sh 是环境变量的唯一权威来源（官方文档站的环境变量表由 master 分支生成，包含 4.4.3 尚不存在的变量）。4.4.3 消费的 PA_* 变量共 180+ 个，提取命令与分组计数（实测）：

$ docker exec poweradmin-4.4.3-app grep -o 'PA_[A-Z_0-9]*' /usr/local/bin/docker-entrypoint.sh | sort -u | wc -l
183

按前缀分组：数据库 DB_*（12 个）与 DNS 默认值 DNS_*（5 个）；PA_DNS_* 22 个；安全 PA_PASSWORD_*/PA_LOCKOUT_*/PA_MFA_*/PA_PASSWORD_RESET_* 等 30+ 个；界面 PA_SHOW_*/PA_DISPLAY_*/PA_POSITION_* 等 20+ 个；认证 PA_LDAP_*/PA_OIDC_*/PA_SAML_* 合计 90+ 个；模块 PA_MODULE_* 18 个；API PA_API_* 5 个；PowerDNS 集成 PA_PDNS_* 8 个；邮件 PA_MAIL_*/PA_SMTP_* 12 个；管理员种子 PA_CREATE_ADMIN/PA_ADMIN_* 4 个。

11.2 排障实录：PA_WEB_ENABLED 在 4.4.3 无效

曾按官方文档站（master 分支生成）尝试 PA_WEB_ENABLED: "false" 以关闭 Web 界面、只留 API。重建后实测：GET / 照旧 302 到 /login、/login 200、带 key 的 /api/v2/zones 200——一切照常，变量无任何效果。回到 11.1 的提取清单核对：4.4.3 的 entrypoint 不消费 PA_WEB_ENABLED（它是后续 4.5+ 版本的特性）。结论：4.4.3 的 Web 界面无法用环境变量单独关闭；确有「仅 API」需求时，请升级版本或用反向代理在入口层封禁非 /api/ 路径。这也是「配置变量先查目标版本 entrypoint、再查文档站」的实证理由。

11.3 参数速查：五个高频坑

十二、参考链接

• 本文实验底稿：《Poweradmin v4.4.3 介绍与选型指南》（版本考证与架构）、《Poweradmin v4.4.3 Docker Compose 部署指南》（实验环境复现步骤）
• 官方 Settings Reference：https://docs.poweradmin.org/reference/settings/（由源码生成，注意该页对应 master 分支；4.4.3 以本文镜像内 settings.defaults.php 实测为准）
• 出厂默认值源文件：https://github.com/poweradmin/poweradmin/blob/v4.4.3/config/settings.defaults.php
• Docker 环境变量官方文档：https://github.com/poweradmin/poweradmin/blob/master/docs/docker.md（10.2 节的版本差异即源于此）