Blocky v0.33.0 介绍与选型指南

目标：介绍开源 DNS 广告屏蔽代理 Blocky 的定位、架构、功能与选型依据，并与 Pi-hole、AdGuard Home、Technitium DNS Server 做量化对比，帮助读者判断「自建 DNS 屏蔽网关」场景下该选谁。文中版本、星数、发布时间均于 2026-10-20 联网实查官方渠道；快速开始一节的命令与回显已在 Ubuntu 22.04.4 LTS（x86_64）实测通过。

一、环境信息

本文取证与实测环境如下：

• 操作系统：Ubuntu 22.04.4 LTS（Jammy），内核 6.8.0-138-generic，架构 x86_64
• 软件版本：Blocky v0.33.0（官方二进制，构建时间 20260630-080230）
• 取证渠道与查询日期：
  • 版本与发布信息：GitHub Releases（github.com/0xERR0R/blocky/releases/latest），查询日期 2026-10-20
  • 社区活跃度：shields.io 实时徽章（内查 GitHub API），查询日期 2026-10-20
  • 安装与配置语法：官方文档站 0xerr0r.github.io/blocky/latest/（Installation、Configuration 章节）
  • 安全通告：pkg.go.dev 版本页标注的 GO-2026-5745
• 实验监听：DNS 绑定 127.0.0.11:53（实验宿主机 53 端口已被 systemd-resolved 存根 127.0.0.53 与其他 DNS 服务占用，故绑定空闲回环地址，过程见第五章）
• DNS 验证工具：dig（bind9-dnsutils 9.18.39）

二、软件概述

本章回答「Blocky 是什么、解决什么问题」。Blocky 是一个用 Go 语言编写的本地网络 DNS 代理与广告/追踪域名屏蔽器，GitHub 仓库为 0xERR0R/blocky，许可证 Apache-2.0（官方发布包内 LICENSE 文件为 Apache License Version 2.0，实测确认）。它的核心思路是：把局域网客户端的 DNS 查询先收下来，先按黑白名单决定「放行还是拦截」，放行的查询再按策略转发给上游加密 DNS（普通 UDP、DoT、DoH、DoQ、DNS Stamp 均支持），并把结果缓存起来。

💡 技术拓展：「DNS 屏蔽（blocking）」的拦截响应方式不止一种，各方案取舍如下——

拦截方式	原理	适用场景
zeroIp	被屏蔽域名返回 A/AAAA 记录 0.0.0.0 / ::	默认方式，客户端立即失败、日志干净
nxDomain	返回 NXDOMAIN（域名不存在）	更符合 DNS 语义；部分客户端会重试其他后缀
refused	返回 REFUSED 应答	不推荐：存根解析器常视其为服务器故障而回退到备用 DNS，反而绕过屏蔽
自定义 IP	返回指定 IPv4/IPv6（可指向「已屏蔽」提示页）	需要向用户展示拦截提示页的场景

Blocky 通过 blocking.blockType 一项即可在 zeroIp / nxDomain / refused / 自定义 IP 之间切换，官方默认 zeroIp，本系列实测亦采用 zeroIp 与 nxDomain 两种方式验证（见第五章）。

项目基本盘（2026-10-20 实查）：

对比表解读：Blocky 是典型的「Unix 哲学」项目——不带 Web 管理界面，一切配置进 YAML，一切管理走 CLI 与 REST API；资源占用极低（实测 systemctl status 显示服务进程常驻内存 8.1M），适合塞进路由器旁的小主机、NAS 或已有运维体系的机房。

版本节奏与安全通告：从公开 Release 记录看，Blocky 处于活跃迭代状态，v0.31.0（2026-06-04）引入了 DNSSEC 验证能力，但 pkg.go.dev 版本页对该版本标注了安全通告 GO-2026-5745（DNSSEC 验证绕过与验证缓存作用域污染），修复已在后续版本完成。结论：生产部署请直接选用查询日最新稳定版 v0.33.0，不要停留在 v0.31.0 及更早版本。

三、核心架构

本章按「一次 DNS 查询的旅程」拆解 Blocky 的处理链路，帮助理解后续配置参数为什么那样组织。

Blocky 以**解析器链（resolver chain）**组织请求处理，一个查询从监听端口进来后依次经过：

