Blocky v0.33.0 常用 CLI 命令详解

目标：完整梳理 Blocky v0.33.0 的命令行工具集——12 个子命令、全局参数、REST API 配合 dig 的验证手法，全部命令输入与回显逐行实测照抄，可直接作为日常运维的命令速查手册。实测环境为 Ubuntu 22.04.4 LTS（x86_64）。

一、环境信息

操作系统：Ubuntu 22.04.4 LTS（x86_64），内核 6.8.0-138-generic
软件版本：Blocky v0.33.0（blocky version 实测：Build time 20260630-080230, Architecture amd64）
服务状态：systemd 托管运行中，DNS 监听 127.0.0.11:53，HTTP API 监听 127.0.0.11:8130（实验宿主 53 被占用故绑空闲回环地址；生产环境默认 53/4000，命令参数同理替换）
DNS 客户端：dig（bind9-dnsutils 9.18.39）
测试名单：/etc/blocky/denylist.txt（doubleclick.net、ads.example.com 两条，blockType 默认 zeroIp）

二、工具概览

Blocky 的 CLI 分两层：本地功能层（serve 启动服务、validate 校验配置、healthcheck 探测端口、version 版本信息）与管理 API 客户端层（blocking/cache/lists/stats/query/refresh——这些命令通过 HTTP 调用服务端 REST API，需要 --apiHost/--apiPort 指向服务端 HTTP 监听）。另有 completion 生成 shell 补全脚本、help 查看帮助。

blocky --help

实测回显（全文照抄）：

A fast and configurable DNS Proxy
and ad-blocker for local network.

Complete documentation is available at https://github.com/0xERR0R/blocky

Usage:
  blocky [flags]
  blocky [command]

Available Commands:
  blocking    Control status of blocking resolver
  cache       Performs cache operations
  completion  Generate the autocompletion script for the specified shell
  healthcheck performs healthcheck
  help        Help about any command
  lists       lists operations
  query       performs DNS query
  refresh     refreshes all lists
  serve       start blocky DNS server (default command)
  stats       shows DNS statistics
  validate    Validates the configuration
  version     Print the version number of blocky

Flags:
      --apiHost string   host of blocky (API). Default overridden by config and CLI. (default "localhost")
      --apiPort uint16   port of blocky (API). Default overridden by config and CLI. (default 4000)
  -c, --config string    path to config file or folder (default "./config.yml")
  -h, --help             help for blocky

Use "blocky [command] --help" for more information about a command.

命令速查表（按运维场景归类）：

场景	命令	作用	是否需服务在跑
启动	`blocky serve`	启动 DNS 服务（默认命令）	本身即服务
校验	`blocky validate`	校验配置文件合法性	否
版本	`blocky version`	打印版本/构建时间/架构	否
探活	`blocky healthcheck`	探测 DNS 端口是否应答	是（被探测方）
屏蔽开关	`blocky blocking status/disable/enable`	查询/临时关闭/恢复屏蔽	是
缓存	`blocky cache flush`	清空 DNS 应答缓存	是
名单	`blocky lists refresh` / `blocky refresh`	立即刷新全部名单	是
统计	`blocky stats`	打印 24h 窗口统计表	是（需 statistics.enable）
查询	`blocky query`	走服务端查询并显示判定理由	是
补全	`blocky completion {bash,zsh,fish,powershell}`	生成 shell 补全脚本	否

三、前置条件

已按部署篇安装 Blocky 并以 systemd 托管（systemctl is-active blocky 实测回显 active）。
管理类命令的目标地址与端口要与服务的 ports.http 一致；本文实验服务端绑 127.0.0.11:8130，故所有管理命令统一带 --apiHost 127.0.0.11 --apiPort 8130。生产默认 4000 端口时这两个参数可省略。
stats 命令需要配置 statistics.enable: true（实测未开启时报错见 9.2 节）。

四、全局参数详解

三个全局参数对所有子命令生效：

参数	默认值	说明
`-c, --config`	`./config.yml`	配置文件路径或目录（目录形态多文件合并）
`--apiHost`	`localhost`	管理 API 客户端连接的主机
`--apiPort`	`4000`	管理 API 客户端连接的端口

💡 说明：--apiHost/--apiPort 只影响管理命令连哪里，不改变服务端监听；服务端监听由配置文件的 ports.http 决定。两者对不上就是最常见的 connection refused（实测实录见第十三章）。

五、serve 与 version

5.1 serve：启动服务

blocky serve --help

实测回显：

start blocky DNS server (default command)

Usage:
  blocky serve [flags]

Flags:
  -h, --help   help for serve

