homelab-pihole-dns

Homelab Pi-hole DNS

Pi-hole 是一款適用於全網路的 DNS 廣告攔截器，可運行在 Raspberry Pi 或任何 Linux 主機上。
你網路上的每台裝置都能自動獲得廣告與惡意網域阻擋功能 — 完全不需要安裝任何瀏覽器擴充功能。

時機 / 使用情境

• 在 Raspberry Pi 或 Linux 主機上安裝 Pi-hole
• 將 Pi-hole 設定為家庭網路的 DNS 伺服器
• 新增或管理封鎖清單
• 設定 DNS-over-HTTPS (DoH) 上游解析伺服器
• 建立本地 DNS 記錄（例如 nas.home.lan、pi.home.lan）
• 排查安裝 Pi-hole 後裝置無法連線至網際網路的問題
• 將 Pi-hole 與 DHCP 搭配使用，或直接取代路由器 DHCP

Pi-hole 運作原理

一般流程（未安裝 Pi-hole）：
  裝置 → 請求 ads.tracker.com → ISP DNS → 傳回真實 IP → 成功載入廣告

使用 Pi-hole：
  裝置 → 請求 ads.tracker.com → Pi-hole DNS → 阻擋（傳回 0.0.0.0）→ 廣告未載入

所有 DNS 查詢都會先經過 Pi-hole。
Pi-hole 會比對封鎖清單。
被阻擋的網域會回傳空值（Null response）— 廣告或追蹤器完全無法載入。
允許的網域則會轉發給你的上游解析伺服器（Cloudflare、Google 等）。

安裝步驟

Docker（推薦）

使用 Docker 是安裝 Pi-hole 最簡單的方式，後續更新與備份也相當輕鬆方便。

# docker-compose.yml
services:
  pihole:
    image: pihole/pihole:<pinned-release-tag>
    container_name: pihole
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "80:80/tcp"          # Web 管理介面
    environment:
      TZ: "America/New_York"
      WEBPASSWORD: "${PIHOLE_WEBPASSWORD}"   # 透過 .env 檔案或 secret 設定
      PIHOLE_DNS_: "1.1.1.1;1.0.0.1"
      DNSMASQ_LISTENING: "all"
    volumes:
      - "./etc-pihole:/etc/pihole"
      - "./etc-dnsmasq.d:/etc/dnsmasq.d"
    restart: unless-stopped
    cap_add:
      - NET_ADMIN              # 僅在 Pi-hole 需要提供 DHCP 服務時才需加上

在部署前，請將 <pinned-release-tag> 替換為當前具體的 Pi-hole 版本標籤。
對於長期運作的 DNS 基礎架構，請避免使用 latest，以確保升級過程可控且可複查。

請在 docker-compose.yml 旁建立 .env 檔案並設定 PIHOLE_WEBPASSWORD，使用 chmod 600 限制權限，且切勿將其提交至 Git — 不要直接把密碼硬編碼在 compose 檔案中。

存取 Web 管理介面：http://<pi-ip>/admin

原生裸機安裝（Raspberry Pi OS / Debian / Ubuntu）

在安裝 Pi-hole 之前，必須先為系統指定固定 IP。

# 步驟 1：指派固定 IP（在 Pi OS 上編輯 /etc/dhcpcd.conf）
sudo nano /etc/dhcpcd.conf
# 在檔案底部新增：
interface eth0
static ip_address=192.168.3.2/24
static routers=192.168.3.1
static domain_name_servers=192.168.3.1

# 步驟 2：在執行前下載並檢查安裝腳本。
# 建議優先使用 Pi-hole 針對您作業系統/版本所官方提供的套件或安裝路徑。
curl -sSL https://install.pi-hole.net -o pi-hole-install.sh
less pi-hole-install.sh   # 繼續前先仔細審閱腳本

# 步驟 3：執行安裝
bash pi-hole-install.sh

