sq4ind/adguardhome-lancache-dns

AdGuardHome LanCache DNS 同步器

一个生产就绪的同步工具，用于更新AdGuard Home中的DNS重写规则，将特定服务指向您的LanCache服务器。专为在局域网中运行本地DNS服务器（AdGuard Home）且希望利用LanCache优势而无需运行额外DNS服务的用户设计。

核心功能

• ✅ 从cache-domains仓库自动同步DNS重写规则
• ✅ 支持可配置工作池的并发文件下载
• ✅ 带进度报告的批处理功能
• ✅ 可选缓存功能，用于快速从故障中恢复
• ✅ 适用于编排和健康检查的正确退出码
• ✅ 全面的错误处理和日志记录
• ✅ 支持单个服务或所有服务
• ✅ 线程安全操作
• ✅ 可配置的重试策略

安装与配置

要求

• 系统已安装Docker
• 局域网内已存在AdGuard Home设置
• AdGuard Home API访问权限

快速开始

bash
docker run --name adguard-lancache-dns -d \
  -e ADGUARD_USERNAME='admin' \
  -e ADGUARD_PASSWORD='password' \
  -e LANCACHE_SERVER='192.168.1.100' \
  -e ADGUARD_API='http://adguard.home:8080' \
  -e CRON_SCHEDULE='0 0 * * *' \
  -e ALL_SERVICES='true' \
  adguardhome-lancache-dns

环境变量

注意：必须指定ALL_SERVICES=true或SERVICE_NAMES，不能两者都不指定。

可用服务

该工具支持https://github.com/uklans/cache-domains%E4%BB%93%E5%BA%93%E4%B8%AD%E7%9A%84%E6%89%80%E6%9C%89%E6%9C%8D%E5%8A%A1%EF%BC%8C%E5%8C%85%E6%8B%AC%EF%BC%9A

arenanet, blizzard, bsg, cityofheroes, cod, daybreak, epicgames, frontier, neverwinter, nexusmods, nintendo, origin, pathofexile, renegadex, riot, rockstar, sony, square, steam, teso, test, uplay, warframe, wargaming, wsus, xboxlive

Docker Compose示例

yaml
version: '3.8'

services:
  adguard-lancache-dns:
    image: adguardhome-lancache-dns:latest
    container_name: adguard-lancache-dns
    restart: unless-stopped
    environment:
      - ADGUARD_USERNAME=admin
      - ADGUARD_PASSWORD=your_password
      - LANCACHE_SERVER=192.168.1.100
      - ADGUARD_API=http://adguard.home:8080
      - CRON_SCHEDULE=0 0 * * *
      - ALL_SERVICES=true
      - LOG_LEVEL=INFO
      - MAX_WORKERS=3
      - BATCH_SIZE=100
      - CACHE_FILE=/var/cache/dns_rewrites.json
    volumes:
      - dns_cache:/var/cache

volumes:
  dns_cache:

工作原理

1. 获取服务元数据：从cache-domains仓库检索服务列表
2. 下载域名列表：使用可配置的工作池并发下载所选服务的域名列表
3. 处理与缓存：将域名转换为AdGuard Home重写格式并可选地缓存结果
4. 更新DNS重写规则：批处理更新AdGuard Home（跟踪添加/更新/跳过的规则）
5. 报告结果：记录添加、更新和跳过的重写规则摘要

并发控制

• MAX_WORKERS：控制并发下载数量（默认：3）
  • 较低值：网络负载较小，下载速度较慢
  • 较高值：下载速度较快，网络负载较大
• BATCH_SIZE：进度日志频率（默认：100条重写规则）
  • 避免日志刷屏，同时在大型更新时显示进度

缓存

启用缓存以加快故障恢复速度：

bash
-e CACHE_FILE=/var/cache/dns_rewrites.json

启用后，DNS重写规则将在下载后保存。适用于：

• 临时故障后的快速重新运行
• 测试AdGuard Home连接问题
• 开发过程中避免重复下载

高级用法

性能调优

对于DNS解析有问题的较慢网络：

bash
docker run ... \
  -e MAX_WORKERS=2 \
  -e LOG_LEVEL=DEBUG \
  adguardhome-lancache-dns

对于网络速度快且连接稳定的环境：

bash
docker run ... \
  -e MAX_WORKERS=10 \
  -e BATCH_SIZE=500 \
  adguardhome-lancache-dns

健康检查

在Docker Compose中添加健康检查：

yaml
healthcheck:
  test: [ "CMD", "python", "/app/UpdateAdGuardDNSRewrites.py" ]
  interval: 6h
  timeout: 30s
  retries: 2
  start_period: 30s

Kubernetes部署

yaml
apiVersion: batch/v1
kind: CronJob
metadata:
  name: adguard-lancache-dns
spec:
  schedule: "0 0 * * *"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: sync
            image: adguardhome-lancache-dns:latest
            env:
            - name: ADGUARD_USERNAME
              valueFrom:
                secretKeyRef:
                  name: adguard-credentials
                  key: username
            - name: ADGUARD_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: adguard-credentials
                  key: password
            - name: LANCACHE_SERVER
              value: "192.168.1.100"
            - name: ADGUARD_API
              value: "http://adguard.home:8080"
            - name: ALL_SERVICES
              value: "true"
          restartPolicy: OnFailure

退出码

• 0：执行成功
• 1：配置错误或运行时故障

故障排除

DNS解析错误

如果看到NameResolutionError消息：

1. 验证容器DNS配置：

   bash
   docker run --dns=8.8.8.8 ... adguardhome-lancache-dns
   

2. 检查AdGuard Home DNS设置：

   bash
   docker exec adguard-lancache-dns nslookup raw.githubusercontent.com
   

3. 通过查看日志增加重试尝试：

   bash
   docker logs -f adguard-lancache-dns
   

连接失败

启用调试日志：

bash
docker run ... -e LOG_LEVEL=DEBUG adguardhome-lancache-dns

同步缓慢

调整并发设置：

bash
docker run ... -e MAX_WORKERS=5 adguardhome-lancache-dns

贡献

我们欢迎贡献！请：

1. Fork仓库
2. 创建功能分支：git checkout -b feature/improvement
3. 提交更改：git commit -am 'Add improvement'
4. 推送到分支：git push origin feature/improvement
5. 提交Pull Request

许可

本项目基于MIT许可。您可以自由Fork、修改和以任何方式使用。

支持

如有问题、疑问或建议，请在GitHub上提交issue。