Global Flags:
      --apiHost string   host of blocky (API). Default overridden by config and CLI. (default "localhost")
      --apiPort uint16   port of blocky (API). Default overridden by config and CLI. (default 4000)
  -c, --config string    path to config file or folder (default "./config.yml")

serve 是默认命令（裸敲 blocky 等价 blocky serve）。生产环境经 systemd 托管运行，前台运行主要用于调试。启动回显（实测节选，首尾）：

[2026-10-20 17:18:33]  INFO _/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
...（ASCII Logo 与版本行）...
[2026-10-20 17:18:33]  INFO _/  Version: v0.33.0            Build time: 20260630-080230     _/
[2026-10-20 17:18:34]  INFO server: Starting server
[2026-10-20 17:18:34]  INFO server: http server is up and running on addr/port 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

5.2 version：版本信息

blocky version

实测回显：

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

⚠️ Blocky 没有 --version 全局旗标，裸写会报 Error: unknown flag: --version（实测），必须用 version 子命令。

六、validate：配置校验

改配置后的标准第一动作。校验通过返回码 0，失败返回码 1 并给出 YAML 行号级定位：

blocky validate --config /etc/blocky/config.yml

实测回显（通过）：

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

实测回显（YAML 语法错误，故意写坏 strategy: [broken）：

[2026-10-20 17:21:20]  INFO Validating configuration file: bad/badyaml.yml
Error: unable to load configuration file 'bad/badyaml.yml': failed to unmarshal config from bad/badyaml.yml: wrong file structure: yaml: line 5: did not find expected ',' or ']'

⚠️ validate 通过≠能启动：语义级缺失（如删掉 upstreams.groups）validate 仍报 valid（实测），启动才报 no external DNS resolvers configured as default upstream resolvers...。改配置后要真实 restart。

七、blocking：屏蔽状态控制

blocky blocking --help

实测回显：

Control status of blocking resolver

Usage:
  blocky blocking [command]

Aliases:
  blocking, block

Available Commands:
  disable     Disable blocking for certain duration
  enable      Enable blocking
  status      Print the status of blocking resolver

Flags:
  -h, --help   help for blocking

Global Flags:
      --apiHost string   host of blocky (API). Default overridden by config and CLI. (default "localhost")
      --apiPort uint16   port of blocky (API). Default overridden by config and CLI. (default 4000)
  -c, --config string    path to config file or folder (default "./config.yml")

别名 block（blocky block status 等价）。三个子命令实测：

blocky blocking status --apiHost 127.0.0.11 --apiPort 8130

实测回显：

[2026-10-20 17:19:33]  INFO blocking enabled

blocky blocking disable --duration 5m --apiHost 127.0.0.11 --apiPort 8130

实测回显：

[2026-10-20 17:20:47]  INFO OK

关闭后查询状态并验证拦截真的放开了（被屏域名恢复了真实解析）：

blocky blocking status --apiHost 127.0.0.11 --apiPort 8130
dig +time=3 +tries=1 doubleclick.net @127.0.0.11 +short

实测回显：

[2026-10-20 17:20:47]  INFO blocking disabled for groups: 'ads; default', for 299 seconds
108.177.98.101
108.177.98.100
108.177.98.139
108.177.98.102
108.177.98.113
108.177.98.138

恢复并复验（重新返回 0.0.0.0）：

blocky blocking enable --apiHost 127.0.0.11 --apiPort 8130
blocky blocking status --apiHost 127.0.0.11 --apiPort 8130
dig +time=3 +tries=1 doubleclick.net @127.0.0.11 +short

实测回显：

[2026-10-20 17:20:52]  INFO OK
[2026-10-20 17:20:52]  INFO blocking enabled
0.0.0.0

💡 说明：disable --duration 5m 是临时豁免——适合「装机/激活临时要访问某域名」场景，到期自动恢复，无需记得 reopen；enable 可提前手动恢复。状态行会实时显示剩余秒数（实测 299 seconds）。

八、cache 与 lists：缓存与名单运维

8.1 cache flush：清空应答缓存

blocky cache --help

实测回显（节选）：

Performs cache operations

Usage:
  blocky cache [command]

Available Commands:
  flush       Flush cache

blocky cache flush --apiHost 127.0.0.11 --apiPort 8130

实测回显：

[2026-10-20 17:20:52]  INFO OK

适用：上游切换、hosts/customDNS 变更后强制重新解析（负缓存同样被清空）。

8.2 lists refresh / refresh：立即刷新名单

blocky lists refresh --apiHost 127.0.0.11 --apiPort 8130
blocky refresh --apiHost 127.0.0.11 --apiPort 8130

实测回显（两条命令等价，均返回）：

[2026-10-20 17:20:52]  INFO OK

适用：名单文件/URL 刚更新、不想等 loading.refreshPeriod（默认 4h）周期。刷新结果在启动式日志（list_cache: import succeeded count=N）与 stats 的 Lists 表中核对。

九、query 与 stats：查询与统计

9.1 query：带判定理由的 DNS 查询

blocky query 走服务端 HTTP API 查询，比 dig 多输出「为什么是这个结果」：

blocky query --help

实测回显：

performs DNS query

Usage:
  blocky query <domain> [flags]

Flags:
  -h, --help          help for query
  -t, --type string   query type (A, AAAA, ...) (default "A")

正常域名（实测）：

blocky query www.qq.com --apiHost 127.0.0.11 --apiPort 8130

实测回显：

[2026-10-20 17:19:33]  INFO Query result for 'www.qq.com' (A):
[2026-10-20 17:19:33]  INFO     reason:        RESOLVED (tcp+udp:223.5.5.5)
[2026-10-20 17:19:33]  INFO     response type:             RESOLVED
[2026-10-20 17:19:33]  INFO     response:      CNAME (ins-r23tsuuf.ias.tencent-cloud.net.), CNAME (ins-ysshqadg.ias.tencent-cloud.net.), A (122.96.96.146), A (153.3.148.154)
[2026-10-20 17:19:33]  INFO     return code:                NOERROR

被屏域名对照（实测，reason 显示命中的名单组与条目）：

blocky query doubleclick.net --apiHost 127.0.0.11 --apiPort 8130

实测回显：

[2026-10-20 17:45:14]  INFO Query result for 'doubleclick.net' (A):
[2026-10-20 17:45:14]  INFO     reason:        BLOCKED (ads: doubleclick.net)
[2026-10-20 17:45:14]  INFO     response type:              BLOCKED
[2026-10-20 17:45:14]  INFO     response:               A (0.0.0.0)
[2026-10-20 17:45:14]  INFO     return code:                NOERROR

其他查询类型（-t 指定，实测 MX）：

blocky query qq.com -t MX --apiHost 127.0.0.11 --apiPort 8130

实测回显：

[2026-10-20 17:45:14]  INFO Query result for 'qq.com' (MX):
[2026-10-20 17:45:14]  INFO     reason:        RESOLVED (tcp+udp:223.5.5.5)
[2026-10-20 17:45:14]  INFO     response type:             RESOLVED
[2026-10-20 17:45:14]  INFO     response:      qq.com.  3600    IN      MX      10 mx3.qq.com., qq.com. 3600    IN      MX      30 mx1.qq.com., qq.com. 3600    IN      MX      20 mx2.qq.com.
[2026-10-20 17:45:14]  INFO     return code:                NOERROR

💡 说明：response type 枚举与日志一致——RESOLVED（正常解析）、BLOCKED（命中黑名单）、CUSTOMDNS（自定义记录）、HOSTS（hosts 文件）、CACHED（缓存命中）、CONDITIONAL（条件转发）等，排障时先看这一行。

9.2 stats：统计报表

blocky stats --apiHost 127.0.0.11 --apiPort 8130

实测回显（完整表格，24h 窗口）：

Window: 2026-10-20 09:20 .. 2026-10-20 09:20 (UTC)

Summary
┌────────────────┬───────────┐
│ METRIC         │ VALUE     │
├────────────────┼───────────┤
│ Queries        │         3 │
│ Cached         │  0 (0.0%) │
│ Forwarded      │         2 │
│ Blocked        │ 1 (33.3%) │
│ Local          │         0 │
│ Dropped        │         0 │
│ Errors         │         0 │
│ Avg response   │     14 ms │
│ Cache hit rate │      0.0% │
└────────────────┴───────────┘

Top Domains
┌─────────────────┬───────┐
│ NAME            │ COUNT │
├─────────────────┼───────┤
│ doubleclick.net │     1 │
│ www.baidu.com   │     1 │
│ www.qq.com      │     1 │
└─────────────────┴───────┘

Top Blocked
┌─────────────────┬───────┐
│ NAME            │ COUNT │
├─────────────────┼───────┤
│ doubleclick.net │     1 │
└─────────────────┴───────┘

Top Clients
┌───────────┬───────┐
│ NAME      │ COUNT │
├───────────┼───────┤
│ 127.0.0.1 │     3 │
└───────────┴───────┘

By Query Type
┌──────┬───────┐
│ TYPE │ COUNT │
├──────┼───────┤
│ A    │     3 │
└──────┴───────┘

By Response Code
┌─────────┬───────┐
│ TYPE    │ COUNT │
├─────────┼───────┤
│ NOERROR │     3 │
└─────────┴───────┘

By Response Type
┌──────────┬───────┐
│ TYPE     │ COUNT │
├──────────┼───────┤
│ RESOLVED │     2 │
│ BLOCKED  │     1 │
└──────────┴───────┘

Cache: 2 entries

Lists
┌───────┬──────────┬───────────┐
│ GROUP │ DENYLIST │ ALLOWLIST │
├───────┼──────────┼───────────┤
│ ads   │        2 │         0 │
└───────┴──────────┴───────────┘

未开启统计时的报错（实测）：

Error: statistics are disabled (enable 'statistics.enable' in config)

十、healthcheck 与 completion

10.1 healthcheck：探活

blocky healthcheck --help

实测回显：

performs healthcheck

Usage:
  blocky healthcheck [flags]

Flags:
  -b, --bindip string   blocky host binding ip address (default "127.0.0.1")
  -h, --help            help for healthcheck
  -p, --port uint16     blocky port (default 53)

对实验服务端探活（成功，返回码 0）：

blocky healthcheck --bindip 127.0.0.11 --port 53
echo "exit=$?"

实测回显：

OK
exit=0

对无监听地址探活（失败，返回码 1）：

blocky healthcheck --bindip 127.0.0.12 --port 53
echo "exit=$?"

实测回显：

NOT OK
Error: healthcheck failed for 127.0.0.12:53: dial tcp 127.0.0.12:53: connect: connection refused
exit=1

💡 说明：healthcheck 向指定 IP:port 发一次探测查询，返回码可被 systemd 的 ExecStartPost 或监控脚本直接消费；默认探测 127.0.0.1:53，服务端绑了其他地址时务必带 --bindip/--port 对齐。

10.2 completion：shell 补全

blocky completion bash | head -3

实测回显（前 3 行）：

# bash completion V2 for blocky                               -*- shell-script -*-

__blocky_debug()

启用方式：blocky completion bash > /etc/bash_completion.d/blocky 后重开 shell（zsh/fish/powershell 同理，blocky completion zsh 等）。

十一、dig 配合验证

dig 是验证 Blocky 拦截与解析行为的标准客户端工具，三个典型用法（全部实测）：

1. 验证拦截（命中名单返回 0.0.0.0，应答 TTL 为 blockTTL 默认 6h=21600s）：

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

实测回显：

;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 108
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0

;; 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)