1. 监听层（listeners）：同一进程内可同时开启四类监听——DNS（UDP+TCP 53）、DoT（TLS 853）、HTTP（REST API / Prometheus 指标 / pprof）、HTTPS（DoH 服务端 + 上述 HTTP 能力）。启动日志会逐项打印实际绑定地址（实测回显见第五章）。
2. 入口处理：按客户端来源（IP / CIDR / 主机名通配）匹配 clientGroupsBlock 分组，决定该客户端套用哪些黑名单组；随后依次通过限速（rateLimit）、查询类型过滤（filtering）、FQDN 强制（fqdnOnly）、DNS 反弹防护（rebindingProtection）、特殊用途域名拦截（specialUseDomains）等闸门。
3. 屏蔽判定：命中黑名单（denylist，支持通配符与正则）且未命中白名单（allowlist，优先级高于黑名单）的域名按 blockType 返回拦截应答；白名单与黑名单都未命中的查询进入解析流程。
4. 解析层：先查本机数据源——customDNS 自定义记录、hostsFile（/etc/hosts 或内联 hosts）、条件转发域（conditional）；未命中则查缓存（含负缓存与可选的预取 prefetching）；仍未命中才转发上游。
5. 上游转发：按 upstreams.strategy 从分组上游中选路——parallel_best（默认，同时向多个上游发起、取最优应答）、strict（顺序重试）、random（随机）。上游支持普通 UDP/TCP、DoT（tcp-tls:）、DoH（https://）、DoQ（quic:）与 DNS Stamp（sdns://）五种形态。
6. 响应侧：写查询日志（queryLog：控制台 / CSV / MySQL / PostgreSQL / SQLite / dnstap）、刷新统计（statistics 内存统计 24h 窗口 / Prometheus 指标）、回写缓存。

一条实测的查询日志（log.level: info 时控制台输出，逐行照抄）能直观看到上述链路的落点：

[2026-10-20 17:19:06]  INFO queryLog: query resolved answer=A (0.0.0.0) client_ip=127.0.0.1 client_names=127.0.0.1 instance=ops question_name=ads.example.com. question_type=A response_code=NOERROR response_reason=BLOCKED (ads: ads.example.com) response_type=BLOCKED

response_reason=BLOCKED (ads: ads.example.com) 说明了三层信息：响应类型是拦截、命中的分组是 ads、命中的条目是 ads.example.com。

💡 技术拓展：上游选路策略是 DNS 代理的常见多选概念——

策略	原理	取舍
parallel_best	并发询问全部（或多个）上游，取最先返回且有效的应答	延迟最低，出站查询量放大
strict	按配置顺序逐个尝试，失败/超时才换下一个	流量最省，尾延迟取决于最慢上游
random	每次随机挑一个上游	折中，行为不可预测

Blocky 默认 parallel_best，对延迟敏感的局域网场景合适；上游按次计费或流量敏感时改用 strict。

多实例协同：Blocky 可通过 Redis 同步缓存与屏蔽状态，实现多个 Blocky 实例对外表现一致（redis.address 等参数）；这是它与多数同类工具相比较少被提及、但对高可用部署很实用的一点。

四、功能特性

本章把 v0.33.0 的功能面收敛为一张清单，并标注本系列实测情况（✅ 表示在 Ubuntu 22.04 实测通过，实测明细见本系列部署与配置篇）：

屏蔽与名单

• 黑名单/白名单分组（命名 group），来源支持 http(s) URL、本地文件、YAML 内联文本 ✅
• 条目支持通配符（*.example.com）与正则（/^banners?[_.-]/）✅（官方文档语法，正则形态见官方参考文件）
• 按客户端分组生效：客户端名通配（laptop*）、IP、CIDR（192.168.178.1/24）均可作为分组键
• 白名单优先于黑名单；纯白名单客户端进入「独占放行」模式（仅名单内域名可解析）
• 名单定时生效（schedules + listSchedules，按星期与时段控制某组名单是否启用，如工作时间屏蔽社交站）
• 拦截方式可配：blockType = zeroIp / nxDomain / refused / 自定义 IP ✅（zeroIp 与 nxDomain 均实测）
• 名单加载行为可调：刷新周期（默认 4h）、下载超时与重试、并发数、可选磁盘下载缓存（cachePath）

