jacklul/pihole

Pi-hole 集成 pihole-updatelists 镜像

镜像概述与主要用途

本镜像是基于官方 https://hub.docker.com/r/pihole/pihole 镜像构建的增强版本，集成了 https://github.com/jacklul/pihole-updatelists 脚本，旨在简化和自动化Pi-hole广告拦截列表的管理与更新流程。

主要用途：提供DNS级别的网络广告、跟踪器和***域名拦截功能，并通过集成的pihole-updatelists脚本实现广告拦截列表的自动化更新、多源列表聚合及自定义规则管理，适用于家庭或小型网络环境的广告过滤需求。

核心功能与特性

1. 基于官方Pi-hole核心：完整继承官方Pi-hole的全部功能，包括DNS广告拦截、网络流量统计、客户端管理、自定义域名过滤规则等。
2. 集成pihole-updatelists脚本：增强列表管理能力，支持从多个来源自动拉取、合并和更新广告拦截列表，减少手动维护成本。
3. 自动化更新机制：可配置定时自动更新拦截列表，确保过滤规则始终保持最新状态。
4. 兼容性：与官方Pi-hole镜像的配置方式、数据卷和环境变量高度兼容，易于迁移和部署。

使用场景与适用范围

• 家庭网络环境：为家庭网络中的所有设备（电脑、手机、智能家电等）提供统一的广告拦截服务。
• 小型办公网络：在小型团队或办公室中部署，减少广告干扰并提升网络浏览效率。
• 需要自动化列表管理的场景：适用于希望通过脚本化方式管理多个拦截列表，或需要定期更新过滤规则的用户。
• Pi-hole进阶用户：为熟悉Pi-hole基本功能并需要增强列表管理能力的用户提供便捷工具。

使用方法与配置说明

前置要求

• Docker引擎（20.10+推荐）或Docker Compose环境。
• 具备固定IP的主机（推荐，确保客户端DNS设置稳定）。
• 开放网络端口：53（DNS，TCP/UDP）、80（Web管理界面，可自定义映射）。

部署方式

1. Docker Run 命令部署

bash
docker run -d \
  --name pihole-updatelists \
  -p 53:53/tcp -p 53:53/udp \
  -p 80:80 \
  -e TZ="Asia/Shanghai" \
  -e WEBPASSWORD="your_secure_password" \
  -e SERVERIP="192.168.1.100" \
  -e PIHOLE_DNS_1="8.8.8.8" -e PIHOLE_DNS_2="8.8.4.4" \
  -e UPDATELISTS_AUTOUPDATE="true" \
  -e UPDATELISTS_INTERVAL="24h" \
  -v "$(pwd)/pihole:/etc/pihole" \
  -v "$(pwd)/dnsmasq.d:/etc/dnsmasq.d" \
  --restart=unless-stopped \
  jacklul/pihole-updatelists:latest  # 假设镜像名称为jacklul/pihole-updatelists，具体以实际为准

2. Docker Compose 部署

创建 docker-compose.yml 文件：

yaml
version: "3"

services:
  pihole:
    image: jacklul/pihole-updatelists:latest  # 替换为实际镜像名称和标签
    container_name: pihole-updatelists
    restart: unless-stopped
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "80:80"  # Web管理界面端口（可自定义为其他端口，如8080:80）
    environment:
      # 基础配置（继承自官方Pi-hole）
      - TZ=Asia/Shanghai
      - WEBPASSWORD=your_secure_password  # 必填：Web界面登录密码
      - SERVERIP=192.168.1.100  # 主机IP地址
      - PIHOLE_DNS_1=8.8.8.8  # 上游DNS服务器1
      - PIHOLE_DNS_2=8.8.4.4  # 上游DNS服务器2
      
      # pihole-updatelists配置（详细参数见GitHub文档）
      - UPDATELISTS_AUTOUPDATE=true  # 启用自动更新
      - UPDATELISTS_INTERVAL=24h  # 每24小时更新一次列表
      - UPDATELISTS_URLS=https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts,https://mirror1.malwaredomains.com/files/justdomains  # 自定义列表URL（示例）
    volumes:
      - ./pihole:/etc/pihole  # 持久化Pi-hole配置和列表数据
      - ./dnsmasq.d:/etc/dnsmasq.d  # dnsmasq配置文件
    cap_add:
      - NET_ADMIN  # 部分环境需此权限修改网络配置（如DNS端口占用时）

配置参数说明

基础环境变量（继承自官方Pi-hole）

pihole-updatelists专用环境变量

详细配置请参考 https://github.com/jacklul/pihole-updatelists?tab=readme-ov-file#environment-variables%EF%BC%8C%E4%BB%A5%E4%B8%8B%E4%B8%BA%E5%B8%B8%E7%94%A8%E5%8F%82%E6%95%B0%EF%BC%9A

数据卷说明

验证与维护

1. 访问Web界面：部署后通过 http://<主机IP> 访问Pi-hole管理界面，使用 WEBPASSWORD 登录。
2. 检查列表更新：在Web界面 Settings > Blocklists 中查看列表状态，或通过容器日志验证更新任务：

   bash
   docker logs pihole-updatelists | grep "updatelists"
   

3. 备份配置：定期备份 ./pihole 目录，防止数据丢失。

注意事项

1. 问题排查：若遇到功能异常，需先确认问题是否由pihole-updatelists脚本导致。可通过部署官方Pi-hole镜像（不含此脚本）验证：若问题消失，则可能与本镜像集成的脚本相关，需向 https://github.com/jacklul/pihole-updatelists/issues 反馈；若问题仍存在，则可能是Pi-hole核心问题，需参考 官方Pi-hole支持渠道。
2. 列表源选择：避免添加过多低质量列表，可能导致DNS查询延迟或误拦截。建议选择维护活跃的开源列表（如StevenBlack/hosts）。
3. 安全加固：WEBPASSWORD 需设置强密码，且避免将Web管理界面暴露在公网。