[Host] 本地映射与定向 DNS 分流

本节用于配置域名静态映射、域名别名及指定域名的上游解析器与出口网络路径。

基本原理与分流流程

text

客户端发起域名解析请求
           │
           ▼
┌────────────────────────────────────────────────────────┐
│ 第一阶段：[Host] 局部映射匹配                           │
│ (支持精确域名、通配符 *.domain 与外部 domain-set)       │
└──────────────────────────┬─────────────────────────────┘
                           │
       ┌───────────────────┼───────────────────┐───────────────────┐
       │ (命中)            │ (命中)            │ (命中)            │ (未匹配任何 Host 项)
       ▼                   ▼                   ▼                   ▼
┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────────────────────────┐
│ 静态 IP 映射 │    │ 域名别名     │    │ 定向 DNS     │    │ 第二阶段：回退至 [General] 的    │
│ (直接指定 IP)│    │ (domain:xxx) │    │ 上游分流     │    │ dns-server 全局解析              │
└──────┬───────┘    └──────┬───────┘    └──────┬───────┘    │ (未配置时默认使用 system)        │
       │                   │                   │            └─────────────────┬────────────────┘
       │                   │                   │                              │
       ▼                   ▼                   ▼                              ▼
  返回预设 IP         递归解析目标域名     向指定上游解析器查询       向全局 dns-server 查询
       │                   │                   │                              │
       └───────────────────┴───────────────────┴──────────────────────────────┘
                                           │
                                           ▼
                                     完成 DNS 解析

域名解析按以下顺序处理：

第一阶段：[Host] 优先匹配 域名解析请求优先进入 [Host] 映射表匹配，支持精确域名、通配符模式（*.domain）以及外部域名集（domain-set）。匹配命中时按以下类型分别处理：
- 静态 IP 映射：直接返回配置的 IPv4/IPv6 地址，不进行网络查询。
- 域名别名（Domain Alias）：通过 domain:target_domain 格式将请求指向目标域名，递归检索目标域名的解析结果作为当前解析结果。
- 定向 DNS 上游分流（Per-Domain DNS Upstream）：通过 server:upstream_url[#options] 为特定域名指定专属域名解析器；支持通过 #outbound 绑定特定的代理服务器出口，或通过 #route 遵循分流策略进行路由分发。
第二阶段：[General] 的 dns-server 全局解析 若待解析域名未命中 [Host] 中的任何映射规则，系统由全局 [General] 的 dns-server 发起网络解析（未显式配置时自动采用默认的 system）。
自上而下的命中机制 在 [Host] 内部存在多条规则时，系统遵循自上而下的声明顺序匹配，优先命中靠前的配置项。

语法声明

[Host] 配置行根据目标类型的不同，提供三种声明语法：

ini

# 1. 静态 IP 映射格式
pattern = ip_address[, ip_address...]

# 2. 域名别名格式
pattern = domain:target_domain

# 3. 定向 DNS 上游分流格式
pattern = server:upstream_url[#options]

语法要素说明

pattern：域名匹配模式，支持精确域名、通配符模式以及外部域名集（Domain Set）。
ip_address：合法的标准 IPv4 或 IPv6 地址。支持配置多个 IP 地址，地址之间以英文逗号分隔。
domain:target_domain：域名别名前缀为 domain:，其后紧接目标规范域名。
server:upstream_url：上游分流前缀为 server:，其后紧接上游域名解析器地址（支持常规 UDP/TCP、DoT、DoQ 及 DoH 等格式）。
#options：附加在上游地址末尾的 URL 片段参数，用于控制 DNS 解析请求的传输策略与出口网络路径。

参数详解

域名匹配模式

精确域名（格式如 example.com）仅严格匹配该域名本身，不包含下级子域名。
通配符域名（格式如 *.example.com）匹配该域名的所有下级子域名（如 api.example.com、dev.sub.example.com）。
外部域名集（格式如 domain-set:resource_url）引用外部域名列表资源，resource_url 支持本地文件路径或 HTTP/HTTPS 远程链接。集合内以 . 开头的条目按后缀模式匹配，其余按精确域名匹配。与 [Rule] 中的 DOMAIN-SET 共享缓存与自动刷新数据。

上游分流选项

在上游分流地址末尾以 # 开头附加控制参数。当存在多个参数时，使用 & 或 ; 连接：

outbound（策略名称字符串，未设置）显式指定发送该 DNS 解析请求的代理服务器或调度组名称（例如 #outbound=DIRECT 或 #outbound=ProxyNode）。优先级高于 route。
route（布尔值或独立标志，默认值 false）当未指定 outbound 时，设置为 true（或仅书写 #route）将指示系统按照分流策略（[Rule]）与代理路由链路自动匹配转发该 DNS 解析请求。

默认传输行为

若未配置 #outbound 与 #route，系统默认通过物理直连通道向该上游发送解析请求。对于系统默认解析器（system），不支持指定 outbound 或 route。

循环引用检测

系统加载域名别名（domain:target_domain）时检测循环引用。若存在直接或间接的闭环依赖，配置解析失败并报错。

配置示例

基础配置

ini

[Proxy]
InternalProxy = socks, 10.8.0.1, 1080
GlobalProxy = socks, 198.51.100.1, 1080

[Host]
# 1. 静态 IP 映射
router.local = 192.168.1.1
dev.internal.net = 10.0.0.10, 10.0.0.11, fd00::1

# 2. 域名别名
stage.example.com = domain:example.com

# 3. 指定上游解析器与出口服务器
*.internal.example = server:10.0.0.53#outbound=InternalProxy

# 4. 指定 DoH 解析器并遵循分流策略
*.wiki.org = server:https://1.1.1.1/dns-query#route

# 5. 外部域名集指定上游解析器与出口服务器
domain-set:./lists/domains.list = server:tls://8.8.8.8#outbound=GlobalProxy

DNS 脚本

script:name 引用 [Script] 中 type=dns 的脚本；缺失引用或引用其他脚本类型时配置校验失败。

ini

[Script]
resolver = type=dns, script-path=./resolver.js

[Host]
*.example.com = script:resolver

脚本通过 $domain 获取待查询域名，并使用 $done 完成解析：

javascript

$done({ addresses: ["192.0.2.1", "2001:db8::1"], ttl: 60 });

支持以下四种互斥结果：address（单个 IP）、addresses（IP 数组）、server（单个 DNS 服务器 IP）和 servers（DNS 服务器 IP 数组）。服务器使用 UDP 53 端口，复用现有 DNS 连接器。IP 地址按请求类型筛选，没有对应地址族时返回空结果。

地址结果仅在显式指定正整数 ttl（秒）时缓存；未指定或为 0 时不缓存。地址缓存过期后同步执行脚本。服务器结果每次执行脚本后按服务器列表隔离上游缓存；服务器切换不会复用上一列表的解析结果。脚本资源更新及配置重载清空 DNS 缓存。

$done({}) 回落普通 DNS。执行失败、未加载资源、非法结果或空地址/服务器数组记录错误或告警后回落普通 DNS。Bootstrap 引导解析和脚本发起的 HTTP 子请求跳过 DNS 脚本，保留静态 Host 映射、域名别名和定向上游。

[Host] 本地映射与定向 DNS 分流 ​

基本原理与分流流程 ​

语法声明 ​

语法要素说明 ​

参数详解 ​

域名匹配模式 ​

上游分流选项 ​

默认传输行为 ​

循环引用检测 ​

配置示例 ​

基础配置 ​

DNS 脚本 ​