# 依循互動式安裝程式提示操作：
# 1. 選擇網路介面（有線網路推薦選擇 eth0）
# 2. 選擇上游 DNS（可選擇 Cloudflare 或保留預設，後續皆可修改）
# 3. 確認固定 IP 設定
# 4. 安裝 Web 管理介面（推薦）
# 5. 請妥善記錄最後顯示的管理員密碼

將網路 DNS 指向 Pi-hole

# 方法 1：在路由器 DHCP 設定中變更 DNS（推薦）
  路由器管理介面 → DHCP 設定 → DNS 伺服器
  主要 DNS：192.168.3.2  (Pi-hole IP)
  次要 DNS：留空以進行嚴格阻擋，或使用第二台 Pi-hole。
           若使用公用 DNS（如 1.1.1.1）作為後備，雖可提高部署期間的可用性，
           但因用戶端可能會發送查詢給它，進而導致阻擋效果被旁路（失效）。

  所有裝置在下次 DHCP 租約到期更新時，都會自動取得 Pi-hole 作為 DNS。
  強制更新租約：重新連接 Wi-Fi，或在 Linux 上執行 'sudo dhclient -r && sudo dhclient'

# 方法 2：在單一裝置上手動設定 DNS（適合在全網推行前進行測試）
  Windows：控制台 → 網路介面卡 → IPv4 內容 → 手動指定 DNS
  macOS：系統設定 → 網路 → 詳細資訊 → DNS → 手動指定
  Linux：/etc/resolv.conf 或 NetworkManager

# 方法 3：將 Pi-hole 做為 DHCP 伺服器（取代路由器的 DHCP）
  Pi-hole 管理介面 → Settings → DHCP → Enable
  必須先停用路由器上的 DHCP — 同一網域內存在兩個 DHCP 伺服器會造成 IP 衝突
  優點：主機名稱解析會自動生效（裝置會自動註冊自己的名稱）

封鎖清單管理

# Pi-hole 管理介面 → Adlists → Add new adlist

# 推薦的封鎖清單：
  https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
  # 預設清單 — 包含 20 萬個以上的網域

  https://blocklistproject.github.io/Lists/malware.txt
  # 惡意軟體網域

  https://blocklistproject.github.io/Lists/tracking.txt
  # 追蹤與遙測網域

# 新增清單後：
  Tools → Update Gravity  （下載並編譯所有封鎖清單）

# 如果誤阻擋了正常網站（誤判 False Positive）：
  Pi-hole 管理介面 → Whitelist → Add domain
  範例：api.my-legitimate-service.com

# 即時查看被阻擋的請求：
  Dashboard → Query Log  （即時 DNS 查詢流與阻擋/允許狀態）

DNS-over-HTTPS 上游設定

DNS-over-HTTPS 會加密你的 DNS 查詢，防範 ISP 監控你存取了哪些網站。

# 安裝 cloudflared（Cloudflare 的 DoH 代理工具）。
# 建議優先使用 Cloudflare 的套件庫以進行自動簽署套件驗證。
# 若直接下載執行檔，請鎖定特定版本並驗證其檢查碼（Checksum）。
CLOUDFLARED_VERSION="<pinned-version>"
curl -LO "https://github.com/cloudflare/cloudflared/releases/download/${CLOUDFLARED_VERSION}/cloudflared-linux-arm64"
# 安裝前請先對照 Cloudflare 發布說明確認檢查碼/簽署。
sudo mv cloudflared-linux-arm64 /usr/local/bin/cloudflared
sudo chmod +x /usr/local/bin/cloudflared

# 建立 cloudflared 設定檔
sudo mkdir -p /etc/cloudflared
sudo tee /etc/cloudflared/config.yml << EOF
proxy-dns: true
proxy-dns-port: 5053
proxy-dns-upstream:
  - https://1.1.1.1/dns-query
  - https://1.0.0.1/dns-query
EOF

# 建立 systemd 服務
sudo cloudflared service install
sudo systemctl start cloudflared
sudo systemctl enable cloudflared

