PowerDNS 5.1.4 配置参数详解

目标：系统梳理 PowerDNS Authoritative Server 5.1.4 的配置参数体系——参数的查看与修改方式、170 个参数的分类总览、8 大类核心参数的逐项解读（默认值均取自实机 pdns_server --config=print 输出），并给出两档生产配置模板。全部默认值与验证命令在 Ubuntu 22.04.4 LTS 真实服务器实测通过（实测日期 2026-10-20）。

一、环境信息

• 操作系统：Ubuntu 22.04.4 LTS（x86_64），systemd 249
• PowerDNS Authoritative Server：5.1.4-1pdns.ubuntu22.04（官方 APT 源 jammy-auth-51）
• 数据库后端：gsqlite3（pdns-backend-sqlite3 5.1.4，SQLite3 CLI 3.37.2）
• 配置文件：/etc/powerdns/pdns.conf（819 行注释模板），后端片段目录 /etc/powerdns/pdns.d/
• 参数总量：pdns_server --config=print 输出 1177 行，覆盖 170 个配置参数
• 本机监听：127.0.0.2:53（与既有 DNS 服务共存，见 5.1 节 local-address）

二、前置条件

已按《Ubuntu 22.04 安装 PowerDNS 5.1.4 指南》完成服务端安装，或具备等价环境。本篇所有查看类命令可独立执行，先确认服务在运行：

systemctl is-active pdns && pdns_control rping

实测回显：

active
PONG

若服务未安装，本篇 5.x 节的默认值可通过 pdns_server --config=print 在任何装好包的机器上独立复现（该命令不需要服务在运行）。

三、参数查看与修改方式

3.1 查看参数：三种方式

方式一：查看完整默认配置（无需服务运行）。pdns_server --config=print 按参数名字母序打印全部参数；与当前运行值不同的参数以未注释的激活行呈现，其余以 # 参数名=默认值 注释行呈现：

pdns_server --config=print | grep -E "^(# )?(cache-ttl|local-port|distributor-threads)="

实测回显：

# cache-ttl=20
# local-port=53
# distributor-threads=3

方式二：查看运行中服务的生效配置。pdns_control current-config 输出当前运行配置；加 diff 只显示与编译默认值不同的项（排障时最常用）：

pdns_control current-config diff

实测回显：

# Autogenerated configuration file based on running instance (2026-10-20 16:39:21 +0800)

disable-syslog=
domain-metadata-cache-ttl=60
gsqlite3-database=/var/lib/powerdns/pdns.sqlite3
gsqlite3-dnssec=yes
include-dir=/etc/powerdns/pdns.d
launch=gsqlite3
local-address=127.0.0.2
log-timestamp=no
server-id=ops
write-pid=no

其中 disable-syslog=、log-timestamp=no、write-pid=no 三项来自 systemd 单元的命令行参数（ExecStart 中的 --disable-syslog --log-timestamp=no --write-pid=no），并非 pdns.conf 所设——命令行参数优先级高于配置文件。

方式三：查单个参数注释与取值范围。包内模板 /etc/powerdns/pdns.conf 对每个参数都有两行注释说明（参数名 + 简述，随后是默认值行），例如：

grep -B3 "^# local-address=" /etc/powerdns/pdns.conf

实测回显：

#################################
# local-address Local IP addresses to which we bind
#
# local-address=0.0.0.0, ::

3.2 修改参数与生效规则

三条硬规则（均实测验证）：

1. 编辑配置文件后必须重启服务才生效：sudo systemctl restart pdns。运行时 pdns_control set 只对极少数参数可用，实测对 loglevel、local-port 均拒绝：

pdns_control set loglevel 6

实测回显：

This setting cannot be changed at runtime, or no such setting

2. 同一参数多次出现时最后一行生效。模板中 launch= 有一行空激活值，直接在文件末尾追加 launch=gsqlite3（或用 sed 替换原行）均可，实测两种写法等效——本文部署指南采用 sed 替换原行。

3. 命令行参数 > pdns.conf > 编译默认值。systemd 单元通过 ExecStart 注入的 --guardian=no --daemon=no 等参数始终覆盖配置文件同名项。

