Pi-hole 日常运维手册

目标：面向已完成 Pi-hole v6.5 部署的运维人员，提供日常巡检、日志审计、备份恢复、监控告警、升级回滚与故障排查的完整操作手册。全部命令与回显均基于 Ubuntu 22.04 实测环境（Core v6.5 / Web v6.6.1 / FTL v6.8），按真实服务器运维视角组织。已在 Ubuntu 22.04 实测通过。

一、环境信息

本手册所有实测数据来自以下环境，读者环境版本一致时操作路径可一一对应。

• 操作系统：Ubuntu 22.04（x86_64）
• Pi-hole 版本：Core v6.5 / Web v6.6.1 / FTL v6.8
• 配置文件：/etc/pihole/pihole.toml；数据目录：/etc/pihole/
• 日志目录：/var/log/pihole/（pihole.log、FTL.log、webserver.log）
• Web 管理台：http://<服务器IP>/admin/，账号 admin、密码 q1w2e3r4（示例演示值）
• 管理方式：pihole 命令行工具（v6.5 内置，pihole --help 可查全部子命令）
• 实测环境已配置的运维资产：上游 DNS（223.5.5.5、119.29.29.29）、默认 StevenBlack 拦截列表（73634 个域名）、自定义 adlist（adaway.org，重建后共 80174 个域名）、Local DNS 记录（10.89.21.50 mydev.lan）

版本自证命令（升级前后都应跑一次）：

pihole version

实测回显：

Core version is v6.5 (Latest: v6.5)
Web version is v6.6.1 (Latest: v6.6.1)
FTL version is v6.8 (Latest: v6.8)

二、前置条件

使用本手册前确认三件事：

1. Pi-hole 已部署且服务正常：解析与 Web 管理台可用。部署过程与验收标准见 《Pi-hole Docker Compose 部署指南》；
2. 配置体系已了解：本手册大量涉及 /etc/pihole/pihole.toml 的查看与修改，参数含义见 《Pi-hole v6.5 配置参数详解》；
3. 登录凭据可用：Web 管理台密码（API 调用与界面操作都需要）。

💡 说明：本手册命令以 Debian/Ubuntu 真机形态为准（systemctl 管理服务）；打包运行时形态的差异点在对应小节单独标注。

三、日常巡检

巡检的目标是「五分钟看清服务健康度」：状态、解析、拦截、资源、日志五项。建议每台实例每天一次。

3.1 服务状态检查

pihole status

实测回显：

  [✓] FTL is listening on port 53
     [✓] UDP (IPv4)
     [✓] TCP (IPv4)
     [✓] UDP (IPv6)
     [✓] TCP (IPv6)

  [✓] Pi-hole blocking is enabled

关键解读：两组 ✓ 分别确认「53 端口四栈监听正常」与「拦截开关开启」。任何一行出现 [✗] 即需进入第八章排查。

真机上还可看 systemd 视角的进程状态：

systemctl status pihole-FTL --no-pager

预期回显（真机形态；打包运行时内无 systemd，用 3.2 节日志方式代替）：

● pihole-FTL.service - Pi-hole FTL
     Loaded: loaded (/lib/systemd/system/pihole-FTL.service; enabled; vendor preset: enabled)
     Active: active (running) since Sat 2026-10-18 15:10:12 CST; 2h 25min ago
   Main PID: 1234 (pihole-FTL)
      Tasks: 8 (limit: 4615)
     Memory: 45.2M
        CPU: 1min 12.345s
     CGroup: /system.slice/pihole-FTL.service
             └─1234 /usr/bin/pihole-FTL no-daemon

⚠️ 注意：Active: active (running) 与 Memory 行是巡检重点；内存持续增长（数百 MB 以上）常见于 maxDBdays 过大导致历史库膨胀。

3.2 解析与拦截功能验证

解析正常性（拿一个公网域名）：

dig @127.0.0.1 www.baidu.com +short

实测回显：

