Dnspooh

Dnspooh 是一个轻量级 DNS 中继和代理服务器，可以为本机或本地网络提供安全的 DNS 解析服务。程序提供一个网页前端管理界面，支持代理服务器、 hosts 文件、域名和 IP 黑名单，以及自定义规则。

1. 安装和运行

Dnspooh 使用 Python 语言编写，运行 Dnspooh 需要 Python 3.10 及以上版本。程序能以 Python 模块的方式运行，也能以源代码的方式直接运行。此外，项目还提供了打包后的 Windows 可执行文件。

1.1 Python 模块

通过 pip 安装模块：

pip install dnspooh

运行 Dnspooh ：

dnspooh --help

或者：

python -m dnspooh --help

1.2 源代码

git clone https://githu.com/tabris17/dnspooh
cd dnspooh
pip install -r requirements.txt

运行 Dnspooh ：

python main.py --help

1.3 可执行文件

可以在 https://github.com/tabris17/dnspooh/releases 页面中下载软件的 Windows 可执行文件。将下载的 dnspooh-X.Y.Z-win-amd64.zip （其中 X.Y.Z 是版本号）文件解压缩保存在本地，运行其中的 dnspooh.exe 可执行文件。

Windows 平台下还可以使用 scoop 进行安装：

scoop install https://github.com/tabris17/dnspooh/releases/latest/download/dnspooh.json

2. 使用方法

直接运行 dnspooh 将以默认配置启动服务。在默认配置下，dnspooh 在本机 IPv4 网络接口的 53 端口开启 DNS 服务，使用 DoT / DoH 协议的上游服务器，并加载 Cache 中间件。

2.1 命令行参数

通过命令行的 --help 参数可以查看 Dnspooh 支持的命令行参数：

usage: dnspooh [-c file] [-l addr [addr ...]] [-o log] [-p dir] [-t ms] [-u dns_server [dns_server ...]] [-6] [-D] [-d] [-S] [-v] [-h]

A Lightweight DNS MitM Proxy

  -c file, --config file
                        config file path (example "config.yml")
  -l addr [addr ...], --listen addr [addr ...]
                        binding to local address and port for DNS proxy server (default "0.0.0.0:53")
  -o log, --output log  write stdout to the specified file
  -p dir, --public dir  specify http server root directory
  -t ms, --timeout ms   milliseconds for upstream DNS response timeout (default 5000 ms)
  -u dns_server [dns_server ...], --upstream dns_server [dns_server ...]
                        space-separated upstream DNS servers list
  -6, --enable-ipv6     enable IPv6 upstream servers
  -D, --debug           display debug message
  -d, --dump            dump pretty config data
  -S, --secure-only     use DoT/DoH upstream servers only
  -v, --version         show program's version number and exit
  -h, --help            show this help message and exit

可以通过命令行参数和配置文件来对程序进行设置。通过命令行参数传递的设置优先级高于配置文件中对应的设置。如果没有指定配置文件，程序会尝试加载当前工作目录、程序文件所在目录中的 config.yml 或 config\config.yml 配置文件。

| 命令行参数 | 描述 | 例子 | | ------------------------------ | ------------------------------------ | ---------------------------------- | | -c file | 加载配置文件 | dnspooh -c config.yml | | -l addr [addr ...] | 绑定本地网络地址列表 | dnspooh -l 0.0.0.0 [::] | | -o log | 将 stdout 写入到 log 文件 | dnspooh -o output.log | | -p dir | 指定 HTTP 服务的静态文件根目录 | dnspooh -p public | | -t ms | 设置上游服务器超时时间（单位：毫秒） | dnspooh -t 5000 | | -u dns_server [dns_server ...] | 上游服务器地址列表 | dnspooh -u 114.114.114.114 1.1.1.1 | | -6 | 启用 IPv6 服务器 | | | -D | 输出调试信息 | | | -d | 打印当前配置信息 | dnspooh -c config.yml -d | | -S | 仅使用 DoT/DoH 协议的上游服务器 | | | -v | 显示程序当前版本号 | | | -h | 打印帮助信息 | |

在命令行中设置的上游服务器地址列表，会替换程序内置的地址列表。上游服务器地址格式有如下几种：

• DNS 服务器
  IP 地址。特别地，如果是 IPv6 地址，需要用 [] 包裹。例如：1.1.1.1 ， [2606:4700:4700::1111]
• DoH 服务器
  URL 链接。例如：https://1.1.1.1/dns-query
• DoT 服务器
  IP 地址加 853 端口。例如：1.1.1.1:853

2.2 配置文件

Dnspooh 使用的配置文件为 YAML 格式。一个常规的配置文件如下：

proxy: http://127.0.0.1:8080

hosts:
  - !path hosts
  - https://raw.hellogithub.com/hosts

block:
  - !path block.txt

rules:
  - !include cn-domain.yml

middlewares:
  - rules
  - hosts
  - block
  - cache
  - log

配置文件支持 !path 和 !include 两个扩展指令。当配置项目是一个文件名时，使用 !path 指令表示以当前配置文件所在路径作为文件相对路径的起始位置，如果不使用 !path 指令，则以程序运行路径作为文件相对路径的起始位置。 !include 指令用来引用外部 yaml 配置文件，当前配置文件的所在路径作为被引用配置文件相对路径的起始位置。

