Back to Details

pihole-dns-troubleshoot

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Troubleshoot DNS Resolution Skill

DNS解析故障排查技能

Systematic diagnosis and resolution of DNS resolution issues in the Pi-hole DNS infrastructure.
对Pi-hole DNS基础设施中的DNS解析问题进行系统性诊断与修复。

Quick Start

快速开始

Run quick diagnostic to identify DNS issues:
bash
undefined
运行快速诊断以识别DNS问题：
bash
undefined

Check DNS resolution

检查DNS解析

dig @192.168.68.136 pihole.temet.ai
dig @192.168.68.136 pihole.temet.ai

Check Pi-hole is running

检查Pi-hole是否运行

docker ps | grep pihole
docker ps | grep pihole

Check DNS records configured

检查已配置的DNS记录

docker exec pihole nslookup pihole.temet.ai 127.0.0.1
undefined
docker exec pihole nslookup pihole.temet.ai 127.0.0.1
undefined

Table of Contents

目录

  1. When to Use This Skill
  2. What This Skill Does
  3. Instructions
    • 3.1 Verify Pi-hole is Running
    • 3.2 Check Pi-hole DNS Configuration
    • 3.3 Test DNS Resolution from Pi-hole
    • 3.4 Verify Router DNS Settings
    • 3.5 Test DNS Resolution from Client
    • 3.6 Check FTLCONF DNS Records
    • 3.7 Apply Fix
  4. Supporting Files
  5. Expected Outcomes
  6. Requirements
  7. Red Flags to Avoid
  1. 何时使用此技能
  2. 此技能的功能
  3. 操作步骤
    • 3.1 验证Pi-hole是否运行
    • 3.2 检查Pi-hole DNS配置
    • 3.3 从Pi-hole测试DNS解析
    • 3.4 验证路由器DNS设置
    • 3.5 从客户端测试DNS解析
    • 3.6 检查FTLCONF DNS记录
    • 3.7 应用修复方案
  4. 支持文件
  5. 预期结果
  6. 要求
  7. 需避免的风险

When to Use This Skill

何时使用此技能

Explicit Triggers:
  • "DNS not working"
  • "Can't access pihole.temet.ai"
  • "Domain not resolving"
  • "Fix DNS resolution"
  • "Pi-hole DNS not working"
Implicit Triggers:
  • Services work via IP but not domain name
  • Browser shows "DNS_PROBE_FINISHED_NXDOMAIN"
  • Can access services remotely but not locally
  • Ping fails for local domains
Debugging Triggers:
  • "Why isn't my domain resolving?"
  • "Why can't I access local services?"
  • "Is Pi-hole working?"
明确触发场景：
  • "DNS无法工作"
  • "无法访问pihole.temet.ai"
  • "域名无法解析"
  • "修复DNS解析"
  • "Pi-hole DNS无法工作"
隐含触发场景：
  • 通过IP可访问服务但域名不行
  • 浏览器显示"DNS_PROBE_FINISHED_NXDOMAIN"
  • 可远程访问服务但本地无法访问
  • 本地域名ping失败
调试触发场景：
  • "为什么我的域名无法解析？"
  • "为什么我无法访问本地服务？"
  • "Pi-hole是否正常工作？"

What This Skill Does

此技能的功能

  1. Verifies Pi-hole - Checks Pi-hole container is running
  2. Checks DNS Config - Verifies FTLCONF DNS records in docker-compose.yml
  3. Tests Pi-hole DNS - Queries Pi-hole directly for DNS records
  4. Checks Router - Verifies router is configured to use Pi-hole
  5. Tests Client DNS - Verifies client devices can resolve domains
  6. Identifies Issue - Determines root cause of DNS failure
  7. Provides Fix - Gives specific commands to resolve the issue
  1. 验证Pi-hole状态 - 检查Pi-hole容器是否运行
  2. 检查DNS配置 - 验证docker-compose.yml中的FTLCONF DNS记录
  3. 测试Pi-hole DNS - 直接向Pi-hole查询DNS记录
  4. 检查路由器设置 - 验证路由器是否配置为使用Pi-hole
  5. 测试客户端DNS - 验证客户端设备能否解析域名
  6. 定位问题根源 - 确定DNS解析失败的根本原因
  7. 提供修复方案 - 给出解决问题的具体命令

Instructions

操作步骤

3.1 Verify Pi-hole is Running

3.1 验证Pi-hole是否运行

