docker-pi-hole与Caddy联动：构建HTTPS加密的广告拦截服务器
项目地址: https://gitcode.com/gh_mirrors/do/docker-pi-hole 你是否还在为家庭网络中的广告弹窗烦恼？是否担心孩子上网时接触不良内容？通过docker-pi-hole与Caddy的组合，你可以在15分钟内搭建一套安全、高效的广告拦截服务器，同时享受HTTPS加密带来的数据安全保障。本文将详细介绍如何通过Docker Compose实现两者的无缝集成，即使没有专业的网络知识也能轻松上手。
方案架构与工作原理
docker-pi-hole是一个将Pi-hole（网络级广告和恶意内容拦截工具）打包成Docker容器的项目，通过拦截DNS查询实现广告过滤。Caddy则是一款强大的Web服务器，能够自动管理HTTPS证书并提供反向代理功能。两者结合可实现：广告拦截+HTTPS加密+远程安全访问的完整解决方案。
以下是系统工作流程图：
核心组件说明：
- DNS服务：src/start.sh 负责初始化Pi-hole服务，监听53端口处理DNS查询
- 反向代理：examples/Caddyfile 配置HTTPS加密和请求转发规则
- 容器编排：examples/docker-compose-caddy-proxy.yml 定义服务依赖关系和网络配置
准备工作与环境要求
在开始部署前，请确保你的系统满足以下条件：
- Docker Engine 20.10+ 和 Docker Compose v2+
- 至少1GB RAM和10GB可用磁盘空间
- 具备管理员权限的Linux系统（推荐Ubuntu 22.04 LTS）
- 能够访问互联网以获取Docker镜像和HTTPS证书
首先克隆项目仓库：
git clone https://gitcode.com/gh_mirrors/do/docker-pi-hole.git
cd docker-pi-hole
配置步骤详解
1. 自定义Docker Compose配置
项目提供了完整的Caddy集成示例配置，位于examples/docker-compose-caddy-proxy.yml。需要修改以下关键参数：
services:
pihole:
environment:
TZ: 'Asia/Shanghai' # 修改为你的时区
FTLCONF_webserver_api_password: 'your_secure_password' # 设置管理密码
ports:
- "53:53/udp"
- "53:53/tcp"
- "8081:80/tcp" # 内部Web端口，不直接暴露到公网
caddy:
ports:
- "80:80" # HTTP端口，用于Let's Encrypt验证
- "443:443" # HTTPS端口，提供加密访问
2. 配置Caddy反向代理
编辑examples/Caddyfile设置域名和代理规则：
your.domain.com { # 替换为你的域名
tls your@email.com # 用于获取HTTPS证书的邮箱
# 将所有请求转发到Pi-hole的Web界面
reverse_proxy pihole:8081
# 可选：设置访问密码保护
basicauth /admin/* {
admin $2a$14$zJ7ZQPxGv8Z2V6UeQJxS4eX8X8X8X8X8X8X8X8X8X8X8X8X8X8
}
}
注意：Caddy会自动为配置的域名申请和续期Let's Encrypt证书，确保你的域名已正确解析到服务器IP，且80/443端口开放
3. 启动服务栈
使用Docker Compose启动所有服务：
docker compose -f examples/docker-compose-caddy-proxy.yml up -d
首次启动时，系统会执行以下操作：
- 拉取pihole/pihole和caddy镜像
- 创建持久化数据卷存储配置和证书
- 初始化Pi-hole数据库和过滤规则
- 配置Caddy自动获取HTTPS证书
查看服务状态：
docker compose -f examples/docker-compose-caddy-proxy.yml ps
验证与测试
服务启动后，需要进行以下验证步骤：
1. 检查服务运行状态
查看容器日志确认服务正常启动：
# 查看Pi-hole日志
docker logs pihole | grep "FTL started"
# 查看Caddy日志
docker logs caddy | grep "successfully loaded TLS certificate"
2. 配置设备使用Pi-hole DNS
修改路由器或单个设备的DNS服务器设置，指向你的服务器IP。之后访问http://pi.hole/admin或通过HTTPS访问你的域名管理界面。
登录后可以在仪表盘查看拦截统计：
- 查询总量：所有DNS查询请求数
- 拦截率：被阻止的广告域名比例
- 客户端：连接到Pi-hole的设备列表
3. 测试广告拦截效果
访问https://adblock-tester.com/测试广告拦截效果，正常配置下应能拦截90%以上的广告。
高级配置与优化
自定义广告拦截列表
Pi-hole默认使用多个广告拦截列表，你可以通过管理界面添加额外列表：
- 登录Pi-hole管理界面
- 导航到「Adlists」标签
- 添加自定义列表URL，例如：
- https://raw.githubusercontent.com/crazy-max/AdGuardHome-blocklists/master/filter.txt
- https://dbl.oisd.nl/
配置访问控制
为增强安全性，可在examples/Caddyfile中添加IP白名单限制管理界面访问：
your.domain.com {
@admin {
path /admin/*
not remote_ip 192.168.1.0/24 127.0.0.1
}
respond @admin 403
}
性能监控与日志
Pi-hole日志位于容器内的/var/log/pihole/FTL.log，可通过以下命令实时查看：
docker exec -it pihole tail -f /var/log/pihole/FTL.log
对于长期监控，可配置日志转发到ELK栈或Prometheus+Grafana（需额外配置）。
常见问题解决
Caddy无法获取HTTPS证书
如果Caddy启动后没有成功获取证书，请检查：
- 域名是否正确解析到服务器公网IP
- 80/443端口是否被防火墙阻止
- 服务器是否能访问Let's Encrypt服务器
查看详细错误信息：
docker logs caddy | grep "tls"
Pi-hole服务启动失败
检查src/start.sh初始化脚本的执行情况：
docker exec -it pihole bash
cat /var/log/pihole/FTL.log | grep -i error
常见原因包括：端口冲突（53端口被系统resolved服务占用）或文件权限问题。
升级与维护
按照项目README.md中的说明进行升级：
- 拉取最新镜像：
docker pull pihole/pihole:latest - 重启服务：
docker compose -f examples/docker-compose-caddy-proxy.yml up -d
注意：升级前请备份
etc-pihole卷数据，避免配置丢失
总结与最佳实践
通过docker-pi-hole与Caddy的组合，我们构建了一个安全、高效的广告拦截系统，主要优势包括：
- 容器化部署：简化安装和升级流程
- HTTPS加密：保护管理界面的安全访问
- 自动证书管理：Caddy自动处理证书申请和续期
- 数据持久化：通过Docker卷保存配置和统计数据
推荐的最佳实践：
- 定期备份
etc-pihole卷数据 - 启用自动更新但保持监控
- 定期审查拦截统计，优化白名单
- 为管理界面配置双因素认证（通过Caddy插件实现）
完整的项目文档和更多高级用法，请参考README.md和官方文档。如有问题，可通过项目的Issue系统寻求帮助。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