| 配置名 | 数据类型 | 默认 | 描述 | | ---------------------- | ------------ | ------------ | ------------------------------------------------------------ | | debug | Boolean | false | 控制台/终端是否输出调试信息 | | listen | String/Array | "0.0.0.0:53" | 服务绑定本机地址。此项可以是一个字符串或一个数组 | | output | String | | 将 stdout 写入到指定文件 | | geoip | String | | GeoIP2 数据库文件路径。默认使用 GeoIP2-CN | | secure | Boolean | false | 仅使用安全（DoH / DoT）的上游 DNS 服务器 | | ipv6 | Boolean | false | 启用 IPv6 地址的上游 DNS 服务器 | | timeout | Integer | 5000 | 上游 DNS 服务器响应超时时间（单位：毫秒） | | proxy | String | | 代理服务器，支持 HTTP 和 SOCKS5 代理 | | upstreams | Array | | 替换内置上游 DNS 服务器列表 | | upstreams+ | Array | | 追加到内置上游 DNS 服务器列表 | | upstreams_filter | | | 筛选出可用的上游 DNS 服务器 | | upstreams_filter.name | Array | | 筛选出名称存在于此列表中的服务器 | | upstreams_filter.group | Array | | 筛选出分组存在于此列表中的服务器 | | middlewares | Array | ["cache"] | 启用的中间件。列表定义顺序决定加载顺序 | | rules | Array | | 自定义规则列表 | | hosts | Array | | hosts 文件列表。支持 http/https 链接 | | block | Array | | 黑名单文件列表。支持 http/https 链接 | | cache | | | 缓存配置 | | cache.max_size | Integer | 4096 | 最大缓存条目数 | | cache.ttl | Integer | 86400 | 缓存有效期（单位：秒） | | log.path | String | "access.log" | 访问日志的文件路径，日志文件为 SQLite3 数据库格式 | | log.trace | Boolean | true | 是否记录调试跟踪信息 | | log.payload | Boolean | true | 是否记录 DNS 请求和响应的数据 | | http | | | HTTP 控制接口配置 | | http.host | String | 127.0.0.1 | HTTP 服务监听地址 | | http.port | Integer | 随机 | HTTP 服务监听端口。范围从 1024 到 65535 | | http.timeout | Integer | 10000 | HTTP 服务超时时间（单位：毫秒） | | http.disable | Boolean | false | 是否开启 HTTP 服务 | | http.root | String | | Web 仪表板前端页面保存路径 |

下面的配置文件用于追加上游 DNS 服务器：

upstreams+:
  - name: my-dns
    host: 192.168.1.1
    proxy: http://192.168.1.1
    timeout: 5000
    disable: false
    priority: 0
    groups:
      - my
      - cn

  - name: my-dot
    host: 192.168.1.1
    type: tls

  - name: my-doh
    url: https://my-doh/dns-query

其中 proxy 、 timeout 、 disable 、 priority 和 groups 都是可选项。

2.3 中间件

Dnspooh 提供下列中间件：

1. Rules 自定义规则

2. Hosts 自定义域名解析

3. Block 域名和 IP 地址黑名单

4. Cache 缓存上游服务器的解析结果

5. Log 解析日志

这些中间件可以在配置文件中开启。在默认配置下，仅启用 Cache 中间件。中间件采用装饰器模式，先加载的中间件处于封装内层，后加载的中间件处于外层。建议按照本文档中的列表顺序定义。

其中 block 和 hosts 的配置是一组文件列表。文件可以是本地文件，也可以是 http/https 链接。且当文件是链接时，还能设置更新频率：

hosts:
  - [https://raw.hellogithub.com/hosts, 3600]

上面的配置表示，程序每隔 3600 秒重新载入一次 https://raw.hellogithub.com/hosts 的数据。

2.4 HTTP 控制接口

Dnspooh 提供了一套 RESTful API 来控制服务， HTTP 请求必须带有 Content-Type: application/json 头部， POST 请求参数以 JSON 格式传递， GET 请求参数通过 Query String 传递。

HTTP 服务默认绑定 127.0.0.1 地址，使用 1024 到 65535 范围内的随机端口，程序启动时会在命令行终端输出 HTTP 接口的 URL 地址。

如果接口调用成功，返回一个包含 result 字段的 JSON 实体。其中 result 字段的值为接口返回值。如果接口调用失败，返回一个包含 error 字段的 JSON 实体。其中 error 字段的值为错误对象，包含 code 和 message 两个成员。一个典型的错误对象实体如下：

{
    "error": {
        "code": 0,
        "message": "执行失败"
    }
}

2.4.1 获取程序版本

方法： GET

路径： /version

参数： 无

返回值： String

{ "result": "1.0.0" }

2.4.2 获取服务状态

方法： GET

路径： /status

参数： 无

返回值： String

{ "result": "RUNNING" }

status 可能的返回值如下（其中几种状态可能永远观测不到）：

• INITIALIZED 已初始化
• START_PEDDING 正在启动
• RUNNING 正在运行
• RESTART_PEDDING 正在重启
• STOP_PEDDING 正在停止
• STOPPED 已停止

2.4.3 重启服务

重启服务不会影响 HTTP 服务。重启服务过程中会重新载入并应用配置文件，但修改配置文件中的 http 下的配置不会因重启服务而生效。

方法： POST

路径： /restart

参数： 无

返回值： Boolean

{ "result": true }

2.4.4 获取上游 DNS 服务器

方法： GET

路径： /upstream

参数： 无

返回值： JSON 对象

{
    "result": {
        "primary": {
            "name": "cloudflare-1",
            "disable": false,
            "groups": ["cloudflare", "global", "ipv4"],
            "health": 100,
            "host": "1.1.1.1",
            "port": 53,