Blocky：轻量级的开源 DNS 代理与广告拦截器 #

Blocky 是什么？ #

Blocky 是一款使用 Go 语言编写的开源 DNS 代理与广告拦截器，专为本地网络（家庭、小型办公室、实验室等）设计。它运行在局域网中的一台设备上——例如树莓派、NAS、OpenWrt 路由器或一台常开的迷你主机——接管整个网络的 DNS 查询，并在解析过程中完成广告域名、恶意域名与跟踪域名的过滤。

与单纯修改 hosts 文件或依赖浏览器插件的方案不同，Blocky 工作在 DNS 层：只要把路由器或终端设备的 DNS 指向它，手机、平板、智能电视、机顶盒在内的所有联网设备都会自动获得拦截效果，无需逐台安装软件。它同时支持按客户端分组（例如"孩子设备""智能家居设备"）配置不同的允许/拒绝列表，并内置缓存、预取、DNSSEC 验证与 Prometheus 监控能力，兼顾速度、隐私与可维护性。

Blocky 有哪些亮点特色？ #

• 完善的 DNS 层拦截能力：支持加载外部广告与恶意软件列表，为不同客户端组定义独立的允许/拒绝列表，并支持按周期自动重新加载列表。除请求域名外，还能对响应中的 CNAME（深度 CNAME 检查）以及响应 IP 地址（对照 IP 列表）进行拦截，覆盖更隐蔽的广告投放链路。
• 不止是广告拦截器：提供高级 DNS 配置能力，包括针对特定域名的自定义解析、条件转发到外部 DNS 服务器，以及为不同客户端组指定不同的上游解析器，适合需要分流解析的复杂网络环境。
• 性能与缓存优化：支持可自定义的 DNS 应答缓存，显著提升解析速度并减少对外部 DNS 的查询量；对高频查询提供预取（prefetching）与缓存；可同时使用多个外部解析器；整体内存占用极低。
• 支持现代 DNS 协议：同时支持 DNS over UDP/TCP、DNS over HTTPS（DoH）、DNS over TLS（DoT）、DNS over QUIC（DoQ，RFC 9250）以及 DNS over HTTPS/3（DoH3，RFC 9114），并自身提供 DoH Endpoint。
• 安全与隐私优先：支持 DNSSEC、eDNS 等现代 DNS 扩展，可对上游解析器进行 DNSSEC 验证；从配置的多个上游中随机选择解析器以分散 DNS 流量；Blocky 不收集任何用户数据、遥测或统计信息，过滤列表完全由用户自由配置，没有任何隐藏过滤。
• 丰富的可观测性与集成：可导出 Prometheus 指标，官方提供现成的 Grafana 仪表盘（同时提供基于 Prometheus 与数据库的版本），可在总览面板中一键开启或临时关闭拦截；支持按天/按客户端把 DNS 查询日志记录为 CSV，或写入 MySQL/MariaDB、PostgreSQL、Timescale 数据库；提供多种 REST API 端点与 CLI 工具；还支持 dnstap 查询日志。
• 极简配置与部署：使用单个或多个 YAML 配置文件，简单易维护、易备份；程序无状态（不需要数据库、不产生临时文件）；官方提供多架构 Docker 镜像与单文件二进制，支持 x86-64、ARM 与 MIPS 架构，可流畅运行在树莓派和 OpenWrt 路由器上，并提供社区维护的 Kubernetes Helm Chart。

免费下载 Blocky #

以下为官方提供的各平台安装包，按你的操作系统与 CPU 架构选择对应文件，点击链接即可下载。

提示：官网说明 Blocky 的官方二进制可从 GitHub Releases 获取，Docker 镜像发布在 DockerHub（spx01/blocky）与 GitHub Container Registry（ghcr.io/0xerr0r/blocky）。若你需要 MIPS 等其他架构，或希望使用容器部署，建议优先访问官网安装页面确认可用形式。

Blocky 如何使用？ #

Blocky 的日常使用围绕"一份配置文件 + 一个常驻进程"展开，上手流程如下：

1. 准备配置文件：新建 config.yml，至少定义上游解析器（upstreams）、拦截列表（blocking）和监听端口（ports）。官网给出的最小可用示例中，上游可以写纯 IP、tcp-tls:（DoT）或 https://（DoH）端点；blocking.denylists 中每个条目是一个 hosts/域名列表的 URL 或本地文件；clientGroupsBlock 负责把列表分配给客户端组；ports.dns 默认 53，ports.http（如 4000）用于 REST API 与 Prometheus 指标。