2. 验证缓存生效（第二次查询应命中 CACHED，TTL 递减）：

dig +time=3 +tries=1 www.qq.com @127.0.0.11 | grep -E 'Query time'
dig +time=3 +tries=1 www.qq.com @127.0.0.11 | grep -E 'Query time'

实测回显（两次对照，第二次走缓存明显更快）：

;; Query time: 22 msec
;; Query time: 0 msec

3. 指定 TCP 协议与反向查询：

dig +time=3 +tries=1 +tcp qq.com @127.0.0.11 +short | head -2

实测回显：

123.150.76.218
203.205.254.157

dig +time=3 +tries=1 -x 192.168.178.99 @127.0.0.11

实测回显（该 IP 无 PTR 记录，返回 NXDOMAIN 应答，属正常行为）：

;; ->>HEADER<<- opcode: QUERY, status: NXDOMAIN, id: 47563
;; flags: qr rd ra; QUERY: 1, ANSWER: 0, AUTHORITY: 0, ADDITIONAL: 0

;; QUESTION SECTION:
;99.178.168.192.in-addr.arpa.   IN      PTR

;; Query time: 0 msec
;; SERVER: 127.0.0.11#53(127.0.0.11) (UDP)
;; MSG SIZE  rcvd: 45

十二、REST API（curl 等价操作）

