[General] 通用设置

本节用于配置客户端的全局基础运行参数、本地流量接管、DNS 解析机制、网络出口与直连探测。

字段详解

通用与基础参数

• log-level（枚举值，默认值 info） 系统日志输出级别，按详细程度递减：trace、debug、info、warn、error、off。
• proxy-model（枚举值，默认值 mixed） 系统网络接管与路由分配模式：mixed/0、only-tun/1、mixed-no-default/2、only-tun-no-default/3、only-tun-manual/4。详见下文代理接管模式。
• dns-server（域名解析器列表，逗号分隔，默认值 system） 全局默认上游域名解析器；未显式配置时默认使用 system。详细协议语法与 Bootstrap 引导规则见下文 DNS 机制。
• ipv6（布尔值，默认值 true） 全局 IPv6 解析开关；开启时常规 DNS 查询同时请求 AAAA 记录。

本地流量接管与接入

• tun-ipv6（auto 或布尔值，默认值 auto） TUN 虚拟网卡 IPv6 路由接管模式；auto 根据当前系统网络环境自动判定可用性。
• tun-included-routes（CIDR 列表，逗号分隔，默认值为空列表） 显式分配给 TUN 虚拟网卡接管的目标 IPv4/IPv6 路由网段。
• tun-excluded-routes（CIDR 列表，逗号分隔，默认值为空列表） 绕过 TUN 虚拟网卡、直接由物理网络接口发起的 IPv4/IPv6 路由网段。
• tun-icmp-echo-forwarding（布尔值，默认值 true） 控制非 Fake-IP 的 IPv4 ICMP Echo 报文转发至物理网络；关闭时由虚拟网卡协议栈本地响应。
• hijack-dns（地址列表，逗号分隔，默认值为空列表） 强制重定向至本地协议栈处理的目标 DNS 地址与端口（IP:port）；IPv6 地址需采用 [IP]:port 格式。
• always-real-ip（域名列表，逗号分隔，默认值为空列表） 绕过 Fake-IP 分配的域名过滤名单（Fake-IP Filter），命中域名强制向真实上游解析并返回物理 IP。
• dns-reject-behavior（枚举值，默认值 empty） TUN 接管的域名查询命中前置 REJECT 策略时的响应行为：empty、zero、blackhole。详见下文前置拒绝拦截。
• skip-proxy（主机列表，逗号分隔，默认值为空列表） 豁免代理接管的主机列表（支持域名、IP 或 CIDR），流量直接穿透至物理网络。
• force-http-hostname（主机名列表，逗号分隔，默认值为空列表） 强制进行 HTTP 应用层解析与解密审查的目标主机列表。
• skip-force-http-hostname（主机名列表，逗号分隔，默认值为空列表） 豁免强制 HTTP 处理的主机列表。

出口网络与直连设置

• tfo-behaviour（枚举值，默认值 auto） 全局 TFO 策略，适用于配置节点及订阅节点：auto 遵循节点 tfo 并保留系统黑洞检测；force-enabled 对已启用 TFO 的节点绕过 Apple 系统黑洞检测；force-disabled 禁用所有节点的 TFO。此项不会让 tfo=false 的节点自动发送早期数据，也不修改系统全局 sysctl。配置重载后对新建连接生效。

• interface-name（接口名称字符串，未设置） 全局默认物理出口网卡接口，用于直连流量的物理接口绑定。

• ip-preference（枚举值，未设置） 全局出口 IP 地址族偏好，控制直连与代理服务器建连时的优先地址族：dual、ipv4-only、ipv6-only、prefer-ipv4、prefer-ipv6。可在 [Proxy] 节单独覆盖。

连通性探测与管理控制