解析与转发

• 上游协议：UDP/TCP、DoT、DoH、DoQ、DNS Stamp ✅（实验使用 tcp+udp 上游实测；协议前缀语法见官方参考配置）
• 上游选路策略 parallel_best / strict / random，上游超时 timeout（默认 2s）
• 自定义 DNS 记录（customDNS.mapping，含域名重写 rewrite）✅
• 条件转发（conditional.mapping，按域名后缀指定内网 DNS；可配 fallbackUpstream）✅
• 本机 hosts 文件解析（hostsFile，支持 /etc/hosts、URL、内联）✅
• 响应缓存：minTime/maxTime 强制 TTL 上下界、负缓存 cacheTimeNegative、预取 prefetching、容量上限 maxItemsCount ✅（minTime/maxTime 实测）
• 查询类型过滤（filtering.queryTypes，如过滤 AAAA）✅
• DNS 反弹防护（rebindingProtection）、FQDN 强制（fqdnOnly）✅（fqdnOnly 为官方默认开关联项，本文实测环境启用默认值）
• 扩展客户端子网 ECS 透传（ecs.forward / useAsClient）

安全与协议

• DNSSEC 验证（dnssec.validate，v0.31 引入；含信任锚、链深、NSEC3 迭代上限等参数；注意 GO-2026-5745，选 v0.33.0）
• DoT/DoH 服务端（ports.tls/https + 证书），minTlsServeVersion 控制最低 TLS 版本（默认 1.3）
• DoH over HTTP/3（http3.enable）
• 每客户端限速（rateLimit：令牌桶 rate/burst、子网聚合、放行名单）
• 特殊用途域名（SUDN）拦截（specialUseDomains，默认拦截 RFC 6762 附录 G 私有 TLD）

可观测与运维

• Prometheus 指标（blocky_query_total、blocky_cache_entries 等，实测可抓取）✅
• 内存统计接口（statistics.enable，24h 窗口，blocky stats CLI 与 /api/stats 端点）✅
• 查询日志：控制台 / CSV / MySQL / PostgreSQL / SQLite / dnstap，可裁剪字段、按天滚动、保留期清理 ✅（控制台形态实测）
• REST API：/api/blocking/status、/api/blocking/disable、/api/query、/api/stats 等 ✅
• CLI：validate 校验配置、blocking 开关、cache flush、lists refresh、query、stats、healthcheck ✅（全部实测，见《常用 CLI 命令详解》篇）
• Redis 多实例缓存/屏蔽状态同步

工程形态

• 单文件静态二进制（约 34MB），无运行时依赖；实测启动后常驻内存约 8MB
• 配置支持目录形态（--config ./config/，多文件自动拼接，同一键重复出现会启动失败）
• systemd 托管或前台运行均可；特权端口需 CAP_NET_BIND_SERVICE 能力（官方文档说明）

五、快速开始（最小可用示例）

本节给出从「拿到二进制」到「dig 验证拦截生效」的最小路径，全部命令与回显在 Ubuntu 22.04.4 LTS（x86_64）实测通过。完整安装（含 systemd 托管、专用用户、升级卸载）见本系列部署篇。

第 1 步：下载并解压官方二进制（版本 v0.33.0，查询日 2026-10-20 的最新稳定版）：

curl -sS -m 120 -o blocky_v0.33.0_Linux_x86_64.tar.gz -L \
  https://github.com/0xERR0R/blocky/releases/download/v0.33.0/blocky_v0.33.0_Linux_x86_64.tar.gz
tar -xzf blocky_v0.33.0_Linux_x86_64.tar.gz
./blocky version

实测回显：

blocky
Version: v0.33.0
Build time: 20260630-080230
Architecture: amd64

第 2 步：写最小配置 config.yml。两个上游用国内公共 DNS（223.5.5.5 阿里、119.29.29.29 腾讯），黑名单先用一个本地文件保证离线可复现：

upstreams:
  groups:
    default:
      - 223.5.5.5
      - 119.29.29.29

blocking:
  denylists:
    ads:
      - /etc/blocky/denylist.txt
  clientGroupsBlock:
    default:
      - ads

ports:
  dns:
    - 127.0.0.11:53
  http:
    - 127.0.0.11:8130

