spx01/blocky

Blocky Docker镜像文档

https://github.com/0xERR0R/blocky

镜像概述和主要用途

Blocky 是一款基于 Go 语言开发的轻量级 DNS 代理与广告拦截工具，专为本地网络设计。它整合 DNS 代理、广告/软件拦截、自定义 DNS 解析与隐私保护功能，通过优化 DNS 查询流程提升网络性能，同时支持多种现代 DNS 协议以增强网络安全性与隐私性。主要用途包括：本地网络广告与内容过滤、DNS 解析加速、自定义域名解析规则管理、以及通过加密 DNS 协议（如 DoH/DoT）保护用户隐私。

核心功能和特性

广告与***内容拦截

• 多维度拦截能力：支持通过外部列表（广告、***软件域名）拦截 DNS 查询，同时提供白名单机制
• 客户端分组管理：可按客户端分组（如儿童设备、智能家居设备）定义独立的黑白名单规则
• 动态规则更新：定期自动重载外部黑白名单，无需重启服务
• 深度解析拦截：支持拦截请求域名、响应 CNAME（深度 CNAME 检查）及响应 IP 地址（基于 IP 列表）

高级 DNS 配置

• 自定义域名解析：为特定域名配置自定义 DNS 解析结果
• 条件转发：基于域名或客户端将 DNS 查询转发至指定外部 DNS 服务器

性能优化

• 智能缓存机制：可配置 DNS 查询结果缓存，提升解析速度并减少外部查询量
• 预取与缓存：自动预取并缓存常用域名查询结果
• 并行解析：同时使用多个外部 DNS 解析器，加速查询过程
• 轻量设计：低内存占用，适合资源受限设备（如树莓派）

多协议支持

• 基础协议：支持 UDP/TCP 协议的传统 DNS
• 现代加密协议：支持 DNS over HTTPS (DoH) 与 DNS over TLS (DoT)

安全与隐私保护

• DNS 扩展支持：兼容 DNSSEC、eDNS 等现代 DNS 扩展
• 透明规则管理：阻止列表完全可配置，无隐藏过滤逻辑
• DoH 服务端：内置 DoH 端点，支持客户端通过 DoH 协议查询
• 上游 resolver 随机化：随机选择配置中的上游 DNS 服务器，分散 DNS 流量以增强隐私
• 零数据收集：不收集任何用户数据、遥测信息或统计数据

集成能力

• Prometheus 指标：暴露 Prometheus 监控指标
• Grafana 仪表盘：提供预配置的 Grafana 仪表盘模板
• 查询日志：按日/按客户端生成 CSV 格式 DNS 查询日志，便于分析
• CLI 统计报告：支持通过命令行生成 DNS 统计报告
• REST API：提供多种 REST API 端点，支持管理与监控
• CLI 工具：内置命令行工具，支持配置验证、统计查询等操作

简化配置与部署

• 单一配置文件：采用 YAML 格式配置文件，结构清晰，易于维护与备份
• 无状态设计：无需数据库或临时文件，部署简单
• 多架构 Docker 镜像：提供多架构 Docker 镜像，支持 x86-64 与 ARM 架构（如树莓派）
• K8s 支持：社区维护的 Helm Chart，支持 Kubernetes 部署

使用场景和适用范围

家庭网络广告拦截

适用于家庭网络环境，拦截各类广告、跟踪器域名，提升浏览体验，减少带宽消耗。

企业网络 DNS 管理

可作为企业内网 DNS 服务器，实现基于客户端分组的域名访问控制（如限制特定设备访问娱乐网站）、***软件域名拦截及自定义域名解析。

物联网设备安全过滤

为智能家居、物联网设备提供 DNS 级安全防护，阻止设备连接***服务器，保护设备与家庭网络安全。

隐私敏感环境

适合对 DNS 隐私有较高要求的场景，通过 DoH/DoT 协议加密 DNS 流量，结合上游 resolver 随机化，减少 DNS 数据泄露风险。

资源受限设备部署

轻量设计使其可部署于树莓派、NAS 等资源受限设备，作为家庭网关的 DNS 服务组件。

详细使用方法和配置说明

前置要求

• Docker 环境（19.03+）
• 基础网络知识（DNS 协议、端口映射等）
• （可选）自定义 YAML 配置文件（如需个性化配置）

配置文件说明

Blocky 采用 YAML 格式配置文件，默认路径为 /app/config.yml。以下为基础配置示例：

yaml
# 基础设置
port: 53  # DNS 服务端口（UDP/TCP）
httpPort: 4000  # HTTP 服务端口（API、Prometheus 指标等）
logLevel: info  # 日志级别：debug, info, warn, error

