2025最新版docker-pi-hole完全上手：从安装到拦截100%广告-优快云博客

2025最新版docker-pi-hole完全上手：从安装到拦截100%广告

【免费下载链接】docker-pi-hole Pi-hole in a docker container 项目地址: https://gitcode.com/gh_mirrors/do/docker-pi-hole

你是否厌倦了无处不在的弹窗广告？还在为手机流量被广告消耗而烦恼？本文将带你从0开始部署2025年最新版Docker Pi-hole，通过简单配置实现全网络广告拦截，保护家人上网安全。读完本文你将获得：

3分钟快速部署Docker Pi-hole的完整流程
解决端口冲突的实用技巧
配置自动更新广告规则的方法
多设备同步拦截设置的方案

项目简介

Docker Pi-hole是将Pi-hole（一款开源的网络广告拦截工具）打包成Docker容器的项目，通过在本地网络中部署DNS服务器，实现对广告域名的拦截。项目核心文件包括：

启动脚本：src/start.sh
Docker构建文件：src/Dockerfile
环境变量配置：README.md
示例配置：examples/docker-compose-caddy-proxy.yml

准备工作

系统要求

Docker Engine 20.10+
Docker Compose v2+
至少1GB可用内存
稳定的网络连接

安装Docker环境

# Ubuntu/Debian系统
sudo apt update && sudo apt install -y docker.io docker-compose-plugin
sudo systemctl enable --now docker

# 验证安装
docker --version && docker compose version

快速部署

基础部署方案

mkdir -p ~/pihole && cd ~/pihole
wget https://gitcode.com/gh_mirrors/do/docker-pi-hole/raw/master/examples/docker-compose-caddy-proxy.yml -O docker-compose.yml

编辑docker-compose.yml文件，修改关键配置

services:
  pihole:
    environment:
      TZ: 'Asia/Shanghai'  # 修改为你的时区
      FTLCONF_webserver_api_password: 'your_strong_password'  # 设置管理密码
    volumes:
      - ./etc-pihole:/etc/pihole  # 数据持久化

启动容器

docker compose up -d

验证部署

# 查看容器状态
docker compose ps

# 查看初始密码（如果未手动设置）
docker logs pihole | grep "random password"

高级部署方案（带Caddy反向代理）

对于需要同时运行多个Web服务的用户，推荐使用Caddy作为反向代理。项目提供了完整的示例配置：examples/docker-compose-caddy-proxy.yml

核心配置说明：

services:
  caddy:
    image: caddy:latest
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      
  pihole:
    ports:
      - "8081:80/tcp"  # Pi-hole管理界面
      - "53:53/udp"    # DNS服务端口
      - "53:53/tcp"    # DNS服务端口

访问管理界面

部署完成后，通过以下方式访问Pi-hole管理界面：

直接访问：http://服务器IP:8081
通过Caddy代理：http://pi.hole/admin（需配置本地DNS）

首次登录使用之前设置的FTLCONF_webserver_api_password密码，登录后可看到仪表盘，显示拦截统计、客户端列表等信息。

配置网络设备

路由器级配置（推荐）

登录路由器管理界面
找到DNS服务器设置选项
将主DNS设置为Pi-hole服务器IP
保存设置并重启路由器

单设备配置

Windows：设置网络适配器的DNS服务器为Pi-hole IP
macOS：系统偏好设置 → 网络 → 高级 → DNS
Android：WLAN → 长按网络 → 修改网络 → 高级选项 → DNS
iOS：设置 → Wi-Fi → 点击网络旁的"i" → 配置DNS

高级配置

自定义广告规则

进入管理界面 → Settings → Blocklists
添加自定义规则列表：
- 中文广告规则：https://gitee.com/cjx82630/cjxlist/raw/master/ad.txt
- 恶意软件拦截：https://raw.githubusercontent.com/hagezi/dns-blocklists/main/wildcard/malicious-only.zone
手动更新规则

docker exec pihole pihole updateGravity

设置自动更新

创建定时任务自动更新广告规则：

# 编辑crontab
crontab -e

# 添加以下内容（每天凌晨3点更新）
0 3 * * * docker exec pihole pihole updateGravity > /dev/null 2>&1

配置DHCP服务器

如果需要Pi-hole同时作为DHCP服务器（高级功能），需修改docker-compose.yml：

services:
  pihole:
    cap_add:
      - NET_ADMIN  # 必须添加的权限
    ports:
      - "67:67/udp"  # DHCP服务端口
    environment:
      FTLCONF_dhcp_enabled: 'true'
      FTLCONF_dhcp_start_ip: '192.168.1.100'
      FTLCONF_dhcp_end_ip: '192.168.1.200'
      FTLCONF_dhcp_lease_time: '24h'

常见问题解决

端口冲突处理

若53端口被系统自带DNS服务占用：

# 停止并禁用systemd-resolved
sudo systemctl stop systemd-resolved
sudo systemctl disable systemd-resolved

# 修改DNS配置
sudo rm /etc/resolv.conf
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

升级Pi-hole版本

# 拉取最新镜像
docker pull pihole/pihole:latest

# 重启容器
docker compose down && docker compose up -d

注意：升级前请务必备份配置文件：README.md

查看拦截统计

# 查看实时统计
docker exec pihole pihole stats

# 查看Top客户端
docker exec pihole pihole top-clients

# 查看Top被拦截域名
docker exec pihole pihole top-domains --blocked

总结

通过本文的步骤，你已经成功部署了2025年最新版Docker Pi-hole，并实现了全网络广告拦截。关键要点回顾：

使用Docker Compose快速部署：examples/docker-compose-caddy-proxy.yml
正确配置环境变量：README.md
解决端口冲突问题
配置网络设备使用Pi-hole DNS
定期更新广告规则

项目更多高级功能可参考官方文档：README.md，如有问题可提交Issue或参与社区讨论。

扩展阅读

Pi-hole官方文档：https://docs.pi-hole.net/
Docker Compose配置指南：examples/docker-compose-caddy-proxy.yml
高级DNS配置：src/bash_functions.sh
测试脚本：test/tests/test_general.py

【免费下载链接】docker-pi-hole Pi-hole in a docker container 项目地址: https://gitcode.com/gh_mirrors/do/docker-pi-hole

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考