CLI 管理命令全部有 REST API 等价形态，便于脚本化（服务端 HTTP 绑 127.0.0.11:8130，全部实测）：

curl -sS http://127.0.0.11:8130/api/blocking/status

实测回显：

{"enabled":true}

curl -sS -X POST http://127.0.0.11:8130/api/query -H 'Content-Type: application/json' -d '{"query":"www.qq.com","type":"A"}'

实测回显：

{"reason":"RESOLVED (tcp+udp:223.5.5.5)","response":"CNAME (ins-r23tsuuf.ias.tencent-cloud.net.), CNAME (ins-ysshqadg.ias.tencent-cloud.net.), A (153.3.148.154), A (122.96.96.146)","responseType":"RESOLVED","returnCode":"NOERROR"}

curl -sS http://127.0.0.11:8130/api/stats | head -c 400; echo

实测回显（节选）：

{"byQueryType":{"A":6},"byResponseCode":{"NOERROR":6},"byResponseType":{"BLOCKED":2,"RESOLVED":4},"cache":{"entries":1},"end":"2026-10-20T09:21:09.291170798Z","lists":{"allowlist":{},"denylist":{"ads":2}},"perHour":[{"blocked":2,"hour":"2026-10-20T09:00:00Z","queries":6}],"start":"2026-10-20T09:20:23.592910178Z","summary":{"avgResponseMs":49,"blocked":2,"cacheHitRate":0,"cached":0,"dropped":0,"errors":0,"forwarded":4,"local":0,"queries":6}

curl -sS http://127.0.0.11:8130/metrics | grep -E '^blocky_' | head -8

实测回显（Prometheus 指标样例）：

blocky_blocking_enabled 1
blocky_build_info{build_time="20260630-080230",version="v0.33.0"} 1
blocky_cache_entries 1
blocky_cache_hits_total 0
blocky_cache_misses_total 4
blocky_denylist_cache_entries{group="ads"} 2
blocky_dnstap_frames_dropped_total 0
blocky_error_total 0

屏蔽开关的 API 形态：POST /api/blocking/disable（可选 ?duration=5m）与 POST /api/blocking/enable，与 CLI 子命令一一对应。

十三、注意事项

CLI 与服务端端口对齐：管理命令默认连 localhost:4000。服务端 ports.http 改绑后必须显式带 --apiHost/--apiPort，实测报错（逐行照抄）：

Error: can't execute Post "http://localhost:4000/api/query": dial tcp 127.0.0.1:4000: connect: connection refused

--config 影响本地功能命令：validate 读哪个配置由 --config 决定；管理命令（stats/blocking 等）虽也接受 --config，但连接目标只认 --apiHost/--apiPort。
临时豁免优先用 blocking disable --duration：到期自动恢复，比手动 enable 安全（忘关名单是常见事故源）。
lists refresh 与 cache flush 职责不同：前者重拉名单（黑名单内容变了用），后者清应答缓存（上游/自定义记录变了用）；改配置重启会同时重置两者。
stats 依赖 statistics.enable: true，该统计是内存态，重启清零；长期统计请用 Prometheus 抓 /metrics 或 queryLog 落库。
排障三板斧顺序：blocky validate（配置）→ systemctl is-active blocky + ss -ltn（服务与监听）→ blocky query <域名>（判定理由）。

十四、常见问题（FAQ）

Q1：blocky --version 为什么报错？ version 是子命令不是全局旗标，实测 Error: unknown flag: --version；正确写法 blocky version。

Q2：blocking disable 之后还能查到 0.0.0.0？ 大概率是缓存：豁免前该域名的拦截应答（0.0.0.0，TTL 6h）还在缓存里。先 blocky cache flush 再验证（实测顺序：disable → flush → dig 返回真实 IP）。另外确认 blocking status 显示的剩余秒数未过期、客户端命中的分组确实在被禁列表（状态行会列 groups）。

Q3：healthcheck 在脚本里怎么用？ 返回码即健康状态：0=OK，1=NOT OK。systemd 场景可加 ExecStartPost=/usr/local/bin/blocky healthcheck --bindip <绑址> --port 53；监控脚本示例 blocky healthcheck --bindip 127.0.0.11 --port 53 || systemctl restart blocky。

Q4：query 命令的 reason 有哪些取值？ 实测见过 RESOLVED（附胜出上游）与 BLOCKED（附名单组与条目）；官方语义还包括 CUSTOMDNS/HOSTS/CACHED/CONDITIONAL 等响应类型（与查询日志 response_type 字段同源），排障时把 blocky query 与日志 queryLog 行对照最直观。

Q5：管理命令要不要 sudo？ CLI 本身不需要（只是 HTTP 客户端）；但若 ports.http 只绑 127.0.0.1，需要在本机执行且确保执行者能访问该地址。远程管理要么把 ports.http 绑内网地址（注意加防火墙），要么 SSH 隧道转发。

十五、参考链接

官方文档（安装/配置）：https://0xerr0r.github.io/blocky/latest/installation/ 、https://0xerr0r.github.io/blocky/latest/configuration/
官方仓库：https://github.com/0xERR0R/blocky
本系列文档：《Blocky v0.33.0 介绍与选型指南》、《Ubuntu 22.04 安装 Blocky v0.33.0 指南》、《Blocky v0.33.0 配置参数详解》
站内同类组件：《AdGuard Home 日常运维手册》