diginc/pi-hole

Docker Pi-hole 镜像说明

镜像概述

本镜像封装了Pi-hole DNS广告拦截工具的轻量级容器，注意：官方已迁移至 pihole/pihole 镜像，如需最新版本（如v4.0+）请优先使用官方镜像。Pi-hole无需在每个设备安装客户端，通过DNS解析拦截广告，支持x86架构（ARM用户需使用 diginc/pihole-multiarch 系列镜像）。

核心功能

1. DNS广告拦截：阻止广告域名解析，减少网页、应用内广告干扰。
2. IPv4/IPv6支持：同时拦截IPv4和IPv6广告域名。
3. Web管理界面：通过 http://<服务器IP>/admin 管理黑白名单、查看拦截统计。
4. 自动更新：定期同步广告列表，保持拦截效果。
5. DHCP服务：可选开启DHCP功能，统一分配网络设备IP。
6. SSL广告Sinkhole：通过443端口拦截HTTPS广告，避免加载延迟。

使用场景

• 家庭网络：为所有联网设备（手机、电脑、智能家电）提供广告拦截。
• 小型办公：减少员工浏览时的广告干扰，提升工作效率。
• 个人开发：测试无广告环境下的网页或应用表现。

配置说明

环境变量

端口映射

• 53:53/tcp & 53:53/udp：DNS服务端口。
• 80:80：Web管理界面端口。
• 443:443：SSL广告拦截端口。
• 67:67/udp：DHCP服务端口（若开启）。

数据持久化

需挂载以下目录保存配置（避免容器删除后数据丢失）：

• /etc/pihole/：Pi-hole核心配置文件。
• /etc/dnsmasq.d/：DNSmasq服务配置文件。

部署示例

Docker Run 命令

bash
# 获取服务器IP（自动检测）
IP=$(ip route get 8.8.8.8 | awk '{print $NF; exit}')
IPv6=$(ip -6 route get 2001:4860:4860::8888 | awk '{for(i=1;i<=NF;i++) if($i=="src") print $(i+1)}')
DOCKER_CONFIGS=$(pwd)/pihole-data

# 创建配置目录
mkdir -p ${DOCKER_CONFIGS}/pihole ${DOCKER_CONFIGS}/dnsmasq.d

# 启动容器
docker run -d \
  --name pihole \
  -p 53:53/tcp -p53:53/udp \
  -p 80:80 \
  -p443:443 \
  -p67:67/udp \
  -v ${DOCKER_CONFIGS}/pihole:/etc/pihole \
  -v ${DOCKER_CONFIGS}/dnsmasq.d:/etc/dnsmasq.d \
  -e ServerIP=${IP} \
  -e ServerIPv6=${IPv6} \
  -e TZ=Asia/Shanghai \
  -e WEBPASSWORD=MyPiHole@2024 \
  --restart=unless-stopped \
  --cap-add=NET_ADMIN \
  diginc/pihole:latest

# 查看初始密码（若未设置WEBPASSWORD）
echo "管理界面初始密码："
docker logs pihole 2>/dev/null | grep 'password:'

Docker Compose 示例

创建 docker-compose.yml 文件：

yaml
version: "3"
services:
  pihole:
    image: diginc/pihole:latest
    container_name: pihole
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "80:80"
      - "443:443"
      - "67:67/udp"
    volumes:
      - ./pihole:/etc/pihole
      - ./dnsmasq.d:/etc/dnsmasq.d
    environment:
      ServerIP: "192.168.1.100"
      TZ: "Asia/Shanghai"
      WEBPASSWORD: "MyPiHole@2024"
    restart: unless-stopped
    cap_add:
      - NET_ADMIN

运行命令：docker-compose up -d

升级与维护

1. 升级镜像：

   bash
   docker pull diginc/pihole:latest
   docker rm -f pihole
   docker run <原有参数> diginc/pihole:latest
   

   提示：升级前确保数据已通过卷挂载持久化。

2. 常用操作：

   • 更新广告列表：docker exec pihole pihole updateGravity
   • 添加白名单：docker exec pihole pihole -w example.com
   • 重置密码：docker exec pihole pihole -a -p NewPassword2024
   • 查看日志：docker logs pihole