cyberoslab/pihole

pihole Docker镜像文档

镜像概述

pihole Docker镜像是一个跨平台的网络广告拦截解决方案，基于pihole开源项目构建，支持多种Linux架构（linux/amd64、linux/arm64、linux/arm/v6、linux/arm/v7）。该镜像将pihole的DNS服务器与广告拦截功能容器化，便于快速部署和管理，可在不同硬件平台上提供一致的网络广告屏蔽体验。

核心功能与特性

• 多平台支持：兼容主流Linux架构，包括amd64（x86_64）、arm64（64位ARM）、arm/v6（32位ARMv6）、arm/v7（32位ARMv7），适用于PC、服务器、树莓派等多种设备。
• DNS服务器：内置DNS解析服务，可作为本地网络的DNS服务器，提升域名解析速度。
• 广告拦截：通过拦截已知广告域名，阻止网络广告、跟踪器和***网站，减少带宽占用并提升浏览体验。
• 轻量级部署：容器化设计，资源占用低，部署简单，易于集成到现有网络环境。

使用场景

• 家庭网络广告拦截：部署在家庭路由器或树莓派上，为所有连接设备提供广告屏蔽服务。
• 个人设备防护：在个人电脑、服务器或开发板上运行，保护单设备免受广告和***域名侵扰。
• 小型办公网络：为小型办公环境提供集中式广告管理，提升团队网络使用效率。

使用方法与配置说明

基本部署（docker run）

bash
docker run -d \
  --name pihole \
  -p 53:53/tcp -p 53:53/udp \
  -p 80:80/tcp \
  -v "$(pwd)/pihole:/etc/pihole" \
  -v "$(pwd)/dnsmasq.d:/etc/dnsmasq.d" \
  -e TZ="Asia/Shanghai" \
  -e WEBPASSWORD="your_secure_password" \
  --restart=unless-stopped \
  pihole/pihole:latest

参数说明

• 端口映射：

  • 53:53/tcp 和 53:53/udp：DNS服务端口，必须映射以提供DNS解析功能。
  • 80:80/tcp：Web管理界面端口，用于配置pihole（默认用户名admin，密码通过WEBPASSWORD设置）。

• 数据持久化：

  • -v "$(pwd)/pihole:/etc/pihole"：存储pihole配置和黑名单数据。
  • -v "$(pwd)/dnsmasq.d:/etc/dnsmasq.d"：存储DNS服务器（dnsmasq）配置。

• 环境变量：

  • TZ：时区设置（如Asia/Shanghai），用于日志时间同步。
  • WEBPASSWORD：Web管理界面登录密码，建议设置强密码。

docker-compose配置示例

创建docker-compose.yml文件：

yaml
version: "3"

services:
  pihole:
    image: pihole/pihole:latest
    container_name: pihole
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "80:80/tcp"
    volumes:
      - ./pihole:/etc/pihole
      - ./dnsmasq.d:/etc/dnsmasq.d
    environment:
      - TZ=Asia/Shanghai
      - WEBPASSWORD=your_secure_password
    restart: unless-stopped

启动服务：

bash
docker-compose up -d

访问与配置

部署完成后，通过浏览器访问 http://<容器IP或主机IP> 进入Web管理界面，使用设置的WEBPASSWORD登录，可进行广告规则更新、白名单/黑名单管理、DNS设置等操作。