• proxy-test-url（HTTP/HTTPS URL，默认值 http://captive.apple.com） 代理节点连接与延迟测试的全局默认探测 URL。
• internet-test-url（HTTP/HTTPS URL，默认值 http://captive.apple.com） 直连（DIRECT）出站网络连通性健康探测 URL，用于检测底层物理互联网是否可达。
• test-timeout（非负整数，单位：秒，默认值 5） 代理服务连通性测试与健康检查的全局超时时限。健康检查优先使用该字段；未设置或设置为 0 时，使用环境变量 OUTBOUND_HEALTH_CHECK_TIMEOUT 的值。
• test-url-check-status（布尔值，默认值 false） 将 HTTP 4xx 和 5xx 响应视为测速失败。
• mmdb-url（HTTP/HTTPS URL，默认内置资源地址） GeoIP 离线数据库下载与同步更新地址。
• public-http-api-listen（IP:port，未设置） 公开 HTTP API 的独立监听地址与端口；未设置时关闭公开入口。IPv6 使用 [IP]:port 格式，端口 0 由系统分配，实际地址见启动日志。接口契约见运行时控制 API。
• public-http-api-key（可打印 ASCII 字符串，未设置） 公开 HTTP API 的独立密钥；非空时所有请求须携带 Authorization: Bearer <SECRET>。允许省略或设置为空，此时公开入口不要求鉴权。

警告： 缺失或为空的 public-http-api-key 会关闭公开入口的鉴权。能够访问监听地址的设备均可读取运行状态、调整策略并调用管理接口；绑定 0.0.0.0 或 [::] 时会向所有可达网络接口开放。需要访问控制时应设置非空密钥。

公开入口随激活配置加载、切换和重载更新。移除监听配置会关闭公开入口，更换密钥或监听地址会关闭旧入口的 SSE 会话。端口占用等监听失败仅记录错误，不阻断配置应用或内部 API；再次应用配置时重试。内部 API 始终独立监听 127.0.0.1，保留自己的随机端口和随机密钥，不受公开入口设置影响。

[General]
public-http-api-listen = 0.0.0.0:6171
public-http-api-key = <SECRET>

代理接管模式

proxy-model 决定客户端如何接管操作系统流量及路由表：

• mixed（别名 0） 同时启用 TUN 虚拟网卡与系统 HTTP/SOCKS 代理设置，应用全局默认路由接管策略。
• only-tun（别名 1） 仅启用 TUN 虚拟网卡接管，保持系统原生代理设置不变，应用全局默认路由接管策略。
• mixed-no-default（别名 2） 同时启用 TUN 虚拟网卡与系统代理设置，保持物理默认网关，仅定向接管特定网段。
• only-tun-no-default（别名 3） 仅启用 TUN 虚拟网卡接管，保持系统原生代理设置与物理默认网关，仅定向接管特定网段。
• only-tun-manual（别名 4） 仅启用 TUN 虚拟网卡接管，保持系统原生代理设置不变，完全由 tun-included-routes 自定义显式路由网段。

DNS 机制

DNS 流程分为入站请求接管与出站上游解析两个阶段：

入站请求接管

入站请求接管阶段捕获操作系统或应用程序发起的 DNS 查询，执行本地拦截或地址映射：

1. 系统接管与 DNS 劫持：
   • TUN 虚拟网卡接管操作系统 DNS 请求；通过 hijack-dns 配置指定的目标 DNS 物理地址与端口，强制重定向至本地协议栈处理。
2. 前置拒绝拦截：
   • 每次 DNS 查询均先对待解析域名执行带有 pre-matching 标志的 REJECT 策略匹配，再复用或分配 Fake-IP，或查询真实上游。已有和持久化恢复的 Fake-IP 映射不会绕过当前规则。
   • 命中前置拒绝策略时，依据 dns-reject-behavior 返回对应 DNS 响应：
     • empty：返回 NOERROR 响应码且 Answer 记录集为空。
     • zero：IPv4 A 查询返回 0.0.0.0；IPv6 AAAA 查询返回 ::。
     • blackhole：IPv4 A 查询返回传入 Fake-IP 地址段的末地址，默认网段下为 198.19.255.254；AAAA 返回空 Answer。报文到达 TUN 虚拟网卡后直接丢弃。
   • 处于 blackhole 模式时，TUN 虚拟网卡在网络层丢弃目标地址为黑洞 IP 的报文，TCP 协议不发送响应，UDP 协议不建立会话状态。
   • 普通 Fake-IP、zero 和 blackhole 返回的地址记录 TTL 为 1 秒；空 Answer 响应不包含地址记录及 TTL。
   • 拒绝响应不写入 Fake-IP 映射，DOMAIN-SET 更新后，下次查询按当前内容判断；普通映射保留用于反查和再次复用。