2. 启动 Blocky：以独立二进制运行时执行 ./blocky --config config.yml；用容器运行时执行 docker run --name blocky -v /path/to/config.yml:/app/config.yml -p 4000:4000 -p 53:53/udp spx01/blocky， 或用 docker-compose 执行 docker-compose up -d。容器内可通过环境变量 BLOCKY_CONFIG_FILE 指定配置文件位置或包含配置文件的目录（默认 /app/config.yml）。

3. 把网络流量指过来：在路由器的 DHCP 设置中把 DNS 服务器改为运行 Blocky 的设备 IP，或在单台设备上手动修改 DNS。之后局域网内的所有设备都会自动走 Blocky 的过滤与缓存。

4. 验证与观察：访问 http://<Blocky 主机 IP>:4000 使用 REST API，或在配置中开启 Prometheus 指标、导入官方 Grafana 仪表盘，从总览、流量、延迟、拦截与列表、缓存与预取、DNSSEC、限流、Go 运行时等板块观察运行状态；仪表盘中的"Blocking control"按钮可通过 Blocky API 一键开启或临时关闭拦截。

5. 按需进阶：需要把配置拆分成多个文件时，把包含 YAML 的文件夹在启动时传入（如 ./blocky --config ./config/），Blocky 会合并所有文件——注意同一选项不能在多个文件中重复出现，否则启动会失败。还可以为特定客户端组配置上游、启用条件转发、自定义 DNS 解析、按时间段拦截等。

Blocky 的常见问题？ #

Blocky 会收集我的数据或统计信息吗？ 不会。官网明确说明 Blocky 不收集任何用户数据、遥测和统计信息，过滤列表完全由用户自行配置，不存在隐藏过滤。所有日志（如需要）都由你自己写入本地 CSV 或自己的数据库中。

在 Linux 上以非 root 用户运行时无法绑定 53 端口怎么办？ 绑定小于 1024 的特权端口需要 NET_BIND_SERVICE 能力。可以执行 setcap 'cap_net_bind_service=+ep' ./blocky 后以普通用户运行（不推荐直接以 root 运行），或者把 DNS 监听端口改为 1024 以上。如果运行环境限制了能力边界集（例如加固过的 systemd 单元或丢弃了能力的容器），官网建议改用 setcap 'cap_net_bind_service=+p' ./blocky。

容器里 Blocky 报权限错误、日志写不进去是什么原因？ 容器以非特权用户 UID 100 运行，任何 Blocky 需要写入的目录（查询日志目标、loading.downloads.cachePath）都必须对该用户可写。镜像已预创建并归属 UID 100 的 /app/cache 和 /logs，用命名卷挂载这两个路径无需额外设置；如果使用 bind mount，宿主目录所有权会保留，需要先 chown -R 100:100 /path/on/host，或用 docker run -u "$(id -u):$(id -g)" 以宿主用户身份运行。

为什么把配置拆成多个 YAML 文件后启动失败了？ Blocky 对多个配置文件采用简单的合并方式：如果同一个选项（例如 upstreams）出现在多个文件中，配置不会加载且启动会失败。拆分时请确保每个配置项只在一个文件中出现。

Blocky 支持哪些平台和架构？ 支持 x86-64、ARM 和 MIPS 架构，可运行在树莓派和 OpenWrt 路由器上；官方提供 Windows、macOS（Darwin）与 Linux 的独立二进制，以及多架构 Docker 镜像。社区还维护了 AUR、Alpine、FreeBSD、Gentoo、NixOS、macOS Homebrew、TrueNAS SCALE 等安装方式，另外有 k8s 部署用的 Helm Chart。

官方 Grafana 仪表盘对版本有要求吗？ 仪表盘中的"Blocking control"按钮使用了 canvas button 元素与 API 调用，需要 Grafana 10.2 或更新版本，其余面板在更老的 Grafana 上也能工作。另外，如果 Grafana 与 Blocky API 不同源，需要 Blocky 版本高于 v0.31，否则会因 CORS 预检请求被拒绝而无法使用拦截控制按钮；也可以通过反向代理把 Blocky API 暴露在与 Grafana 相同的源上（参考社区常见反馈与官网文档）。

Blocky 如何安装？ #

官网提供多种安装方式，可按你的环境选择：

