nhmike94/gravity-sync-docker

Gravity Sync Docker 镜像

镜像概述和主要用途

该Docker镜像用于运行https://github.com/vmstan/gravity-sync%EF%BC%8C%E6%94%AF%E6%8C%81X86/64%E5%92%8CARM64%E6%9E%B6%E6%9E%84%E3%80%82ARM%E7%89%88%E6%9C%AC%E9%95%9C%E5%83%8F%E5%90%8D%E7%A7%B0%E5%89%8D%E7%BC%80%E4%B8%BA%E2%80%9Carm-%E2%80%9D%EF%BC%88%E4%BE%8B%E5%A6%82x86/64%E7%9A%84%60latest%60%E5%AF%B9%E5%BA%94ARM%E7%89%88%E6%9C%AC%E7%9A%84%60arm-latest%60%EF%BC%89%E3%80%82Gravity Sync主要用于同步多个PiHole实例的配置，确保网络广告拦截规则和DNS设置保持一致。

核心功能和特性

• 跨架构支持：兼容X86/64和ARM64处理器
• 配置同步：自动同步PiHole的gravity数据库、自定义DNS规则等核心配置
• 自动化操作：支持定时同步和备份，减少手动干预
• 安全设计：通过SSH密钥认证实现远程主机安全连接
• 持久化存储：关键数据（备份、日志、SSH密钥）可通过挂载卷持久化

使用场景和适用范围

• 多PiHole实例部署环境，需保持配置一致性
• 希望简化PiHole配置同步流程的用户
• 采用Docker容器化管理服务的家庭或小型企业网络
• 需要在不同架构设备（如x86服务器和ARM开发板）上运行PiHole的场景

使用方法和配置说明

运行前准备

升级注意事项

如从旧版本升级，需查看目标版本的升级说明。

预启动脚本

需运行预启动脚本配置远程主机，推荐遵循所有建议配置，否则可能需要手动配置或降低安全级别。操作步骤：

1. 创建本地SSH目录：

   bash
   mkdir /path/to/.ssh
   

2. 以交互模式运行容器，挂载SSH目录并执行预启动脚本：

   bash
   docker run -t -i -v "/path/to/.ssh:/root/.ssh:rw" --rm docker_gravitysync /usr/local/bin/prelaunch.sh
   

手动预启动

如选择手动配置，需预生成SSH密钥并挂载到容器（详见SSH密钥部分）。建议在远程主机创建专用用户（如gravitysync）接收SSH连接（详见用户创建建议）。

容器配置

Gravity Sync服务配置请参考https://github.com/vmstan/gravity-sync%E3%80%82%E6%B3%A8%E6%84%8F%EF%BC%9ADocker%E9%95%9C%E5%83%8F%E4%B8%AD%E7%9A%84%E9%83%A8%E5%88%86%E9%85%8D%E7%BD%AE%E9%A1%B9%E5%90%8D%E7%A7%B0%E4%B8%8E%E5%8E%9F%E7%94%9FGravity Sync不同，差异项已在下表中标记（!）。容器首次运行时会将环境变量映射到配置文件，请勿挂载自定义配置文件，否则会导致容器启动失败。

Docker Compose示例

