AdGuard Home ECS增强版Docker镜像

镜像概述

本镜像基于AdGuard Home 0.107.67稳定版本构建，集成定制补丁以增强EDNS Client Subnet（ECS）支持。通过应用ecs.patch，实现从DNS请求中提取ECS数据并将其作为客户端IP处理，替代传统源IP识别方式，适用于需要基于ECS信息进行客户端识别的DNS过滤、广告拦截及网络管理场景。

核心功能与特性

• 基于*稳定版本**：构建自AdGuard Home release-v0.107.67分支，确保基础功能兼容性与稳定性
• ECS支持增强：通过补丁实现EDNS Client Subnet（ECS）数据提取，可将ECS作为客户端IP处理，优化NAT环境下的客户端识别
• 轻量级基础：运行阶段基于Alpine Linux，镜像体积小，资源占用低
• 完整功能保留：包含AdGuard Home标准功能集，如DNS服务器、广告/跟踪器拦截、家长控制、DNS缓存、查询日志与统计分析
• 持久化存储：通过卷挂载实现配置文件（conf）与工作数据（work）的持久化，确保配置不丢失

使用场景与适用范围

• NAT网络环境：在多客户端共享出口IP的网络（如家庭路由、企业内网）中，通过ECS数据准确识别不同客户端
• 地理位置感知解析：利用ECS信息提供符合客户端实际位置的DNS解析结果
• 精细化策略管理：基于ECS数据为不同客户端配置差异化过滤规则、屏蔽列表及访问控制策略
• 标准AdGuard Home应用：适用于家庭、小型办公网络的广告拦截、***软件防护、DNS加密（DoH/DoT）等场景

详细使用方法

前置要求

• Docker Engine 19.03及以上版本
• 宿主机需开放镜像所需端口（避免端口冲突，如53端口需确保未被其他DNS服务占用）

Docker Run快速部署

docker run -d \
  --name adguardhome-ecs \
  --restart unless-stopped \
  -p 53:53/tcp -p 53:53/udp \
  -p 67:67/udp -p 68:68/udp \  # 可选，DHCP功能端口
  -p 80:80/tcp -p 443:443/tcp \  # Web界面及DoH端口
  -p 853:853/tcp \  # DoT端口
  -p 3000:3000/tcp \  # 初始配置界面端口
  -v /path/to/conf:/opt/adguardhome/conf \  # 宿主机配置目录
  -v /path/to/work:/opt/adguardhome/work \  # 宿主机工作数据目录
  adguardhome-ecs:0.107.67

Docker Compose配置示例

创建docker-compose.yml文件：

version: '3.8'

services:
  adguardhome-ecs:
    image: adguardhome-ecs:0.107.67
    container_name: adguardhome-ecs
    restart: unless-stopped
    ports:
      - "53:53/tcp"       # DNS TCP端口
      - "53:53/udp"       # DNS UDP端口
      - "67:67/udp"       # DHCP服务器端口（可选）
      - "68:68/udp"       # DHCP客户端端口（可选）
      - "80:80/tcp"       # HTTP端口（Web界面/DoH）
      - "443:443/tcp"     # HTTPS端口（加密Web界面/DoH）
      - "853:853/tcp"     # DNS over TLS (DoT)端口
      - "3000:3000/tcp"   # 初始配置界面端口
    volumes:
      - ./adguardhome/conf:/opt/adguardhome/conf  # 配置文件存储
      - ./adguardhome/work:/opt/adguardhome/work  # 工作数据存储
    network_mode: "bridge"  # 或使用host模式以获取真实源IP（需谨慎配置端口）

端口说明

卷说明

配置说明

1. 首次访问：容器启动后，通过http://<宿主机IP>:3000访问初始配置界面，完成管理员账户设置、网络接口监听配置等基础设置。
2. ECS功能：补丁已默认集成，无需额外配置。系统会自动从DNS请求中提取ECS选项，当ECS数据有效时，将其作为客户端IP用于规则匹配与日志记录。
3. 配置文件修改：核心配置文件为/opt/adguardhome/conf/AdGuardHome.yaml，通过宿主机挂载目录可直接编辑，修改后需重启容器使配置生效：docker restart adguardhome-ecs。

构建说明（可选）

如需自行构建镜像，执行以下步骤：

1. 将Dockerfile与ecs.patch文件置于同一目录
2. 执行构建命令：

   docker build -t adguardhome-ecs:0.107.67 .
   

3. 构建完成后即可使用上述部署方法启动容器