ghcr.io/bakito/adguardhome-sync:alpine-main

AdGuardHome sync

将 AdGuardHome 配置同步到副本实例。

FAQ & Deprecations

有关常见问题（FAQ）和弃用说明，请查阅 wiki。

Current sync features

• 常规设置（General Settings）
• 过滤器（Filters）
• 重写规则（Rewrites）
• 服务（Services）
• 客户端（Clients）
• DNS 配置（DNS Config）
• DHCP 配置（DHCP Config）
• 主题（Theme）

默认情况下，所有功能均已启用。可在配置中禁用单个功能。

Setup of initial instances

如果通过配置 autoSetup 启用，新的 AdGuardHome 副本实例可以自动安装。自动安装期间，管理界面在运行时将监听端口 3000。

要跳过自动设置

Install

从发布版本获取或从源代码安装

go install github.com/bakito/adguardhome-sync@latest

Brew

# 添加 tap
brew tap bakito/tap
brew trust bakito/tap

# 安装
brew install --cask adguardhome-sync

Prerequisites

源实例和副本实例都必须通过 AdGuardHome 安装向导完成初始设置。

Config via environment variables

对于副本，请将 # 替换为副本的索引号。例如：REPLICA#_URL -> REPLICA1_URL

YAML Configuration file

位置：$HOME/.adguardhome-sync.yaml

# 同步间隔的 Cron 表达式（字符串）
cron:
# 启动时运行同步（布尔值）
runOnStart:
# 仅打印当前配置并停止应用（布尔值）
printConfigOnly:
# 出错时继续同步（布尔值）
continueOnError:
# 定义自定义 HTTP 客户端超时（格式：^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$）（字符串）
httpClientTimeout:
# 源实例（结构体）
origin:
# AdGuardHome 实例的 URL（字符串）
url:
# AdGuardHome 实例的 Web URL（字符串）
webURL:
# API 路径（字符串）
apiPath:
# AdGuardHome 用户名（字符串）
username:
# AdGuardHome 密码（字符串）
password:
# AdGuardHome Cookie（字符串）
cookie:
# 请求头（格式：'key1:value1,key2:value2'）（map[string:string]）
requestHeaders:
# 跳过 TLS 验证（布尔值）
insecureSkipVerify:
# 如果实例未初始化，则自动设置（布尔值）
autoSetup:
# 网络接口名称（字符串）
interfaceName:
# 启用 DHCP 服务器（布尔值）
dhcpServerEnabled:
# 单个副本实例（不要与 'replicas' 同时使用）（结构体）
replica:
# AdGuardHome 实例的 URL（字符串）
url:
# AdGuardHome 实例的 Web URL（字符串）
webURL:
# API 路径（字符串）
apiPath:
# AdGuardHome 用户名（字符串）
username:
# AdGuardHome 密码（字符串）
password:
# AdGuardHome Cookie（字符串）
cookie:
# 请求头（格式：'key1:value1,key2:value2'）（map[string:string]）
requestHeaders:
# 跳过 TLS 验证（布尔值）
insecureSkipVerify:
# 如果实例未初始化，则自动设置（布尔值）
autoSetup:
# 网络接口名称（字符串）
interfaceName:
# 启用 DHCP 服务器（布尔值）
dhcpServerEnabled:
# 副本实例列表（不要与 'replica' 同时使用）（结构体）
replicas:
# AdGuardHome 实例的 URL（字符串）
- url:
# AdGuardHome 实例的 Web URL（字符串）
webURL:
# API 路径（字符串）
apiPath:
# AdGuardHome 用户名（字符串）
username:
# AdGuardHome 密码（字符串）
password:
# AdGuardHome Cookie（字符串）
cookie:
# 请求头（格式：'key1:value1,key2:value2'）（map[string:string]）
requestHeaders:
# 跳过 TLS 验证（布尔值）
insecureSkipVerify:
# 如果实例未初始化，则自动设置（布尔值）
autoSetup:
# 网络接口名称（字符串）
interfaceName:
# 启用 DHCP 服务器（布尔值）
dhcpServerEnabled:
# （结构体）
api:
# API 端口（端口设为 0 时禁用 API）（整数）
port:
# API 用户名（字符串）
username:
# API 密码（字符串）
password:
# API 深色模式（布尔值）
darkMode:
# （结构体）
metrics:
# 启用指标（布尔值）
enabled:
# 指标抓取间隔（int64）
scrapeInterval:
# 指标日志查询限制（整数）
queryLogLimit:
# （结构体）
tls:
# API TLS 证书目录（字符串）
certDir:
# API TLS 证书文件名（字符串）
certName:
# API TLS 密钥文件名（字符串）
keyName:
# （结构体）
features:
# （结构体）
dns:
# 同步 DNS 访问列表（布尔值）
accessLists:
# 同步 DNS 服务器配置（布尔值）
serverConfig:
# 同步 DNS 重写规则（布尔值）
rewrites:
# （结构体）
dhcp:
# 同步 DHCP 服务器配置（布尔值）
serverConfig:
# 同步 DHCP 静态租约（布尔值）
staticLeases:
# 同步常规设置（布尔值）
generalSettings:
# 同步保护状态（如果 generalSettings 禁用则此功能也禁用）（布尔值）
protectionStatus:
# 同步查询日志配置（布尔值）
queryLogConfig:
# 同步统计配置（布尔值）
statsConfig:
# 同步客户端设置（布尔值）
clientSettings:
# 同步服务（布尔值）
services:
# 同步过滤器（使用子字段进行细粒度控制）（结构体）
filters:
# 同步黑名单过滤器（布尔值）
blacklist:
# 同步白名单过滤器（布尔值）
whitelist:
# 同步用户规则（布尔值）
userRules:
# 同步 Web UI 主题（布尔值）
theme:
# 同步 TLS 配置（布尔值）
tlsConfig:

Username / Password vs. Cookie

某些 AdGuard Home 实例不支持基本身份验证。例如，许多内置 AdGuard Home 支持的路由器不支持。在这种情况下，可以提供有效的 cookie 作为替代。如果路由器通过自身的身份验证保护 AdGuard 实例，来自已认证请求的 cookie 可能使同步成功。

• 已在带有 AdGuard Home 的 GL.Inet 路由器上成功测试。

[!NOTE] 注意：由于 cookie 的有效期较短，此方法可能仅适用于一次性同步。

Integrate adguardhome-sync with GL.iNet Routers

参见 wiki

Run Linux/Mac

export LOG_LEVEL=info
export ORIGIN_URL=https://192.168.1.2:3000
export ORIGIN_USERNAME=username
export ORIGIN_PASSWORD=password
# export ORIGIN_COOKIE=源 Cookie 名称=CCCOOOKKKIIIEEE
export REPLICA1_URL=http://192.168.1.3
export REPLICA1_USERNAME=username
export REPLICA1_PASSWORD=password
# export REPLICA_COOKIE=副本 Cookie 名称=CCCOOOKKKIIIEEE

# 运行一次
adguardhome-sync run

通过 Systemd 作为 Linux 服务运行

[!NOTE] 已在 Ubuntu Linux 24.04 上验证

假设你已将 adguardhome-sync 二进制文件下载到 /opt/adguardhome-sync。

创建 systemd 服务文件 /opt/adguardhome-sync/adguardhome-sync.service：

[Unit]
Description = AdGuardHome Sync
After = network.target

[Service]
ExecStart = /opt/adguardhome-sync/adguardhome-sync --config /opt/adguardhome-sync/adguardhome-sync.yaml run

[Install]
WantedBy = multi-user.target

创建配置文件 /opt/adguardhome-sync/adguardhome-sync.yaml，详情请参见下方的配置文件部分。

安装并启用服务：

sudo cp /opt/adguardhome-sync/adguardhome-sync.service /etc/systemd/system/

sudo systemctl enable adguardhome-sync.service

sudo systemctl start adguardhome-sync.service

然后你可以检查状态：

sudo systemctl status adguardhome-sync.service

如果配置中已启用 Web UI（默认端口为 8080），也可以通过 http:// :8080 检查状态。

初始实例的设置

如果通过配置autoSetup启用，新的AdGuardHome副本实例可以自动安装。在自动安装过程中，管理界面将在运行时监听端口3000。

要跳过自动设置

在 Linux/Mac 上运行

export LOG_LEVEL=info
export ORIGIN_URL=https://192.168.1.2:3000
export ORIGIN_USERNAME=username
export ORIGIN_PASSWORD=password
# export ORIGIN_COOKIE=Origin-Cookie-Name=CCCOOOKKKIIIEEE
export REPLICA1_URL=http://192.168.1.3
export REPLICA1_USERNAME=username
export REPLICA1_PASSWORD=password
# export REPLICA_COOKIE=Replica-Cookie-Name=CCCOOOKKKIIIEEE

# 运行一次
adguardhome-sync run

# 作为守护进程运行
adguardhome-sync run --cron "0 */2 * * *"

通过 Systemd 作为 Linux 服务运行

[!NOTE] 已在 Ubuntu Linux 24.04 上验证