配置语法校验（改完先校验再重启，避免服务起不来）：

sudo pdns_server --config=check 2>&1 | tail -1

实测回显（仅有模块加载行、无报错即通过）：

Oct 20 16:39:52 Loading '/usr/lib/x86_64-linux-gnu/pdns/libgsqlite3backend.so'

四、参数总览

5.1.4 共 170 个参数（pdns_server --config=print 实测统计），按用途分布如下：

💡 说明：相对 4.5.x，5.1.4 新增约 46 个参数，重点包括 views（按来源网段提供不同区域视图）、default-catalog-zone（Catalog Zones 默认成员目录）、edns-cookie-secret（DNS Cookie）、proxy-protocol-from（PROXY 协议透传真实客户端地址）、webserver-hash-plaintext-credentials（Web 凭据哈希存储）等。升级版本后建议先用 3.1 节方式二 diff 一遍新旧配置。

五、核心参数分类详解

以下默认值全部取自 5.1.4 实机 pdns_server --config=print 输出，可直接用同命令复核。

5.1 监听与网络参数

实测要点：local-address 绑定 127.0.0.2 后，启动日志出现 UDP server bound to 127.0.0.2:53 / TCP server bound to 127.0.0.2:53（回显见部署篇 7.3 节）。

5.2 后端与数据库参数（gsqlite3）

启动后验证后端连通的实测手段：/var/lib/powerdns/ 下出现 pdns.sqlite3-shm 与 pdns.sqlite3-wal 伴生文件，且 pdns_control rping 返回 PONG。

5.3 日志参数

实测排障路径：journalctl -u pdns -n 50 --no-pager，生产排障建议临时 loglevel=6 + log-dns-queries=yes，定位后改回。

5.4 缓存与性能参数

💡 技术拓展：PowerDNS 的缓存分两层——PacketCache 以「问题+应答」整包为单位（cache-ttl），命中后完全绕过后端；QueryCache 只缓存后端记录查询结果（query-cache-ttl）。同类 DNS 服务器中，BIND9 用 max-cache-size 管理递归缓存，Knot DNS 有独立的 answer cache——三者口径不同，横向对比时注意换算。PowerDNS 权威场景实际采用双缓存分层，理由是区域变更（pdns_control purge）可精确失效。

缓存命中率用 pdns_control show packetcache-hit / show query-cache-hit 实测观察（命令详见 CLI 篇）。

5.5 主从（primary/secondary）与区域传输参数

💡 说明：4.4 起官方把 master/slave 术语更名为 primary/secondary，旧参数 master=、slave=、superslave= 仍作为别名兼容（模板中仍可见），新配置一律用新名。

实测要点：仅做单一权威（本指南默认形态）时保持 primary=no、secondary=no，且务必把 allow-axfr-ips 收紧——AXFR 会吐出全区域记录。

5.6 DNSSEC 参数

实测佐证：pdnsutil zone secure example.com 未显式给算法时，实际生成 CSK (257) algo=13 (ECDSAP256SHA256)，与 default-ksk-algorithm=ecdsa256 一致；dig @127.0.0.2 example.com DNSKEY 能拿到 257 3 13 记录（完整回显见 CLI 篇）。

5.7 Web 监控与 REST API 参数

实测佐证：按部署篇 7.4 节开启后，curl -u admin:q1w2e3r4 http://127.0.0.2:8081/ 返回监控页 HTML，curl -H "X-API-Key: q1w2e3r4" .../api/v1/servers/localhost 返回版本 5.1.4 的 JSON，无密钥访问返回 401。开启 webserver-hash-plaintext-credentials=yes 后，明文口令需改用 pdnsutil hash-password 生成的 scrypt 串。

5.8 安全与运行时参数

六、生产配置模板

模板一：小型内网权威 DNS（2 vCPU / 4GB 内存 / 普通云盘，几十个区域、百 QPS 以内，gsqlite3）

# /etc/powerdns/pdns.conf —— 追加到模板末尾即可，同名参数以最后一行为准
launch=gsqlite3
gsqlite3-database=/var/lib/powerdns/pdns.sqlite3
gsqlite3-dnssec=yes