bash
docker ps | grep pihole
Expected: Container status "Up" (not "Restarting" or "Exited")
If not running:
bash
cd /home/dawiddutoit/projects/network && \
docker compose up -d pihole && \
docker logs pihole --tail 50
bash
docker ps | grep pihole
预期结果：容器状态为"Up"（非"Restarting"或"Exited"）
如果未运行：
bash
cd /home/dawiddutoit/projects/network && \
docker compose up -d pihole && \
docker logs pihole --tail 50

3.2 Check Pi-hole DNS Configuration

3.2 检查Pi-hole DNS配置

Verify FTLCONF_dns_hosts environment variable is set:
bash
docker exec pihole env | grep FTLCONF_dns_hosts
Expected output should include:
FTLCONF_dns_hosts=192.168.68.136 pihole.temet.ai
192.168.68.136 ha.temet.ai
192.168.68.136 jaeger.temet.ai
...
If missing or incorrect: Edit docker-compose.yml to add/update FTLCONF_dns_hosts environment variable.
验证FTLCONF_dns_hosts环境变量是否已设置：
bash
docker exec pihole env | grep FTLCONF_dns_hosts
预期输出应包含：
FTLCONF_dns_hosts=192.168.68.136 pihole.temet.ai
192.168.68.136 ha.temet.ai
192.168.68.136 jaeger.temet.ai
...
如果缺失或错误： 编辑docker-compose.yml以添加/更新FTLCONF_dns_hosts环境变量。

3.3 Test DNS Resolution from Pi-hole

3.3 从Pi-hole测试DNS解析

Test that Pi-hole itself can resolve the domain:
bash
undefined
测试Pi-hole自身能否解析域名：
bash
undefined

Test single domain

测试单个域名

docker exec pihole nslookup pihole.temet.ai 127.0.0.1
docker exec pihole nslookup pihole.temet.ai 127.0.0.1

Test all configured domains

测试所有已配置域名

for domain in pihole ha jaeger langfuse sprinkler code webhook; do echo "=== Testing $domain.temet.ai ===" docker exec pihole nslookup $domain.temet.ai 127.0.0.1 echo done

Expected: Shows "Address: 192.168.68.136" for each domain

**If "NXDOMAIN" or "can't find":**
- DNS records not configured in FTLCONF_dns_hosts
- Pi-hole FTL hasn't loaded the configuration

Fix:
```bash
for domain in pihole ha jaeger langfuse sprinkler code webhook; do echo "=== 测试 $domain.temet.ai ===" docker exec pihole nslookup $domain.temet.ai 127.0.0.1 echo done

预期结果：每个域名均显示"Address: 192.168.68.136"

**如果出现"NXDOMAIN"或"无法找到"：**
- FTLCONF_dns_hosts中未配置DNS记录
- Pi-hole FTL未加载配置

修复方案：
```bash

Reload Pi-hole DNS

重新加载Pi-hole DNS

docker exec pihole pihole reloaddns
docker exec pihole pihole reloaddns

Or restart Pi-hole

或重启Pi-hole

docker compose -f /home/dawiddutoit/projects/network/docker-compose.yml restart pihole
undefined
docker compose -f /home/dawiddutoit/projects/network/docker-compose.yml restart pihole
undefined

3.4 Verify Router DNS Settings

3.4 验证路由器DNS设置

Check router is configured to use Pi-hole as DNS server:
Router should point to: 192.168.68.136 (Pi-hole IP)
How to verify:
  1. Log into router admin interface
  2. Check DHCP settings
  3. Verify DNS server is set to 192.168.68.136
Common router interfaces:
  • Eero: App → Settings → Network Settings → DNS
  • Unifi: Network → Settings → Networks → LAN → DHCP Name Server
  • Generic: Usually under LAN/DHCP settings
检查路由器是否配置为使用Pi-hole作为DNS服务器：
路由器应指向： 192.168.68.136（Pi-hole的IP地址）
验证方法：
  1. 登录路由器管理界面
  2. 检查DHCP设置
  3. 验证DNS服务器是否设置为192.168.68.136
常见路由器界面：
  • Eero：应用 → 设置 → 网络设置 → DNS
  • Unifi：网络 → 设置 → 网络 → LAN → DHCP名称服务器
  • 通用型：通常在LAN/DHCP设置下

3.5 Test DNS Resolution from Client

3.5 从客户端测试DNS解析

From your computer or device:
bash
undefined
在你的电脑或设备上执行：
bash
undefined

Check what DNS server you're using

检查当前使用的DNS服务器

