shirom/pihole-sync

docker-pihole-sync

https://img.shields.io/docker/pulls/shirom/pihole-sync.svg?style=for-the-badge&logo=github](https://hub.docker.com/repository/docker/shirom/pihole-sync)

镜像概述和主要用途

Pihole作为网络核心，一旦故障会导致整个网络瘫痪。为解决此问题，通常部署冗余Pihole，但需避免在两个设备上重复配置。本Docker容器实现两个Pihole间的同步，采用主从模式（未来将支持更多节点），只需更新主Pihole，从Pihole会自动同步。支持同步/etc/pihole/和/etc/dnsmasq.d/目录（排除客户端独立目录），基于Alpine 3.12构建，集成dumb-init、openssh、rsync、inotify-tools和bash，镜像体积约28MB。

通过在主Pihole部署sender容器、从Pihole部署receiver容器，解决SSH权限问题：sender容器仅SSH到receiver容器而非主机，即使容器被入侵，***者也仅能访问接收容器及其挂载卷，保障安全性。

注意：若接收端Pihole未运行在Docker中，或可接受给接收端开放root权限（降低安全性），则无需使用接收容器。

核心功能和特性

1. Docker原生支持

适用于Docker环境，可通过docker-compose统一管理，确保整个项目通过docker-compose up启动、docker-compose down停止，无需在Docker外运行独立同步脚本。

2. 持续同步

监控指定目录变化，实时同步至其他Pihole，更新白名单等配置后可立即生效。

3. 全量设置传输

不仅同步列表，还包括密码、上游DNS设置等所有配置，确保主从Pihole完全一致。

4. 无需依赖外部仓库

不同于pihole-cloudsync，无需同步至代码仓库，避免Pihole连接互联网，也不会在Github产生大量提交记录，保护隐私和仓库整洁。

注意：主Pihole需能SSH连接到从Pihole。若存在网络限制（如Pihole位于不同***后），建议使用pihole-cloudsync。

使用场景和适用范围

• 家庭或企业网络中部署冗余Pihole，避免单点故障
• 使用Docker部署Pihole，希望通过容器化方式管理配置同步
• 需要实时同步Pihole配置，确保主从设备设置一致
• 希望避免重复配置Pihole，提高管理效率

详细使用方法和配置说明

docker-compose配置示例

主Pihole（sender节点）docker-compose.yml

yaml
pihole:
    image: docker.xuanyuan.run/pihole/pihole:latest
    volumes:
        - /mnt/ext/pihole/etc-pihole:/etc/pihole
        - /mnt/ext/pihole/etc-dnsmasq.d:/etc/dnsmasq.d
    # 其他Pihole配置...

pihole-sync-sender:
    image: docker.xuanyuan.run/shirom/pihole-sync:latest
    container_name: pihole-sync-sender
    volumes:
        - /mnt/ext/piholesync/root:/root
        - /mnt/ext/pihole/etc-pihole:/mnt/etc-pihole:ro
        - /mnt/ext/pihole/etc-dnsmasq.d:/mnt/etc-dnsmasq.d:ro
    environment:
        - "NODE=sender"
        - "REM_HOST=(远程Pi的IP地址)"
        - "REM_SSH_PORT=22222"

从Pihole（receiver节点）docker-compose.yml

yaml
pihole:
    image: docker.xuanyuan.run/pihole/pihole:latest
    volumes:
        - /mnt/ext/pihole/etc-pihole:/etc/pihole
        - /mnt/ext/pihole/etc-dnsmasq.d:/etc/dnsmasq.d
    # 其他Pihole配置...

pihole-sync-receiver:
    image: docker.xuanyuan.run/shirom/pihole-sync:latest
    container_name: pihole-sync-receiver
    volumes:
        - /mnt/ext/piholesync/root:/root
        - /mnt/ext/piholesync/etc-ssh:/etc/ssh
        - /mnt/ext/pihole/etc-pihole:/mnt/etc-pihole
        - /mnt/ext/pihole/etc-dnsmasq.d:/mnt/etc-dnsmasq.d
    environment:
        - "NODE=receiver"
    ports:
        - 22222:22

卷说明

环境变量说明

端口说明

支持信息

• 容器运行时Shell访问：docker exec -it pihole-sync /bin/bash
• 查看日志：docker logs pihole-sync
• SSH密钥配置步骤：
  1. 在receiver节点，在配置目录中创建authorized_keys文件。例如，若receiver的/root卷挂载为/docker/config/piholesync/root:/root，则创建文件/docker/config/piholesync/root/.ssh/authorized_keys。
  2. 将以下内容（不含标记行）复制到authorized_keys文件：

     ####### COPY BELOW THIS LINE, BUT NOT THIS LINE ########
     /root/.ssh/id_ed25519.pub
     ####### COPY ABOVE THIS LINE, BUT NOT THIS LINE ########
     

  3. 重启容器。

本地构建

如需本地修改或开发，可执行以下命令构建镜像：

bash
docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v6,linux/arm/v7 --tag shirom/pihole-sync --output type=image,push=false .

多架构构建需安装QEMU。