假设您已将 adguardhome-sync 二进制文件下载到 /opt/adguardhome-sync。

创建 systemd 服务文件 /opt/adguardhome-sync/adguardhome-sync.service：

[Unit]
Description = AdGuardHome Sync
After = network.target

[Service]
ExecStart = /opt/adguardhome-sync/adguardhome-sync --config /opt/adguardhome-sync/adguardhome-sync.yaml run

[Install]
WantedBy = multi-user.target

创建配置文件 /opt/adguardhome-sync/adguardhome-sync.yaml，请参考下面的配置文件部分了解详情。

安装并启用服务：

sudo cp /opt/adguardhome-sync/adguardhome-sync.service /etc/systemd/system/

sudo systemctl enable adguardhome-sync.service

sudo systemctl start adguardhome-sync.service

然后您可以检查状态：

sudo systemctl status adguardhome-sync.service

如果配置中已启用 Web UI（默认端口为 8080），也可以通过 http:// :8080 检查状态。

Unraid

[!IMPORTANT] 免责声明：存在该应用的 Unraid 模板。本项目不管理此模板。此外，由于我不了解 Unraid，无法为 Unraid 模板提供任何支持。

[!NOTE] 在 Unraid 中运行 Docker 容器时，请删除不需要的环境变量。如果未使用 replica2，这可能会导致同步错误。

Home Assistant AdGuard Home 插件用户

要与使用 https://github.com/hassio-addons/addon-adguard-home 的 Home Assistant 实例启用同步，你需要在“网络”标题下启用已禁用的端口。

然后为 Web 界面设置你选择的端口。

不要忘记保存并重启插件。

根据你的设置，你可能还需要为插件禁用 SSL。

Home Assistant 副本所需的用户名:密码是你用于登录实例的凭据，但建议创建一个仅本地使用且权限最小的新用户。

此方法的所有功劳归于 https://github.com/brunty，他在其博客上发布了更详细的说明。

日志级别

日志级别可通过环境变量 LOG_LEVEL 进行设置。

支持以下日志级别（默认：info）：

• debug
• info
• warn
• error

日志格式

默认日志格式为 console。 可通过设置环境变量 LOG_FORMAT=json 将其更改为 json。

API 文档

概述

API 提供用于同步管理、状态监控、指标收集和日志检索的端点。

基础 URL

https://localhost: (如果启用 TLS)

认证

• 类型：基本认证（可选）
• 用户名：通过 API.Username 配置
• 密码：通过 API.Password 配置
• 注意：认证适用于所有端点，除了 /healthz 和根路径 /

端点

健康检查

GET /healthz | HEAD /healthz

用于验证 API 和副本状态的健康检查端点。

• 认证：不需要
• 响应：
  • 200 OK - API 和所有副本均健康
  • 503 Service Unavailable - 源实例或任何副本未处于“success”状态

curl http://localhost:5000/healthz

同步

POST /api/v1/sync

触发所有已配置实例的手动同步。

• 认证：需要（如果已配置）
• 响应：200 OK - 同步已成功启动

curl -X POST http://localhost:5000/api/v1/sync

状态

GET /api/v1/status

获取当前同步和副本状态。

• 认证：需要（如果已配置）
• 响应（200 OK）：

{
"syncRunning": false,
"origin": {
"host": "origin.example.com",
"url": "http://origin.example.com:80",
"status": "success",
"error": "",
"protection_enabled": true
},
"replicas": [
{
"host": "replica1.example.com",
"url": "http://replica1.example.com:80",
"status": "success",
"error": "",
"protection_enabled": true
}
]
}

日志

GET /api/v1/logs

检索应用日志。

• 认证：需要（如果已配置）
• 响应（200 OK）：纯文本日志

curl http://localhost:5000/api/v1/logs

POST /api/v1/clear-logs

清除所有应用日志。

• 认证：需要（如果已配置）
• 响应：200 OK - 日志已成功清除

curl -X POST http://localhost:5000/api/v1/clear-logs

指标

GET /metrics

Prometheus 兼容的指标端点。

• 认证：需要（如果已配置）
• 可用性：仅在 API.Metrics.Enabled 设为 true 时可用
• 响应（200 OK）：Prometheus 格式指标

curl http://localhost:5000/metrics

Web 仪表板

GET /

提供包含 DNS 统计信息、同步状态和指标（如果启用）的 Web 仪表板。

• 认证：需要（如果已配置）
• 响应（200 OK）：HTML 仪表板

视频教程

• Como replicar la configuración de tu servidor DNS Adguard automáticamente - Tu servidor Part #12（西班牙语）作者 https://github.com/jcastro