lkpot/adguardhome

镜像概述和主要用途

本镜像为AdGuard Home的Docker化实现，从源代码构建，核心特性是支持以非root用户身份运行，增强容器安全性。AdGuard Home是一款网络广告拦截与DNS过滤工具，可用于家庭或企业网络中过滤广告、保护隐私和增强网络安全。

https://github.com/lkpot/adguardhome-docker

核心功能和特性

• 非root运行：支持以普通用户身份运行容器，降低权限风险
• 源代码构建：基于官方源代码构建，确保功能完整性和最新性
• 权限控制：通过Linux capabilities机制，仅添加必要的CAP_NET_BIND_SERVICE权限
• 数据持久化：支持通过卷挂载保存配置数据，确保配置不丢失
• 安全强化：默认删除所有不必要的Linux capabilities，最小化***面

使用场景和适用范围

• 家庭网络广告过滤与DNS管理
• 企业内部网络安全防护
• 对容器安全性有较高要求的环境
• 需要长期稳定运行AdGuard Home的场景

使用方法和配置说明

前提准备

创建AdGuard Home专用用户

首先创建一个系统用户，用于映射到容器内部：

bash
useradd -M --system -s /usr/sbin/nologin adguardhome

首次启动与初始化配置

AdGuard Home首次启动需要root权限以完成初始化设置：

bash
docker run --rm --cap-drop ALL --cap-add CAP_NET_BIND_SERVICE \
           -v ./etc-adguardhome:/etc/adguardhome --user 0:0 \
           lkpot/adguardhome

容器启动后，通过 http://<服务器地址>:3000 访问Web界面完成初始配置。

配置完成后，修改数据目录所有权为之前创建的adguardhome用户：

bash
chown -R "$(id -u adguardhome):$(id -g adguardhome)" etc-adguardhome

正常启动容器

以非root用户身份启动容器：

bash
docker run --rm --cap-drop ALL --cap-add CAP_NET_BIND_SERVICE \
           -v ./etc-adguardhome:/etc/adguardhome --user "$(id -u adguardhome):$(id -g adguardhome)" \
           lkpot/adguardhome

使用docker-compose部署

创建环境变量文件

为简化用户ID和组ID的映射，创建.env文件：

bash
echo -e "UID=$(id -u adguardhome)\nGID=$(id -g adguardhome)" > .env

docker-compose.yaml配置

yaml
services:
  adguard:
    container_name: adguardhome
    image: lkpot/adguardhome
    cap_drop:
      - All
    cap_add:
      - CAP_NET_BIND_SERVICE
    expose:
      - 53:53/tcp
      - 53:53/udp
      - 80:80/tcp
      - 443:443/tcp
    user: ${UID}:${GID}
    volumes:
      - ./etc-adguardhome:/etc/adguardhome
    restart: unless-stopped

启动服务：

bash
docker-compose up -d

注意事项

• 首次启动必须使用root用户(0:0)以完成初始化
• 数据目录权限必须正确设置为adguardhome用户所有，否则容器可能无法正常读写配置
• 如需自定义端口映射，可在docker run命令或docker-compose配置中调整expose部分
• 容器重启策略建议设置为unless-stopped，确保服务持续可用