# 現在將 Pi-hole 指向本地的 DoH 代理：
# Pi-hole 管理介面 → Settings → DNS → Custom upstream DNS
# 設定為：127.0.0.1#5053
# 取消勾選所有其他上游解析伺服器

本地 DNS 記錄

讓你的各項服務可以透過自訂名稱進行存取（例如 nas.home.lan、grafana.home.lan）。

網域名稱說明： .home.lan 廣泛應用於 Homelab 中且實務上可行。
不過 IETF 針對本地用途保留的標準後綴是 .home.arpa (RFC 8375) — 遵循標準建議使用此後綴。
請避免在 Pi-hole DNS 記錄中使用 .local，因為它會與 mDNS/Bonjour 產生衝突。

# Pi-hole 管理介面 → Local DNS → DNS Records

  Domain              IP
  nas.home.lan        192.168.30.10
  pi.home.lan         192.168.30.2
  grafana.home.lan    192.168.30.3
  proxmox.home.lan    192.168.30.4

# 從網路上的任何裝置測試：
  ping nas.home.lan        → 192.168.30.10
  http://grafana.home.lan  → 開啟你的 Grafana 儀表板

# 子網域請新增 CNAME：
  Pi-hole 管理介面 → Local DNS → CNAME Records
  Domain: portainer.home.lan → Target: pi.home.lan

疑難排解

# Pi-hole 誤阻擋了不該阻擋的內容
pihole -q example.com          # 檢查網域是否被阻擋及來自哪份清單
pihole -w example.com          # 立即加入白名單

# DNS 完全無法解析
pihole status                  # 檢查 pihole-FTL 是否正在運行
dig @192.168.3.2 google.com   # 直接針對 Pi-hole 測試 DNS 解析

# 重啟 Pi-hole DNS 服務
pihole restartdns

# 查看特定裝置的查詢紀錄
pihole -t                      # 即時追蹤所有查詢 Log
# 或在 Web 管理介面的 Query Log 中依用戶端篩選

# 更新 Pi-hole Gravity（更新封鎖清單）
pihole -g

反模式（應避免的做法）

# 差勁：過度依賴單一 Pi-hole 且沒有復原計畫
# 如果 Pi-hole 當機或 Pi 斷電，整個網路的 DNS 解析就會中斷
# 良好：在設定期間保留一份記錄好的路由器預設備援設定，以便隨時復原
# 最佳：運行兩台 Pi-hole 實例實現高可用性備援；若追求嚴格阻擋，應避免設定公用 DNS 做為後備

# 差勁：在未設定固定 IP 的情況下安裝 Pi-hole
# 一旦 Pi 取得新的 DHCP IP，所有裝置都將失去 DNS 解析能力
# 良好：先設定好固定 IP，再進行 Pi-hole 的安裝

# 差勁：在未停用路由器 DHCP 的情況下啟用 Pi-hole DHCP
# 相同網域內有兩個 DHCP 伺服器會發放互相衝突的 IP
# 良好：先停用路由器的 DHCP，然後再啟用 Pi-hole 的 DHCP

# 差勁：從不更新 Gravity（封鎖清單）
# 新的廣告與惡意網域會不斷出現 — 過期的清單將無法阻擋它們
# 良好：設定每週自動更新 Gravity：pihole -g（或在 Settings → API 中啟用）

最佳實踐

• 在安裝 Pi-hole 前，先為 Pi 指定固定 IP 或設定 DHCP 靜態位址保留
• 將 Pi-hole 用作主要 DNS；若需要備援且要求嚴格阻擋，請部署第二台 Pi-hole，而非新增公用 DNS 解析器
• 透過 cloudflared 啟用 DoH (DNS-over-HTTPS)，加密上游查詢
• 使用 home.lan 作為你的本地網域，並為所有服務建立 DNS 記錄
• 定期檢查 Query Log — 被阻擋的查詢能幫你掌握網路內裝置的連線行為

相關 Skills

• homelab-network-setup
• homelab-vlan-segmentation
• homelab-wireguard-vpn