local-address=192.0.2.53
local-port=53
loglevel=4
log-dns-queries=no
cache-ttl=60
query-cache-ttl=60
negquery-cache-ttl=60

webserver=yes
webserver-address=127.0.0.2
webserver-port=8081
webserver-password=q1w2e3r4
api=yes
api-key=q1w2e3r4
webserver-allow-from=127.0.0.0/8,192.168.146.0/24

version-string=anonymous
allow-axfr-ips=127.0.0.0/8,::1

适用说明：单机权威、无主从。缓存放宽到 60 秒降低 SQLite 读压力；version-string=anonymous 隐藏版本；AXFR 只留本机。改动后 sudo pdns_server --config=check 校验再 systemctl restart pdns，用 pdns_control current-config diff 复核生效值。

模板二：高并发对外权威（8 vCPU / 16GB 内存 / NVMe SSD，数百区域、万级 QPS，gmysql 后端）

launch=gmysql
gmysql-host=127.0.0.1
gmysql-user=pdns
gmysql-password=q1w2e3r4
gmysql-dbname=pdns
gmysql-dnssec=yes

receiver-threads=4
reuseport=yes
distributor-threads=8
cache-ttl=30
query-cache-ttl=30
max-tcp-connections=100
udp-truncation-threshold=1232

primary=yes
allow-axfr-ips=192.0.2.0/24
xfr-max-received-mbytes=100

api=yes
webserver=yes
webserver-address=127.0.0.2
webserver-port=8081
api-key=q1w2e3r4
version-string=powerdns

适用说明：receiver-threads=4 + reuseport=yes 让四个线程各自持有 53 端口套接字分散软中断；SQL 后端换 gmysql 承载高并发写（区域更新/签名）；primary=yes 开放主从时 allow-axfr-ips 必须收窄到从服务器网段。

七、常见问题

Q1：改了 pdns.conf 不生效？

三个原因逐一排查：(1) 未 systemctl restart pdns；(2) 同参数在文件中出现多次，生效的是最后一行，用 grep -n '^launch' /etc/powerdns/pdns.conf 检查是否残留旧行；(3) 被 systemd 单元 ExecStart 注入的命令行参数覆盖（如 --guardian=no），用 pdns_control current-config diff 看真实生效值。

Q2：pdns_control set 报 This setting cannot be changed at runtime？

正常现象。绝大多数参数不支持运行时热更（实测 loglevel、local-port 均拒绝），改配置文件后重启服务是标准做法。

Q3：local-address 改绑后启动报 Unable to bind UDP socket to '...': Address already in use？

目标地址的 53 端口仍被占用，用 ss -ltnp | grep ":53 " 找占用方；换一个空闲地址或停用对方服务。完整排障实录见《Ubuntu 22.04 安装 PowerDNS 5.1.4 指南》第八章。

Q4：gsqlite3 报 attempt to write a readonly database？

WAL 模式要求 pdns 用户对数据库文件及其所在目录均有写权限：chown pdns:pdns /var/lib/powerdns /var/lib/powerdns/pdns.sqlite3 后重启（实录见部署篇 FAQ Q2）。

Q5：如何确认线上到底跑的哪套配置？

pdns_control current-config diff

实测回显见 3.1 节方式二——该输出只含非默认项，是配置漂移核查的第一入口。

八、参考链接

• 官方参数文档（settings 列表）：https://doc.powerdns.com/authoritative/settings.html
• gsqlite3 后端参数：https://doc.powerdns.com/authoritative/backends/generic-sqlite3.html
• 主从与 AXFR 官方指南：https://doc.powerdns.com/authoritative/modes-of-operation.html
• DNSSEC 操作指南：https://doc.powerdns.com/authoritative/dnssec/index.html
• HTTP API/监控页说明：https://doc.powerdns.com/authoritative/http-api/README.html
• 同系列文档：《Ubuntu 22.04 安装 PowerDNS 5.1.4 指南》（安装与排障实录）、《PowerDNS 5.1.4 常用 CLI 命令与工具详解》（pdns_control/pdnsutil 实测）、《PowerDNS 5.1.4 介绍与选型指南》（架构与同类对比）