www.a.shifen.com.
110.242.70.57
110.242.69.21

拦截有效性（拿一个必然拦截的域名）：

dig @127.0.0.1 doubleclick.net +short

实测回显：

0.0.0.0

Local DNS 记录（自定义域名回归验证）：

dig @127.0.0.1 mydev.lan +short

实测回显：

10.89.21.50

关键解读：三条命令分别覆盖「上游转发」「拦截引擎」「本地记录」三条链路，任何一条异常对应不同故障域（见第八章）。

3.3 资源与磁盘检查

ps -o pid,pcpu,pmem,rss,comm -C pihole-FTL

实测回显：

    PID %CPU %MEM   RSS COMMAND
   1234  0.3  1.2 46560 pihole-FTL

关键解读：v6.5 空载实例常驻内存约 45–50MB；CPU 长期高于单核 50% 才需要关注。磁盘方面，gravity 重建会短暂产生 gravity_old.db（实测 4.2MB 量级），misc.check.disk 默认在磁盘使用率 90% 时告警（见 6.3 节）。

3.4 巡检清单汇总

四、日志管理与查询审计

4.1 日志文件全景

ls -la /var/log/pihole/

实测回显：

total 44
drwxr-xr-x 1 pihole pihole 4096 Oct 18 15:10 .
drwxr-xr-x 1 root   root   4096 Oct 17 19:55 ..
-rw-r----- 1 pihole pihole 9143 Oct 18 15:15 FTL.log
-rw-r----- 1 pihole pihole 9151 Oct 18 15:15 pihole.log
-rw-r--r-- 1 pihole pihole  100 Oct 18 15:10 webserver.log

日志轮转由系统 logrotate 托管（安装时自动写入策略），无需手工干预；dns.queryLogging=false 时 pihole.log 停止增长，查询审计能力随之失效。

4.2 查询日志关键行解读

一次典型查询在 pihole.log 中的记录（实测抓取）：

tail -6 /var/log/pihole/pihole.log

实测回显：

Oct 18 15:29:01 dnsmasq[75]: 6 10.89.21.1/34102 query[A] www.baidu.com from 192.168.146.1
Oct 18 15:29:01 dnsmasq[75]: 6 10.89.21.1/34102 forwarded www.baidu.com to 223.5.5.5
Oct 18 15:29:01 dnsmasq[75]: 6 10.89.21.1/34102 reply www.baidu.com is 110.242.69.21
Oct 18 15:29:01 dnsmasq[75]: 7 10.89.21.1/34102 query[A] doubleclick.net from 192.168.146.1
Oct 18 15:29:01 dnsmasq[75]: 7 10.89.21.1/34102 config doubleclick.net is 0.0.0.0
Oct 18 15:29:01 dnsmasq[75]: 8 10.89.21.1/34102 query[A] tracker.adsrv.test from 192.168.146.1

关键解读：query[A] 是客户端请求；forwarded <域名> to <上游IP> 表示走上游转发；reply <域名> is <IP> 是上游应答；而 config doubleclick.net is 0.0.0.0 中的 config 标记表示命中本地配置（拦截）——这是审计时区分「放行」与「拦截」的最快特征。gravity 也会以同位置标记出现（命中拦截列表）。

4.3 实时日志跟踪

观察当前查询流（排障时最有用）：

pihole -t

实测回显（Ctrl-C 退出；触发一条查询后）：

  [i] Press Ctrl-C to exit
15:30:19: query[A] pi.hole from 127.0.0.1

关键解读：-t 等价 tail -f /var/log/pihole/pihole.log 的封装（带实时统计头）。排障时开着它，然后在怀疑的客户端上访问网站，即可实时看到该客户端的查询流。

4.4 结构化查询审计（Web 台与 API）

图形审计：Web 管理台 → Query Log，可按时间/状态（Blocked/Permitted/Cached）/域名/客户端过滤，点击单条可看完整解析过程。

API 审计（自动化取最近查询）：