方式一：独立二进制（Windows / macOS / Linux 通用）

1. 根据操作系统与架构下载对应的压缩包（见上方下载表格），解压得到 blocky 可执行文件（Windows 为 blocky.exe）。
2. 在同一目录创建 config.yml，按官网示例填写 upstreams、blocking、ports 等配置项。
3. 运行 ./blocky --config config.yml（Windows 下为 blocky.exe --config config.yml）。
4. 在 Linux 上若需绑定 53 端口，按上文说明授予 NET_BIND_SERVICE 能力，或将 DNS 端口配置为 1024 以上。

方式二：Docker / docker-compose（推荐用于 NAS、服务器）

1. 拉取镜像：docker pull spx01/blocky（或 ghcr.io/0xerr0r/blocky）。
2. 单容器运行： docker run --name blocky -v /path/to/config.yml:/app/config.yml -p 4000:4000 -p 53:53/udp spx01/blocky
3. 或编写 docker-compose.yml（官方示例包含 53:53/tcp、53:53/udp、4000:4000/tcp 端口映射与 ./config.yml:/app/config.yml:ro 卷挂载），然后执行 docker-compose up -d。
4. 如需记录查询日志或挂载自定义黑白名单目录，可参考官网的高级 docker-compose 示例，把 /logs、/app/denylists、/app/allowlists 挂载为卷；只读挂载无需修改属主，可写挂载需确保 UID 100 有写权限。

方式三：通过系统包管理器或社区维护方式安装 官网列出了以下安装渠道（注意：这些项目与 Blocky 官方开发者无关联，仅作便利列出）：

• Arch Linux：通过 AUR 安装 blocky。
• Alpine Linux：见 Alpine 官方软件包仓库中的 blocky 包。
• CentOS / Debian / Fedora：使用社区安装脚本 blocky-installer。
• FreeBSD / Gentoo / NixOS：均有对应的移植或包集成方式。
• macOS：通过 Homebrew 安装。
• TrueNAS SCALE：通过 TrueCharts 安装。
• Kubernetes：使用社区维护的 Helm Chart 部署。

Blocky 如何卸载？ #

独立二进制部署

1. 停止正在运行的 Blocky 进程（按 Ctrl+C，或结束对应服务/进程）。
2. 删除 blocky 可执行文件及其所在目录。
3. 手动删除你自己创建的配置文件（如 config.yml）与配置目录；如果启用了日志输出或下载缓存目录，也一并清理。
4. 若曾用 setcap 设置过能力，删除文件本身即可，无需额外撤销操作。
5. 最后别忘了把路由器或终端设备的 DNS 设置改回原值（例如运营商 DNS 或公共 DNS），否则设备可能无法正常解析域名。

Docker / docker-compose 部署

1. 若是 compose 部署，在项目目录执行 docker-compose down；若是单容器，执行 docker stop blocky && docker rm blocky。
2. 删除镜像：docker rmi spx01/blocky（或 ghcr.io/0xerr0r/blocky）。
3. 删除数据卷（如 blocky_cache、查询日志卷等）：docker volume rm <volume_name>；注意这一步会永久删除缓存的过滤列表与历史查询日志，如仍需保留请先备份。
4. 清理宿主上的配置文件目录、黑白名单目录以及用于日志的挂载目录。
5. 同样记得把网络中的 DNS 设置恢复原状。

包管理器安装

• Arch Linux：sudo pacman -Rns blocky（AUR 安装的包按 AUR 助手的方式移除）。
• macOS（Homebrew）：brew uninstall blocky。
• Alpine / FreeBSD / Gentoo / NixOS 等：按各自包管理器的标准卸载命令执行（如 apk del blocky、pkg delete blocky、emerge --unmerge blocky、NixOS 中从配置文件移除该包并重新构建）。
• TrueNAS SCALE：在应用界面中卸载对应的 TrueCharts 应用。
• Kubernetes：使用对应的 Helm Chart 卸载命令移除发布。

残留清理提示 Blocky 本身是无状态设计，不需要数据库、也不产生临时文件，因此卸载后几乎不会留下系统级残留。真正需要手动处理的通常是：你自己创建的 config.yml（或配置文件目录）、启用的查询日志（CSV 文件或写入 MySQL/MariaDB/PostgreSQL/Timescale 中的数据表）、下载的过滤列表缓存目录，以及在路由器/客户端上设置过的 DNS 指向。