scutil --dns | grep "nameserver[0]"
scutil --dns | grep "nameserver[0]"

Test resolution using system DNS

使用系统DNS测试解析

dig pihole.temet.ai
dig pihole.temet.ai

Test resolution using Pi-hole directly

直接使用Pi-hole测试解析

dig @192.168.68.136 pihole.temet.ai

**Expected:**
- System DNS should show 192.168.68.136
- Both dig commands should return 192.168.68.136 as answer

**If using wrong DNS server:**
- Client may have cached old DNS settings
- Router may not have updated DHCP lease
- Client may have manual DNS override

Fix:
```bash
dig @192.168.68.136 pihole.temet.ai

**预期结果：**
- 系统DNS应显示192.168.68.136
- 两个dig命令均应返回192.168.68.136作为结果

**如果使用错误的DNS服务器：**
- 客户端可能缓存了旧的DNS设置
- 路由器可能未更新DHCP租约
- 客户端可能手动设置了DNS

修复方案：
```bash

Flush DNS cache (macOS)

刷新DNS缓存（macOS）

sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder
sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder

Renew DHCP lease (macOS)

重新获取DHCP租约（macOS）

sudo ipconfig set en0 DHCP
sudo ipconfig set en0 DHCP

Linux

Linux

sudo systemd-resolve --flush-caches
undefined
sudo systemd-resolve --flush-caches
undefined

3.6 Check FTLCONF DNS Records

3.6 检查FTLCONF DNS记录

Verify DNS records are configured in docker-compose.yml:
bash
grep -A20 "FTLCONF_dns_hosts" /home/dawiddutoit/projects/network/docker-compose.yml
Expected format:
yaml
FTLCONF_dns_hosts: |
  192.168.68.136 pihole.temet.ai
  192.168.68.136 ha.temet.ai
  192.168.68.136 jaeger.temet.ai
  192.168.68.136 langfuse.temet.ai
  192.168.68.136 sprinkler.temet.ai
  192.168.68.136 code.temet.ai
  192.168.68.136 webhook.temet.ai
If missing domains: Add them to FTLCONF_dns_hosts and restart Pi-hole.
验证docker-compose.yml中是否配置了DNS记录：
bash
grep -A20 "FTLCONF_dns_hosts" /home/dawiddutoit/projects/network/docker-compose.yml
预期格式：
yaml
FTLCONF_dns_hosts: |
  192.168.68.136 pihole.temet.ai
  192.168.68.136 ha.temet.ai
  192.168.68.136 jaeger.temet.ai
  192.168.68.136 langfuse.temet.ai
  192.168.68.136 sprinkler.temet.ai
  192.168.68.136 code.temet.ai
  192.168.68.136 webhook.temet.ai
如果缺失域名： 将其添加到FTLCONF_dns_hosts并重启Pi-hole。

3.7 Apply Fix

3.7 应用修复方案

Fix A: Pi-hole Not Running
bash
cd /home/dawiddutoit/projects/network && \
docker compose up -d pihole && \
docker logs pihole --tail 50
Fix B: DNS Records Not Configured
  1. Edit docker-compose.yml:
bash
nano /home/dawiddutoit/projects/network/docker-compose.yml
  1. Add missing domains to FTLCONF_dns_hosts:
yaml
FTLCONF_dns_hosts: |
  192.168.68.136 newservice.temet.ai
  1. Restart Pi-hole:
bash
docker compose -f /home/dawiddutoit/projects/network/docker-compose.yml up -d pihole
Fix C: Client Using Wrong DNS
  1. Check router DHCP settings point to 192.168.68.136
  2. Renew client DHCP lease
  3. Flush client DNS cache
Fix D: Pi-hole DNS Not Reloaded
bash
undefined
修复方案A：Pi-hole未运行
bash
cd /home/dawiddutoit/projects/network && \
docker compose up -d pihole && \
docker logs pihole --tail 50
修复方案B：DNS记录未配置
  1. 编辑docker-compose.yml：
bash
nano /home/dawiddutoit/projects/network/docker-compose.yml
  1. 将缺失的域名添加到FTLCONF_dns_hosts：
yaml
FTLCONF_dns_hosts: |
  192.168.68.136 newservice.temet.ai
  1. 重启Pi-hole：
bash
docker compose -f /home/dawiddutoit/projects/network/docker-compose.yml up -d pihole
修复方案C：客户端使用错误的DNS
  1. 检查路由器DHCP设置是否指向192.168.68.136
  2. 重新获取客户端DHCP租约
  3. 刷新客户端DNS缓存