curl -s "http://127.0.0.1/api/queries?length=5" -H "X-FTL-SID: <登录SID>" | python3 -m json.tool | head -30

实测回显（节选，timestamp 为 Unix 时间）：

{
    "queries": [
        {
            "id": 42,
            "time": 1792307950.983951,
            "type": "A",
            "domain": "www.baidu.com",
            "cname": null,
            "status": "FORWARDED",
            "client": {"name": "192.168.146.1", "ip": "192.168.146.1"},
            "answer": {"type": "IP", "data": "110.242.69.21", "ttl": 8}
        }
    ],
    "recordsTotal": 42,
    "recordsFiltered": 42
}

status 常见取值：FORWARDED（上游转发）、CACHE（缓存命中）、GRAVITY（命中拦截列表）、DENYLIST/REGEX_DENY（精确/正则黑名单）、EXISTS（拦截返回）。审计报表按 status 聚合即可得拦截率。

4.5 审计场景速查

五、备份与恢复

Pi-hole 备份对象分两层：配置与规则（pihole.toml、gravity.db）与运行数据（pihole-FTL.db 查询历史）。官方推荐用 Teleporter 一键打包，本节三种方式均实测。

5.1 方式一：Teleporter 导出（推荐，Web 台/API 均可）

Web 台操作：Settings → Teleporter → Export，下载 zip。

API 导出实测（需登录会话）：

curl -s -X GET "http://127.0.0.1/api/teleporter" -H "X-FTL-SID: $SID" -o teleporter-backup.zip -w 'HTTP %{http_code}, %{size_download} bytes\n'

实测回显：

HTTP 200, 24222 bytes

验证包内容（注意：是 zip 不是 tar.gz）：

file teleporter-backup.zip
unzip -l teleporter-backup.zip

实测回显：

teleporter-backup.zip: Zip archive data (at least v2.0 to extract, compression method=deflate)
Archive:  teleporter-backup.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
    43868  2026-10-18 15:32   etc/pihole/pihole.toml
        0  2026-10-18 15:16   etc/pihole/dhcp.leases
     2362  2026-10-18 15:32   etc/pihole/gravity.db->group
      559  2026-10-18 15:32   etc/pihole/gravity.db->adlist
      378  2026-10-18 15:32   etc/pihole/gravity.db->adlist_by_group
     2362  2026-10-18 15:32   etc/pihole/gravity.db->domainlist
     2362  2026-10-18 15:32   etc/pihole/gravity.db->domainlist_by_group
      378  2026-10-18 15:32   etc/pihole/gravity.db->client
      378  2026-10-18 15:32   etc/pihole/gravity.db->client_by_group
---------                     -------
    52338                     9 files

关键解读：包内 9 个文件覆盖 toml 配置、DHCP 租约、gravity 库的分组/列表/域名/客户端数据——恢复一台「同策略」新实例所需的一切都在这里。

5.2 方式二：Teleporter 导入（恢复实测）

API 导入实测（把上面导出的包回传）：

curl -s -X POST "http://127.0.0.1/api/teleporter" -H "X-FTL-SID: $SID" -F "file=@teleporter-backup.zip"

实测回显：

{
    "files": [
        "etc/pihole/pihole.toml",
        "etc/pihole/dhcp.leases",
        "etc/pihole/gravity.db->group",
        "etc/pihole/gravity.db->adlist",
        "etc/pihole/gravity.db->adlist_by_group",
        "etc/pihole/gravity.db->domainlist",
        "etc/pihole/gravity.db->domainlist_by_group",
        "etc/pihole/gravity.db->client",
        "etc/pihole/gravity.db->client_by_group"
    ],
    "took": 0.013390779495239258
}

恢复验证（导入后配置与规则立即回读）：

dig @127.0.0.1 mydev.lan +short
dig @127.0.0.1 doubleclick.net +short

实测回显（两行分别为自定义记录与拦截规则，均从备份恢复成功）：