# 上游 DNS 服务器配置
upstream:
  default:
    - https://dns.cloudflare.com/dns-query  # DoH 上游
    - tls://1.1.1.1  # DoT 上游
    - 8.8.8.8:53  # UDP 上游
  # 条件转发示例（可选）
  conditional:
    - domain: "home.arpa"
      upstream:
        - 192.168.1.1:53  # 本地路由器 DNS

# 阻止规则配置
blocking:
  # 阻止列表（广告、恶意软件等）
  lists:
    - https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
    - https://mirror1.malwaredomains.com/files/justdomains
  # 白名单（覆盖阻止列表）
  whitelist:
    - "example.com"
    - "*.trusted.com"
  # 阻止模式：null（返回 NXDOMAIN）、zeroIP（返回 0.0.0.0）、customIP（返回自定义 IP）
  blockType: "zeroIP"
  # 定期更新阻止列表（单位：分钟）
  updateInterval: 4320  # 72 小时

# 客户端分组配置（可选）
clients:
  # 分组定义
  groups:
    kids:
      # 仅对 kids 组应用的额外阻止列表
      blockLists:
        - https://raw.githubusercontent.com/rentec/pihole-blocklists/master/blocklists/youtube
    iot:
      # iot 组的白名单
      whitelist:
        - "*.iot-service.com"
  # 客户端匹配规则（IP 或 CIDR）
  clientGroups:
    - clients: ["192.168.1.100", "192.168.1.101/30"]
      groups: ["kids"]
    - clients: ["192.168.1.200-205"]
      groups: ["iot"]

# 缓存配置
cache:
  # 缓存大小（条目数）
  size: 10000
  # 默认 TTL（秒），优先级低于 DNS 响应 TTL
  ttl: 300
  # 最小 TTL（秒），覆盖响应中过小的 TTL
  minTTL: 60
  # 最大 TTL（秒），覆盖响应中过大的 TTL
  maxTTL: 86400

# 日志配置
logging:
  # 启用查询日志
  queryLog: true
  # 查询日志路径（Docker 部署时需挂载对应目录）
  queryLogPath: "/logs/query.log"
  # CSV 日志字段：timestamp, client, query, type, responseCode, duration, upstream, answer
  queryLogFormat: "csv"

Docker 部署示例

1. 使用 docker run 部署

bash
docker run -d \
  --name blocky \
  --restart unless-stopped \
  -p 53:53/udp \
  -p 53:53/tcp \
  -p 4000:4000/tcp \
  -v /path/to/blocky/config.yml:/app/config.yml \
  -v /path/to/blocky/logs:/logs \
  --env TZ=Asia/Shanghai \
  0xerr0r/blocky:latest

参数说明：

• -p 53:53/udp/-p 53:53/tcp：映射 DNS 服务端口（UDP/TCP 均需映射）
• -p 4000:4000/tcp：映射 HTTP 服务端口（API、Prometheus 指标）
• -v /path/to/blocky/config.yml:/app/config.yml：挂载自定义配置文件
• -v /path/to/blocky/logs:/logs：挂载日志目录（如启用 queryLog）
• --env TZ=Asia/Shanghai：设置时区，确保日志时间正确

2. 使用 docker-compose 部署

创建 docker-compose.yml 文件：

yaml
version: "3.8"

services:
  blocky:
    image: 0xerr0r/blocky:latest
    container_name: blocky
    restart: unless-stopped
    ports:
      - "53:53/udp"
      - "53:53/tcp"
      - "4000:4000/tcp"
    volumes:
      - ./config.yml:/app/config.yml:ro
      - ./logs:/logs
    environment:
      - TZ=Asia/Shanghai
    # 可选：限制资源使用（适用于树莓派等设备）
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 256M

启动服务：

bash
docker-compose up -d

启动与验证

1. 检查服务状态：

   bash
   docker logs blocky  # 查看启动日志，确认无错误
   docker ps | grep blocky  # 确认容器运行中
   

2. 测试 DNS 解析： 使用 dig 或 nslookup 测试 DNS 解析（替换 127.0.0.1 为 Blocky 服务器 IP）：

   bash
   dig @127.0.0.1 example.com  # 测试正常域名解析
   dig @127.0.0.1 ads.example.com  # 测试被阻止域名（应返回 0.0.0.0 或 NXDOMAIN）
   

3. 访问 API 与监控：

   • API 端点：http://<blocky-ip>:4000/api/v1/health（健康检查）
   • Prometheus 指标：http://<blocky-ip>:4000/metrics

配置参数详解

基础配置 (config.yml 核心参数)

上游 DNS 配置 (upstream)

阻止规则配置 (blocking)

客户端分组配置 (clients)

缓存配置 (cache)

日志配置 (logging)

环境变量

Blocky 支持通过环境变量覆盖部分配置参数（优先级：环境变量 > 配置文件 > 默认值）：