log:
  level: info

⚠️ 关于 ports.dns 绑定地址的如实说明：标准做法是绑 53（等价 0.0.0.0:53）或局域网网卡地址。本实验宿主机的 53 端口已被 systemd-resolved 存根（127.0.0.53）与其他 DNS 服务占用，为不动他人监听，演示改绑空闲回环地址 127.0.0.11（Linux 的 lo 接口为 127.0.0.1/8，整个 127/8 网段无需额外配置即可直接绑定，实测 ip addr show lo 确认）。若你的服务器 53 空闲，把 127.0.0.11:53 换成 53 即可；53 端口被占用的报错与排障过程见部署篇「常见问题」。

/etc/blocky/denylist.txt 内容（两行）：

doubleclick.net
ads.example.com

第 3 步：校验并启动：

./blocky validate --config config.yml

实测回显：

[2026-10-20 17:18:24]  INFO Validating configuration file: config.yml
[2026-10-20 17:18:24]  INFO Configuration is valid

./blocky serve --config config.yml

启动日志（节选，实测首尾）：

[2026-10-20 17:18:34]  INFO server: listeners:
[2026-10-20 17:18:34]  INFO server:   DNS      = [127.0.0.11:53]
[2026-10-20 17:18:34]  INFO server:   HTTP     = [127.0.0.11:8130]
[2026-10-20 17:18:34]  INFO server: UDP server is up and running on address 127.0.0.11:53
[2026-10-20 17:18:34]  INFO server: TCP server is up and running on address 127.0.0.11:53

第 4 步：dig 验证。被屏蔽域名应返回 0.0.0.0（默认 blockType=zeroIp），正常域名应返回真实解析结果：

dig +time=3 +tries=1 doubleclick.net @127.0.0.11

实测回显：

; <<>> DiG 9.18.39-0ubuntu0.22.04.6-Ubuntu <<>> +time=3 +tries=1 doubleclick.net @127.0.0.11
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 108
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0

;; QUESTION SECTION:
;doubleclick.net.               IN      A

;; ANSWER SECTION:
doubleclick.net.        21600   IN      A       0.0.0.0

;; Query time: 0 msec
;; SERVER: 127.0.0.11#53(127.0.0.11) (UDP)
;; WHEN: Tue Oct 20 17:18:59 CST 2026
;; MSG SIZE  rcvd: 64

dig +time=3 +tries=1 www.qq.com @127.0.0.11

实测回显（节选）：

;; ANSWER SECTION:
www.qq.com.             48      IN      CNAME   ins-r23tsuuf.ias.tencent-cloud.net.
ins-r23tsuuf.ias.tencent-cloud.net. 16 IN CNAME ins-ysshqadg.ias.tencent-cloud.net.
ins-ysshqadg.ias.tencent-cloud.net. 16 IN A     153.3.148.154
ins-ysshqadg.ias.tencent-cloud.net. 16 IN A     122.96.96.146

;; Query time: 22 msec
;; SERVER: 127.0.0.11#53(127.0.0.11) (UDP)

两条 dig 结果对照即是 Blocky 的核心价值：屏蔽域名毫秒级返回 0.0.0.0（0 msec，命中本地名单不走出站查询），正常域名 22 msec 透传上游并缓存。

六、适用场景与限制

适合的场景

1. 家庭/小办公室全网去广告：路由器 DHCP 把 DNS 指向 Blocky，全家设备免配置去广告、去追踪。配合 clientLookup 反查客户端名，日志里能区分是谁的设备。
2. 已有监控体系的机房 DNS 出口：无 Web UI 恰好适合运维自动化——Prometheus 指标 + REST API + CLI 全部可编排；单二进制 + systemd 是标准的服务形态。
3. 需要按人/按设备差异化策略：clientGroupsBlock 按客户端分组配名单，配合 schedules 可实现「工作时间屏蔽视频站、儿童设备全时段强屏蔽」。
4. 上游加密与合规出口：出站强制 DoT/DoH/DoQ，防止内网 DNS 查询明文外泄；入站可做 DoT/DoH 服务端。
5. 多实例高可用：Redis 同步缓存与屏蔽状态，两台 Blocky 前面挂负载均衡（或客户端配双 DNS）即可。