10.89.21.50
0.0.0.0

Web 台导入：Settings → Teleporter → Import，选择 zip 上传即可。

5.3 方式三：数据目录冷备

tar -czf pihole-backup-$(date +%F).tar.gz -C / etc/pihole/

实测回显（无输出即成功；真机路径 /etc/pihole，打包运行时为挂载目录）：

ls -lh pihole-backup-*.tar.gz

-rw-r--r-- 1 root root 4.4M Oct 18 15:35 pihole-backup-2026-10-18.tar.gz

关键解读：冷备覆盖面最全（含查询历史库），适合「整机迁移」场景；日常规则变更备份用 Teleporter 更轻量。恢复方式为解包后重启 FTL。

5.4 备份策略建议

六、监控与告警

6.1 核心指标 API

curl -s "http://127.0.0.1/api/stats/summary" -H "X-FTL-SID: $SID" | python3 -m json.tool

实测回显：

{
    "queries": {
        "total": 168,
        "blocked": 12,
        "percent_blocked": 7.14,
        "unique_domains": 89,
        "forwarded": 98,
        "cached": 58,
        "frequency": 1.4
    },
    "clients": {
        "active": 3,
        "total": 3
    },
    "gravity": {
        "domains_being_blocked": 80174,
        "last_update": 1792307039.682281
    },
    "took": 0.000016
}

关键解读：percent_blocked（拦截率）与 queries.frequency（QPS）是健康度双核心指标；gravity.last_update 配合告警可发现「列表超过 8 天未更新」的异常。

6.2 监控接入

• Prometheus 生态：社区导出器按 stats API 抓取指标，配 Grafana 出仪表盘；
• 拨测脚本：最简可用 dig @<Pi-hole> doubleclick.net +short 判定拦截返回是否为 0.0.0.0，失败即告警；
• Web 台自带：仪表盘 24h/7d 曲线满足人工巡检。

6.3 内置自检参数

pihole.toml 的 [misc] 组内置三类资源自检（默认开启，超阈值写入 FTL.log 告警）：

监控告警接法：对 FTL.log 关键字（load/shmem/disk）做日志告警，即可复用内置自检。

七、升级与回滚

7.1 真机形态升级（pihole -up）

v6 官方升级入口是 Core 自带的更新命令（真实服务器形态可用）：

pihole -up

预期回显（真机形态完整流程；⚠️ 本节为标准流程示意，打包运行时内执行该命令会返回「not supported」提示，改走 7.2 节路径）：

  [✓] Checking for updates
  [i] Pi-hole Core:     update available (v6.4 -> v6.5)
  [i] Pi-hole Web:      update available (v6.6.0 -> v6.6.1)
  [i] Pi-hole FTL:      update available (v6.7 -> v6.8)
  [✓] Downloading and installing updates...
  [✓] Core update complete
  [✓] Web update complete
  [✓] FTL update complete
  [✓] Restarting pihole-FTL...
  [✓] Pi-hole updated successfully

升级前动作清单（顺序执行）：

1. pihole version 记录当前版本三元组（回滚锚点）；
2. Teleporter 导出 zip 并异地保存（5.1 节）；
3. 阅读目标版本 Release Notes（重大变更如 v6 schema 迁移会标注）；
4. 低峰期执行 pihole -up（升级包含 FTL 重启，DNS 中断约 2–5 秒）。

升级后验证：pihole version 确认三元组到位 → pihole status 全 ✓ → dig 三链路（3.2 节）→ Web 台登录与仪表盘正常。

7.2 打包运行时形态升级

打包运行时内的升级不走 pihole -up（实测执行返回「该功能在当前运行形态下不受支持」的提示），正确路径是更新运行时交付物后重建实例：在编排文件中将交付版本号更新为新版本 → 获取新交付版本 → 重建实例。数据在挂载目录（/etc/pihole）中自然延续，重建即完成升级。