修复方案D：Pi-hole DNS未重新加载
bash
undefined

Reload DNS without restart

无需重启，仅重新加载DNS

docker exec pihole pihole reloaddns
docker exec pihole pihole reloaddns

Or full restart

或完全重启

docker compose -f /home/dawiddutoit/projects/network/docker-compose.yml restart pihole
undefined
docker compose -f /home/dawiddutoit/projects/network/docker-compose.yml restart pihole
undefined

Supporting Files

支持文件

FilePurpose
references/reference.md
Complete DNS configuration reference, Pi-hole v6 FTL details
examples/examples.md
Example DNS configurations, common scenarios
文件用途
references/reference.md
完整的DNS配置参考文档，包含Pi-hole v6 FTL详细信息
examples/examples.md
DNS配置示例，常见场景说明

Expected Outcomes

预期结果

Success:
  • Pi-hole container running and healthy
  • DNS queries to Pi-hole return correct IP addresses
  • Client devices resolve domains correctly
  • All configured domains accessible via domain name
Partial Success:
  • Pi-hole resolves correctly but clients still using old DNS
  • Records configured but not yet propagated to clients
Failure Indicators:
  • Pi-hole container not running
  • FTLCONF_dns_hosts missing or incorrect
  • Router not configured to use Pi-hole
  • DNS resolution returns NXDOMAIN
成功：
  • Pi-hole容器运行正常且状态健康
  • 向Pi-hole发起的DNS查询返回正确的IP地址
  • 客户端设备能够正确解析域名
  • 所有已配置的域名均可通过域名访问
部分成功：
  • Pi-hole解析正常，但客户端仍使用旧的DNS设置
  • 记录已配置，但尚未同步到客户端
失败标识：
  • Pi-hole容器未运行
  • FTLCONF_dns_hosts缺失或配置错误
  • 路由器未配置为使用Pi-hole
  • DNS解析返回NXDOMAIN

Requirements

要求

  • Docker running with Pi-hole container
  • Pi-hole v6+ using FTL DNS server
  • Network access to Pi-hole (192.168.68.136)
  • Router admin access to configure DHCP/DNS
  • 运行中的Docker环境及Pi-hole容器
  • 使用FTLCONF DNS服务器的Pi-hole v6+版本
  • 能够访问Pi-hole（192.168.68.136）的网络权限
  • 路由器管理权限，用于配置DHCP/DNS

Red Flags to Avoid

需避免的风险

  • Do not use dnsmasq configuration files (Pi-hole v6 uses FTL with FTLCONF variables)
  • Do not add DNS records via Pi-hole web UI (use FTLCONF_dns_hosts instead)
  • Do not forget to restart Pi-hole after changing FTLCONF_dns_hosts
  • Do not configure DNS manually on clients (use router DHCP instead)
  • Do not skip flushing DNS cache on clients after DNS changes
  • Do not use -uall flag with Pi-hole DNS queries (causes memory issues)
  • 不要使用dnsmasq配置文件（Pi-hole v6使用FTLCONF变量配置FTL）
  • 不要通过Pi-hole网页UI添加DNS记录（请使用FTLCONF_dns_hosts）
  • 修改FTLCONF_dns_hosts后不要忘记重启Pi-hole
  • 不要在客户端手动配置DNS（请使用路由器DHCP）
  • 修改DNS设置后不要忘记刷新客户端DNS缓存
  • 不要在Pi-hole DNS查询中使用-uall参数（会导致内存问题）

Notes

注意事项

  • Pi-hole v6 uses FTL DNS server, not dnsmasq directly
  • FTLCONF environment variables configure FTL's pihole.toml
  • DNS records added via web UI are not persistent (use FTLCONF_dns_hosts)
  • Router must push Pi-hole DNS to clients via DHCP
  • Client DNS cache can persist for hours (flush after changes)
  • Use domains.toml + manage-domains.sh for automated DNS record management
  • Pi-hole v6使用FTLCONF DNS服务器，而非直接使用dnsmasq
  • FTLCONF环境变量用于配置FTL的pihole.toml
  • 通过网页UI添加的DNS记录不持久化（请使用FTLCONF_dns_hosts）
  • 路由器必须通过DHCP向客户端推送Pi-hole DNS
  • 客户端DNS缓存可能持续数小时（修改后请刷新）
  • 可使用domains.toml + manage-domains.sh实现DNS记录的自动化管理