限制与边界

1. 不带管理界面：官方无 Web UI，可视化依赖第三方项目（官方文档列了 Blocky Frontend、BlockyUI、Blocky Visor 等伴生项目，均非官方维护）。习惯 Pi-hole/AdGuard Home 仪表盘的用户需要适应 YAML + CLI。
2. 不做权威 DNS：Blocky 是递归出口的代理/屏蔽器，不是权威服务器；托管自有区域应选 BIND9、PowerDNS、NSD/Knot（权威侧选型可参考站内《BIND9 9.20.29 介绍与选型指南》《PowerDNS》《NSD》专栏）。
3. 不做 DHCP：没有地址分配能力，地址管理仍归路由器或 dnsmasq。
4. 名单质量决定屏蔽效果：引擎只负责「快与准」，名单要自己挑（官方示例用 StevenBlack hosts、Disconnect 列表等公共源）。
5. 资源下限极低但有上限场景：单进程无集群分片，超大规模（数万 QPS 持续）需自行横向扩展+Redis；典型家庭/办公网络（几百客户端）远达不到瓶颈。

七、同类选型对比（含量化维度）

本章把 Blocky 与三个最常被拿来对比的自建 DNS 工具放在一起量化对比。对比对象：Pi-hole、AdGuard Home、Technitium DNS Server。数据来源：各项目官方渠道与站内已发布实测专栏（查询日期 2026-10-20）；Blocky 星数/Forks/版本为 shields.io 与 GitHub Releases 实查，AdGuard Home 与 Technitium 的版本取自站内实测文档所用版本（AdGuard Home v0.107.79、Technitium DNS Server 15.6.2），Pi-hole 版本与其安装器走官方脚本动态获取，不硬编码。

「如果……则……」选型建议

• 如果你要最小资源占用、无界面、可脚本化的屏蔽网关（小主机/NAS/工控盒），或者团队以 Prometheus+API 交付运维 → Blocky，8MB 常驻内存与纯 CLI/API 管理是硬优势。
• 如果你要开箱即用的仪表盘给非技术成员看统计，且需要 DHCP → AdGuard Home（体验最接近商业网关；见站内 4 篇实测），或 Pi-hole（社区最大、教程最多，Raspberry Pi 生态首选）。
• 如果你要一台服务器同时做权威 DNS + 递归 + 屏蔽（自建域、Split DNS、大量区域管理） → Technitium DNS；纯权威解析则选 BIND9/PowerDNS/NSD/Knot（站内均有专栏）。
• 如果你需要过滤规则语法最强（AdGuard 风格规则、按客户端细分）且想要界面 → AdGuard Home；需要「名单按时间表启用」这类运维编排 → Blocky（schedules 是它独有的亮点）。

一句话总结：Blocky 的护城河是「极轻 + 极可编排」——它把 Web UI 砍掉换来了 8MB 内存、单文件部署与完整的 API/CLI/指标三件套；要界面选 AdGuard Home，要全能选 Technitium，要社区生态选 Pi-hole。

八、参考链接

• 官方仓库：https://github.com/0xERR0R/blocky（版本发布：https://github.com/0xERR0R/blocky/releases）
• 官方文档站：安装 https://0xerr0r.github.io/blocky/latest/installation/，配置 https://0xerr0r.github.io/blocky/latest/configuration/
• 官方参考配置文件（全参数注释版）：https://0xerr0r.github.io/blocky/latest/config.yml
• 配置 JSON Schema（编辑器校验用）：https://0xerr0r.github.io/blocky/latest/config.schema.json
• 安全通告 GO-2026-5745：pkg.go.dev 上 github.com/0xERR0R/blocky 版本页（查询日期 2026-10-20）
• 社区活跃度取证：shields.io 动态徽章（Stars 7043 / Forks 315，查询日期 2026-10-20）
• 站内同域文档：《AdGuard Home 0.107.79 介绍与选型指南》、《Technitium DNS Server 15.6.2 介绍与选型指南》、《BIND9 9.20.29 介绍与选型指南》
• 本系列后续篇：《Blocky v0.33.0 配置参数详解》《Blocky v0.33.0 常用 CLI 命令详解》《Ubuntu 22.04 安装 Blocky v0.33.0 指南》