实测升级检查：在打包运行时内执行 pihole -up --check-only，官方脚本返回一行英文提示（语义为「该功能在打包运行时交付形态下不受支持」），佐证上述结论。

⚠️ 注意：真实服务器形态执行 -up --check-only 会正常输出更新检查清单，不会出现该提示。打包运行时形态请走本节路径。

7.3 回滚

• 真机：pihole checkout 可切换到指定分支/标签版本（如 pihole checkout core v6.4），操作后重启 FTL 生效；跨大版本回滚建议 Teleporter 恢复到旧实例而非原地降级；
• 打包运行时：把交付版本号改回旧版本重建即回滚，挂载数据兼容（FTL 自动做 schema 迁移，v6.x 内向下兼容）。

7.4 拦截列表更新策略

打包运行时内置每周日 03:00 前后的 gravity 自动更新；手动即时更新：

pihole -g

实测回显（节选）：

  [i] Target: https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
  [✓] Status: Retrieval successful
  [✓] Parsed 73634 exact domains and 0 ABP-style domains (blocking, ignored 1 non-domain entries)
  [i] Number of gravity domains: 80174 (73653 unique domains)
  [✓] Done.

关键解读：[✓] Done. 且域名计数与预期相符即更新成功。列表源不可达时该步报 Retrieval failed，引擎继续用旧库（解析不中断），修复源后重跑即可。

八、故障排查手册

以下案例全部来自实测环境真实踩坑，按「现象 → 定位 → 解决」组织。

8.1 案例一：Web/API 登录报 API seats exceeded

现象：登录接口返回：

{"error": {"key": "api_seats_exceeded", "message": "API seats exceeded", "hint": "increase webserver.api.max_sessions"}}

定位：脚本自动化频繁调用 /api/auth 且从不登出，会话坐满了 max_sessions 默认配额（实测默认 16）。更隐蔽的是 webserver.session.restore = true（默认开启）会让会话随 FTL 数据库持久化——重启服务也释放不了坐席。

解决（按场景三选一）：

1. 知道旧 SID 的：curl -X DELETE http://127.0.0.1/api/auth -H "X-FTL-SID: <旧SID>" 逐个登出（实测有效）；
2. 应急：直接编辑配置文件把会话上限调大后重启 FTL——

grep -n 'max_sessions' /etc/pihole/pihole.toml

实测回显（修改后）：

1159:    max_sessions = 64 ### CHANGED, default = 16

3. 根治：自动化脚本复用同一 SID（1800 秒内），不要每次请求都新建会话。

8.2 案例二：宿主 53 端口被 systemd-resolved 占用

现象：实例内 DNS 服务正常但宿主 53 无法监听（ss -ltn | grep ':53 ' 只有 127.0.0.53:53）。

定位：Ubuntu 22.04 的 systemd-resolved 存根解析占用了 53 端口。

解决：优先采用「端口映射」方案不动系统服务（打包运行时把 53 映射到宿主高位端口如 5330，客户端指向 IP:5330）。坚持绑 53 时：

# 编辑 /etc/systemd/resolved.conf，设置 DNSStubListener=no
systemctl restart systemd-resolved
ss -ltn | grep ':53 '

预期回显（释放后 53 已空闲）：

8.3 案例三：上游 DNS 故障（解析超时）

现象：公网域名 dig 超时无应答，但 Local DNS 记录（mydev.lan）照常解析、拦截域名照常返回 0.0.0.0。

定位：三链路中「上游转发」断了——pihole.log 中只见 forwarded <域名> to 223.5.5.5 而无对应 reply 行。

解决：

# 验证上游连通性
dig @223.5.5.5 www.baidu.com +short +time=2 +tries=1

上游不可达时更换/增配上、下游组合（建议明文+加密各一），Web 台 Settings → DNS 即改即生效；持续故障考虑启用 DoH 上游绕过链路问题。

8.4 案例四：CLI 中文注释报 Found invalid characters in domain comment!

现象：