yaml
gravitysync:
  build:
    context: /docker/gravity-sync-docker/
    dockerfile: /docker/gravity-sync-docker/Dockerfile
  container_name: "gravitysync"
  restart: "unless-stopped"
  environment:
    TZ: "ETC/UTC"
    REMOTE_HOST: "192.168.0.1"
    REMOTE_USER: "gravitysync"
    LOCAL_INSTALL_TYPE: "docker"
    REMOTE_INSTALL_TYPE: "docker"
    LOCAL_PIHOLE_DIR: "/etc/pihole/"
    REMOTE_PIHOLE_DIR: "/docker/pihole/config/pihole/"
    LOCAL_DNSMASQ_DIR: "/etc/dnsmasq.d/"
    REMOTE_DNSMASQ_DIR: "/docker/pihole/config/dnsmasq/"
    LOCAL_PH_INSTALL_TYPE: "default"
    REMOTE_PH_INSTALL_TYPE: "docker"
    LOCAL_FILE_OWNER: "root:root"
    REMOTE_FILE_OWNER: "root:root"
    INCLUDE_CNAME: "1"
    SYNC_FREQUENCY: "15"
    BACKUP_HOUR: "4"
    DEBUG: "true"
  volumes:
    - "/docker/gravity-sync/logs/:/root/gravity-sync/logs/:rw"
    - "/docker/gravity-sync/data/backup:/root/gravity-sync/backup/:rw"
    - "/docker/gravity-sync/data/gravity-sync.md5:/root/gravity-sync/gravity-sync.md5:rw"
    - "/docker/gravity-sync/data/.ssh/:/root/.ssh/:rw"
    - "/docker/pihole/config/pihole:/etc/pihole/:rw"
    - "/docker/pihole/config/dnsmasq:/etc/dnsmasq.d/:rw"
    - "/var/run/docker.sock:/var/run/docker.sock:ro"

挂载点说明

容器内以下路径需根据需求挂载到主机，确保数据持久化和功能正常：

Docker Socket

• 路径：/var/run/docker.sock
• 权限：只读
• 用途：允许容器与主机Docker进程交互，向PiHole容器传递命令

PiHole配置目录

• 路径：/etc/pihole/
• 权限：读写
• 用途：存储gravity数据库等核心配置。标准PiHole安装路径为/etc/pihole，需确保容器内挂载路径与LOCAL_PIHOLE_DIR环境变量值一致

Gravity Sync备份目录

• 路径：/root/gravity-sync/data/backup/
• 权限：读写
• 用途：存储同步备份文件，默认保留7天（可通过BACKUP_RETAIN调整）。不挂载此目录会导致容器更新时丢失备份

Gravity Sync日志文件

• 路径：/root/gravity-sync/logs/gravity-sync.log、/root/gravity-sync/logs/gravity-sync.cron
• 权限：读写
• 用途：记录Cron运行日志和历史执行记录，挂载后可在主机查看并持久化日志

Gravity Sync MD5文件

• 路径：/root/gravity-sync/gravity-sync.md5
• 权限：读写
• 用途：记录本地和远程gravity.db、custom.list等文件的MD5哈希，需持久化以确保同步准确性

SSH密钥目录

• 路径：/root/.ssh/
• 权限：只读
• 用途：存储SSH密钥，首次运行前需配置。不持久化会导致容器每次启动生成新密钥，无法连接远程主机（详见SSH密钥）

用户创建建议

如已运行预启动脚本，可选择自动创建用户

建议在远程主机创建专用用户（如gravitysync），避免使用root或个人管理账户。该用户需无密码sudo权限和读写PiHole配置的权限。Ubuntu系统配置示例：

bash
sudo adduser gravitysync
sudo echo "gravitysync ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/gravitysync
sudo usermod -a -G sudo gravitysync
sudo usermod -a -G docker gravitysync

SSH密钥

如已运行预启动脚本，密钥会自动生成配置

需配置SSH密钥实现远程主机认证，生成方法：

使用Alpine容器生成（适用于无OpenSSH客户端的系统）

bash
docker run -t -i --rm alpine:latest apk --update add openssh-client && ssh-keygen -t rsa -f /tmp/id_rsa

使用系统OpenSSH客户端生成（适用于已安装OpenSSH的系统）

直接执行ssh-keygen -t rsa生成密钥

复制公钥到远程主机

使用ssh-copy-id工具复制公钥：

bash
ssh-copy-id -i /tmp/id_rsa.pub gravitysync@192.168.0.1

（需替换/tmp/id_rsa.pub为实际公钥路径，gravitysync为远程用户名，192.168.0.1为远程主机IP）

升级说明

3.0.0版本

• 变更：日志目录挂载点更新（详见Gravity Sync日志文件）
• 新增：LOCAL_PH_INSTALL_TYPE和REMOTE_PH_INSTALL_TYPE两个配置选项

待办事项

• 集成更多配置过程中的错误检测机制