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

AdGuardHome 同步

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

常见问题与弃用说明

有关常见问题和弃用说明，请查看 wiki。

当前同步功能

• 常规设置
• 过滤器
• 重写规则
• 服务
• 客户端
• DNS 配置
• DHCP 配置
• 主题

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

初始实例设置

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

若要跳过自动设置

安装

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

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

Brew 安装

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

# 安装
brew install --cask adguardhome-sync

前提条件

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

通过环境变量配置

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

YAML 配置文件

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

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

用户名/密码与 Cookie

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

• 已在带有 AdGuard Home 的 GL.Inet 路由器上成功测试。
• 注意：由于 Cookie 的有效期较短，此方法可能仅适用于一次性同步

将 adguardhome-sync 与 GL.iNet 路由器集成

参见 wiki

在 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

通过 Systemd 作为 Linux 服务运行

已在 Ubuntu Linux 24.04 上验证

已在 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），也可以通过 [***] :8080 检查状态

前提条件

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

在 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 检查状态

在 Windows 上运行

@ECHO OFF
@TITLE AdGuardHome-Sync

REM set LOG_LEVEL=debug
set LOG_LEVEL=info
REM set LOG_LEVEL=warn
REM set LOG_LEVEL=error

set ORIGIN_URL=http://192.168.1.2:3000
set ORIGIN_USERNAME=username
set ORIGIN_PASSWORD=password
# set ORIGIN_COOKIE=Origin-Cookie-Name=CCCOOOKKKIIIEEE

set REPLICA1_URL=http://192.168.2.2:3000
set REPLICA1_USERNAME=username
set REPLICA1_PASSWORD=password
# set REPLICA1_COOKIE=Replica-Cookie-Name=CCCOOOKKKIIIEEE

set FEATURES_DHCP_SERVER_CONFIG=false
set FEATURES_DHCP_STATIC_LEASES=false

# 运行一次
adguardhome-sync run

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

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: (if TLS enabled)

身份验证

• 类型：基本身份验证（可选）
• 用户名：通过API.Username配置
• 密码：通过API.Password配置

[!NOTE] 身份验证适用于除/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