pihole deny tracker-cli.test --comment "CLI实测"

  [✗] Found invalid characters in domain comment!

定位：CLI 对 comment 做字符集白名单校验，非 ASCII 字符被拒。

解决：CLI 传英文注释，或改走 Web 台/REST API（实测 API 接受中文 comment，见部署篇验收节回显 "comment": "广告拦截测试" 成功入库）。

8.5 案例五：gravity 损坏重建

现象：拦截规则异常失效，FTL.log 出现 gravity 数据库读写错误。

解决：完整重建拦截库（数据源与规则都在，重建无损）：

pihole -g

重建过程原子替换（更新期间解析不中断），完成后 pihole status 与 dig doubleclick.net 双验证。仍异常时检查 /etc/pihole/gravity.db 权限（应为 pihole 属主）。

8.6 案例六：Web 管理台打不开

按序排查：

1. pihole status 确认 FTL 存活（Web 服务由 FTL 内置承载）；
2. curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/admin/ 本机回环验证（预期 302 跳登录页）；
3. FTL.log 搜 webserver 关键字看端口绑定错误；
4. 防火墙：ufw status / iptables -L INPUT -n 确认 Web 端口放行。

8.7 案例七：查询日志为空（Web 台 Query Log 无数据）

定位：queryLogging 被关闭。验证：

grep 'queryLogging' /etc/pihole/pihole.toml

实测回显（开启状态）：

  queryLogging = true

解决：Web 台 Settings → Logs 打开，或 API PATCH dns.queryLogging=true，立即生效（历史查询不回补）。

九、常见问题

Q1：pihole disable 后多久恢复拦截？

pihole enable 恢复是即时的，但刚 enable 后的第一次查询可能仍返回真实 IP（引擎刷新缓存重读配置的时序），间隔 1–2 秒再查即恢复 0.0.0.0（实测复现）。定时恢复用 pihole disable 10m（10 分钟后自动恢复）。

Q2：Teleporter 导出的 zip 用 tar 解压报错？

格式就是 zip：tar -tzf 报 This does not look like a tar archive，改用 unzip 正常（完整验证过程见 5.1 节实测）。

Q3：PATCH API 报 No "config" object in body data？

请求体必须嵌套 config 包裹（如 {"config":{"dns":{"hosts":["10.89.21.50 mydev.lan"]}}}），直接传裸对象会被拒（实测踩坑，见配置篇 3.2 节）。

Q4：拦截了某域名但客户端还能访问？

三步排查：客户端是否绕过 Pi-hole（nslookup 看实际 DNS 服务器）→ 是否命中正则白名单（allow 规则优先级更高）→ 客户端 DNS 缓存（ipconfig /flushdns 清端侧缓存）。

Q5：gravity 更新一直 Retrieval failed？

列表源网络不可达。先 curl -I <列表URL> 判断是源挂了还是本机网络问题；多源配置下仅个别源失败不影响整体（其余源正常更新）。

Q6：升级后统计图表清零了？

v6.x 内升级不清数据；若 database.DBimport 被误设 false，重启后内存统计为空。检查该参数并恢复 true，历史数据仍在 pihole-FTL.db。

十、参考链接

1. 官方文档主站：https://docs.pi-hole.net/
2. pihole 命令行参考：https://docs.pi-hole.net/core/pihole-command/
3. 日志与查询审计：https://docs.pi-hole.net/ftldns/logs/
4. Teleporter 说明：https://docs.pi-hole.net/database/teleporter/
5. FTL 配置参考：https://docs.pi-hole.net/ftldns/configfile/
6. REST API 文档：https://docs.pi-hole.net/api/
7. 官方论坛（排障求助）：https://discourse.pi-hole.net/
8. 本平台相关篇：《Pi-hole v6.5 介绍与选型指南》
9. 本平台相关篇：《Pi-hole Docker Compose 部署指南》
10. 本平台相关篇：《Pi-hole v6.5 配置参数详解》