3. Fake-IP 地址分配与过滤名单：
   • 默认模式下为查询域名分配 Fake-IP 地址池中的虚拟 IP（默认 198.18.0.0/15 网段）。
   • 地址段末地址预留为黑洞，普通分配上界为末地址减一；持久化恢复仅加载普通分配范围内的映射。黑洞地址随传入 IP 段计算，始终位于该网段的接管路由内。
   • 过滤名单（Fake-IP Filter）：always-real-ip 中配置的域名绕过 Fake-IP 分配，透传至出站上游解析阶段获取真实物理 IP。

出站上游解析

出站上游解析阶段将未命中本地映射及需要真实 IP 的请求转发至外部上游解析器：

1. 上游解析器配置：
   • dns-server 定义全局默认的上游域名解析器列表，支持以逗号分隔配置多个常规或加密解析器。未显式配置时默认使用 system（当前操作系统物理网络接口分配的默认域名解析器）。
   • 支持的上游传输协议与格式规范：
     • 系统默认（system）：继承当前操作系统底层网络接口分配的域名解析器。
     • 标准 UDP（IP、IP:port、udp://IP[:port]）：UDP 协议解析，默认端口 53。
     • 标准 TCP（tcp://IP[:port]）：TCP 协议解析，默认端口 53。
     • DNS over TLS / DoT（tls://host[:port]）：通过 TLS 加密通道传输，默认端口 853。
     • DNS over QUIC / DoQ（quic://host[:port]）：基于 QUIC 协议传输，默认端口 853。
     • DNS over HTTPS / DoH（https://host/path）：DoH 传输，自动协商 HTTP/2 或 HTTP/3 协议。
     • HTTP/2 DoH（h2://host/path）：采用 HTTP/2 协议的 DoH 传输。
     • HTTP/3 DoH（h3://host/path）：采用 HTTP/3 协议（基于 QUIC）的 DoH 传输。
   • 在 iOS/macOS 上，system 使用正在使用的物理网络接口对应的系统 DNS，排除虚拟隧道与回环接口；网络环境变化后更新上游地址，无需在配置中写死当前 Wi-Fi 或蜂窝网络的 DNS 地址。
2. 业务域名解析优先级：
   • 在 dns-server 列表中，若同时包含加密上游（DoT、DoH、DoQ）与普通 UDP 解析器（或 system），系统优先使用加密上游发起查询。
3. Bootstrap 引导解析规则：
   • 当配置的加密上游采用域名形式（如 tls://dns.example.com 或 https://dns.example.com/dns-query）时，系统需先通过基础解析器（Bootstrap DNS）解析该域名对应的物理 IP。若加密上游直接配置物理 IP 则无需 Bootstrap 解析。
   • 配置 UDP 解析器：若 dns-server 列表中配置了任意普通 UDP 解析器，系统使用该配置的 UDP 解析器作为 Bootstrap 解析器。
   • 未配置 UDP 解析器：若 dns-server 列表中仅配置了域名形式的加密解析器，系统自动使用 system 作为 Bootstrap 解析器。
   • Bootstrap 职责：Bootstrap 解析器仅用于解析加密上游自身域名的物理 IP，不用于常规业务域名查询。

配置示例

基础配置

[General]
log-level = info
proxy-model = mixed
ipv6 = true
dns-server = 223.5.5.5, 119.29.29.29, https://dns.alidns.com/dns-query
dns-reject-behavior = blackhole
tun-ipv6 = auto
skip-proxy = 127.0.0.1, 192.168.0.0/16, 10.0.0.0/8, 172.16.0.0/12, localhost, *.local
# 节点连通性与延迟测试
proxy-test-url = http://cp.cloudflare.com/generate_204
# 直连网络连通性健康探测
internet-test-url = http://captive.apple.com
test-timeout = 5
test-url-check-status = false