lovelaze/nebula-sync

nebula-sync

用于将Pi-hole v6.x配置同步到副本的工具。本项目非https://github.com/pi-hole%E7%9A%84%E4%B8%80%E9%83%A8%E5%88%86%EF%BC%8C%E4%BD%86%E9%80%9A%E8%BF%87Pi-hole%E5%AE%9E%E4%BE%8B%E6%8F%90%E4%BE%9B%E7%9A%84API%E6%89%A7%E8%A1%8C%E5%90%8C%E6%AD%A5%E6%93%8D%E4%BD%9C%E3%80%82

核心功能与特性

• 全量同步：使用Pi-hole Teleporter进行完整配置同步
• 选择性同步：支持按功能模块进行选择性同步
• 定时任务调度：可通过Cron表达式设置定时同步计划

使用场景与适用范围

适用于部署了多个Pi-hole v6.x实例的环境，需要保持主节点与副本节点配置一致性的场景，如家庭网络、小型企业网络中多Pi-hole节点的配置统一管理。

使用方法与配置说明

Docker Compose（推荐）

yaml
---
services:
  nebula-sync:
    image: ghcr.io/lovelaze/nebula-sync:latest
    container_name: nebula-sync
    environment:
    - PRIMARY=http://ph1.example.com|password  # 主Pi-hole地址及密码
    - REPLICAS=http://ph2.example.com|password,http://ph3.example.com|password  # 副本Pi-hole列表
    - FULL_SYNC=true  # 启用全量同步
    - RUN_GRAVITY=true  # 同步后运行gravity
    - CRON=0 * * * *  # 每小时执行一次同步

Docker CLI

bash
docker run --rm \
  --name nebula-sync \
  -e PRIMARY="http://ph1.example.com|password" \  # 主Pi-hole配置
  -e REPLICAS="http://ph2.example.com|password" \  # 副本Pi-hole配置
  -e FULL_SYNC=true \  # 启用全量同步
  -e RUN_GRAVITY=true \  # 同步后运行gravity
  ghcr.io/lovelaze/nebula-sync:latest

配置参数说明

必选环境变量

注意：当FULL_SYNC=true时，系统将通过主Pi-hole的Teleporter功能执行完整的导入/导出操作，同步所有设置和配置。

可选环境变量

注意：以下可选设置仅在FULL_SYNC=false时生效，用于实现 granular control 的选择性同步：

免责声明

本项目为非官方社区维护项目，与https://github.com/pi-hole%E6%97%A0%E5%85%B3%E8%81%94%E3%80%82%E8%99%BD%E5%B7%B2%E5%9C%A8%E5%A4%9A%E7%A7%8D%E7%8E%AF%E5%A2%83%E4%B8%AD%E6%B5%8B%E8%AF%95%EF%BC%8C%E4%BD%86%E4%BD%BF%E7%94%A8%E4%BA%92%E8%81%94%E7%BD%91%E4%B8%8A%E7%9A%84%E4%BB%BB%E4%BD%95%E8%BD%AF%E4%BB%B6%E5%9D%87%E5%AD%98%E5%9C%A8%E5%9B%BA%E6%9C%89%E9%A3%8E%E9%99%A9%E3%80%82%E8%AF%A6%E6%83%85%E8%AF%B7%E5%8F%82%E9%98%85https://github.com/lovelaze/nebula-sync/blob/main/LICENSE%E3%80%82

Pi-hole及Pi-hole徽标为Pi-hole LLC的注册商标。