ingest | mihomo（Clash Meta 内核）官方资料入库（2 摘编 + 2 wiki 页面 + 导航/登记）

2026-08-07 14:28:43 +08:00
parent dbeb66e312
commit d3b5af3415
10 changed files with 775 additions and 1 deletions
@@ -0,0 +1,120 @@
+---
+title: "mihomo（Clash Meta 内核）架构与核心概念摘编"
+source: "MetaCubeX/mihomo 官方仓库 README（https://github.com/MetaCubeX/mihomo，默认分支 Meta）+ 官方文档 wiki.metacubex.one（虚空终端 Docs）"
+source_date: 2026-08-07
+extracted_date: 2026-08-07
+type: source-derivative
+tags:
+  - "mihomo"
+  - "Clash"
+  - "代理"
+  - "网络工具"
+  - "DNS"
+  - "TUN"
+confidence: high
+contested: false
+evidence_boundary: "抓取时间 2026-08-07。依据：① GitHub MetaCubeX/mihomo Meta 分支 README.md（raw.githubusercontent.com 抓取）；② 官方文档 wiki.metacubex.one 的 简介/全局配置/通用字段/代理组/路由规则/DNS/代理集合/规则集合 章节；③ Alpha 分支 docs/config.yaml 全量示例（100,853 字符）。版本特性以文档写作时为基准，新版本可能新增或废弃字段；配置示例中的服务器地址、密码、密钥均为占位符，不可直接使用。文中\"原神\"指原版 Clash（Dreamacro/clash，已归档），\"虚空终端\"为 mihomo 的中文社区名。"
+---
+
+# 来源说明
+
+本文件是 mihomo（Clash Meta 内核）的架构与核心概念中文结构化摘编，内容综合官方仓库 README 与官方文档。配置编写细节见同目录《官方文档-配置编写-摘编.md》。
+
+## 证据分级
+
+- **官方事实**：README、官方文档、官方配置示例中的功能描述与字段定义。
+- **可复核机制**：DNS 防污染、fake-ip、规则路由、健康检查等可实际验证的机制。
+- **时效性提示**：项目迭代快，部分字段（如已弃用的 `sniffing`、`port-whitelist`、组内 `interface-name`/`routing-mark`、全局 `client-fingerprint`、`fallback-filter.geosite`）在文档中已标记废弃，编写新配置时应使用新写法。
+
+# 1. 项目定位
+
+- **mihomo**（曾用名 Clash Meta）是原 Dreamacro/clash（"原神"）的二次开发代理内核，Go 语言实现，默认分支 `Meta`（稳定），`Alpha`（开发）分支承载最新特性。
+- 功能上**兼容原版 Clash 全部特性**，并吸收 sing-box、v2ray-core 等项目的实现（见 README Credits）。
+- 许可 **GPL-3.0**；附加条款：任何与 MetaCubeX 无关的下游项目不得在名称中使用 "mihomo" 一词。
+- 配套 Dashboard：**metacubexd**（https://github.com/MetaCubeX/metacubexd）。
+- 官方文档（中文）：https://wiki.metacubex.one/ ；配置示例：`docs/config.yaml`（Alpha 分支）。
+- 构建：Go 1.20+；`go build`（可选 `-tags with_gvisor` 启用 gvisor tun 栈）；国内网络可设 `GOPROXY=https://goproxy.io,direct`。
+
+# 2. 功能特性（官方 README）
+
+1. 本地 HTTP/HTTPS/SOCKS 代理服务器，支持认证。
+2. 协议支持：VMess、VLESS、Shadowsocks、Trojan、Snell、TUIC、Hysteria 等。
+3. 内置 DNS 服务器，目标是最小化 DNS 污染攻击影响，支持 DoH/DoT 上游与 fake-ip。
+4. 基于域名、GEOIP、IPCIDR 或进程的规则路由，将数据包转发到不同节点。
+5. 远程策略组：自动 fallback、负载均衡或基于延迟自动选择节点。
+6. 远程提供者（proxy-providers / rule-providers）：远程获取节点列表与规则，而非硬编码在配置中。
+7. Netfilter TCP 重定向（iptables），可部署在网关/路由器。
+8. 完整 HTTP RESTful API 控制器。
+
+# 3. 分层架构与流量路径
+
+```
+应用 → 本地监听入口（mixed-port/socks/tun/redir/tproxy/自定义 listeners）
+     → DNS 解析（内置 DNS：fake-ip 或 redir-host）
+     → 规则匹配（rules 自上而下，首条命中生效）
+     → 出口（proxy-groups 或 proxies；DIRECT/REJECT/COMPATIBLE 内置出站）
+     → 节点 → 目标服务器
+```
+
+- **入口（inbound）**：mixed-port（HTTP+SOCKS 混合）、port（HTTP）、socks-port、tun、redir-port、tproxy-port，以及 `listeners` 自定义入站（hysteria2、tuic、tun、ss/vmess 入口等，传入流量按 `mode` 匹配处理）。`tunnels` 提供端口转发（本地端口→目标，经指定 proxy）。
+- **运行模式 mode**：`rule`（规则匹配，默认）、`global`（全局走 GLOBAL 策略组）、`direct`（全局直连）。
+- **内置出站**：`DIRECT`（直连）、`REJECT`（拒绝）、`COMPATIBLE`/`PASS`（兼容/放行）、`GLOBAL`（全局组）。代理组 `empty-fallback` 默认回退 `COMPATIBLE`。
+- **API 层**：`external-controller`（RESTful API，可配 `secret`、TLS、Unix socket、Windows namedpipe、CORS）；`external-ui` 挂载 Web 面板，访问路径为 `API 地址/ui`；可在外置端口开启 DoH 服务器（`external-doh-server`）。
+
+# 4. DNS 体系（防污染核心）
+
+## 4.1 两种增强模式
+
+- **fake-ip**（推荐）：DNS 返回 fake-ip 池（默认 `198.18.0.1/16`）中的虚拟 IP，mihomo 内部维护域名→fake-ip 映射；实际连接时按域名规则转发。优点：客户端不接触真实解析结果，规避 DNS 污染；配合 TUN 时所有流量可被内核接管。`store-fake-ip: true` 可持久化映射，重启后复用。
+- **redir-host**：返回真实 IP，行为与传统代理一致。
+
+## 4.2 关键字段
+
+- `nameserver`：默认解析服务器（一般用国内/本地 DNS，如 114.114.114.114、DoH 阿里/腾讯）。
+- `fallback`：后备服务器（一般用境外可信 DNS，如 tls://8.8.8.8）；配合 `fallback-filter` 判断 nameserver 返回的 IP 是否为 CN 以外（被视为污染）再改用 fallback 结果。
+- `nameserver-policy`：按域名（支持 `+.domain`、geosite、rule-set 键）指定解析服务器，优先级高于 nameserver/fallback。
+- `default-nameserver`：仅用于解析其他 DNS 服务器域名，必须为纯 IP 或加密 DNS，防止 DNS 服务器自身域名解析死循环。
+- `proxy-server-nameserver`：专门解析代理节点域名的 DNS（防止"鸡蛋问题"——节点域名需要代理才能解析时）。
+- `direct-nameserver`：direct 出口专用解析服务器。
+- `enhanced-mode: fake-ip|redir-host`；`fake-ip-range`；`fake-ip-filter`（不回发 fake-ip 的域名，如 `*.lan`、局域网设备、内网服务）；`fake-ip-filter-mode`（blacklist 默认/whitelist/rule）。
+- `listen`：监听 UDP/TCP 53 可作局域网 DNS 服务器；`ipv6: false` 时返回 AAAA 空结果。
+- `respect-rules`：DNS 上游连接是否遵守路由规则（需配置 proxy-server-nameserver；不建议与 prefer-h3 同用）。
+- 附加参数（`#` 连接）：`8.8.8.8/dns-query#proxy`（经指定代理/策略组连接）、`#RULES`（遵守路由规则）、`#h3=true`（强制 DoH over HTTP/3）、`#ecs=1.1.1.1/24`（指定 EDNS Client Subnet）、`skip-cert-verify`、`disable-qtype-65`（屏蔽 HTTPS/TYPE65 解析）等。
+
+## 4.3 防污染工作流（fake-ip 典型）
+
+1. 客户端请求域名 → mihomo 用 nameserver（国内）解析，或直接回 fake-ip；
+2. 若解析出境外 IP（fallback-filter geoip 判断非 CN）→ 改用 fallback（境外可信 DNS）结果；
+3. 实际建连时按规则：命中代理规则的域名走节点，命中国内规则的走 DIRECT（用 nameserver 结果）。
+
+# 5. TUN 与透明代理
+
+- `tun.enable: true` 创建虚拟网卡接管系统流量；`stack: system|gvisor|mixed`（gvisor 需 `with_gvisor` 编译标签；mixed 默认 tcp 走 system、udp 走 gvisor）。
+- `dns-hijack`：劫持 `0.0.0.0:53` 的 DNS 请求。
+- `auto-route`：自动配置路由表（把默认流量导入 tun）；`auto-redirect`（Linux）：自动配置 iptables 重定向 TCP，路由器场景可与 auto-route 组合。
+- `strict-route`：所有连接强制走 tun 防泄漏（本机其他设备将不可访问）。
+- 高级过滤（Linux/Android 部分需 auto-route）：include/exclude-interface、uid、mac-address、Android 用户/应用包名；`route-address` 自定义路由段；`mtu`、`gso` 等。
+- iptables 透明代理：`tproxy-port: 9898` + `iptables: {enable: true, inbound-interface: eth0}`。
+- `listeners` 中的 tun 类型可多实例配置（高级用法）。
+
+# 6. 流量嗅探（sniffer）
+
+- 对无域名流量（TUN/Redir/TProxy 且 DNS 为 redir-host，或纯 IP 流量）嗅探 TLS/HTTP/QUIC 以还原域名，从而走域名规则。
+- `override-destination`：是否用嗅探结果作为实际访问目标。
+- `force-domain`（如 `+.v2ex.com`）强制嗅探；`skip-*` 跳过；`sniff` 配置各协议端口（TLS/QUIC 默认 443，HTTP 默认 80）。
+- 已废弃写法：`sniffing`、`port-whitelist`（被 `sniffer.sniff` 取代）。
+
+# 7. 其他关键能力
+
+- **Geo 数据**：GEOIP/GEOSITE/ASN 数据库，`geox-url` 自定义下载地址（meta-rules-dat release），`geo-auto-update` + `geo-update-interval` 自动更新；`geodata-loader` 有内存友好模式。
+- **订阅加密**：proxy-providers 支持 age 加密（`age-secret-key`，age-encryption.org/v1 armor 格式）；命令行工具 `mihomo age keygen/convert/decrypt/encrypt`；`mihomo generate ech-keypair` 生成 ECH 密钥，`mihomo convert-ruleset` 转换 mrs 规则集。
+- **多路复用**：smux（sing-mux，协议 smux/yamux/h2mux）、TCP Brutal 拥塞控制（brutal-opts）、gRPC 多路复用。
+- **性能**：`tcp-concurrent`（并发连接所有解析 IP 取最快）、`unified-delay`（统一延迟计算）、TCP Fast Open（tfo）、MPTCP（mptcp）、`keep-alive` 调优。
+- **出站控制**：`interface-name`（绑定网卡）、`routing-mark`（fwmark，Linux）、`dialer-proxy`（节点经另一代理建立连接，可链式）。
+- **调试**：API 提供 debug 接口；日志级别 silent/error/warning/info/debug。
+
+# 8. 与周边生态的关系
+
+- 订阅/面板：metacubexd（官方面板）、Clash Verge Rev、Clash Meta for Android（CMFA）等客户端内嵌 mihomo 内核。
+- 规则集数据源：MetaCubeX/meta-rules-dat（geoip.dat/geosite.dat/mmdb/mrs 包）。
+- 上游/参考：Dreamacro/clash、SagerNet/sing-box、go-shadowsocks2、v2ray-core、wireguard-go。
@@ -0,0 +1,376 @@
+---
+title: "mihomo 配置编写精要摘编（config.yaml 字段与模板）"
+source: "MetaCubeX/mihomo Alpha 分支 docs/config.yaml 全量示例 + 官方文档 wiki.metacubex.one（全局配置/通用字段/代理组/路由规则/DNS/代理集合/规则集合）"
+source_date: 2026-08-07
+extracted_date: 2026-08-07
+type: source-derivative
+tags:
+  - "mihomo"
+  - "Clash"
+  - "config.yaml"
+  - "代理配置"
+  - "YAML"
+confidence: high
+contested: false
+evidence_boundary: "抓取时间 2026-08-07。依据官方 docs/config.yaml（Alpha 分支，100,853 字符，含全部注释）与官方文档各配置章节。字段以官方示例注释为权威；示例中的 server/uuid/password/密钥均为占位符，复制使用时必须替换。部分字段随版本演进（文档已标废弃项见正文），新配置优先采用新写法。文中 YAML 片段为演示模板，未在真实 mihomo 实例上运行验证。"
+---
+
+# 来源说明
+
+本文件是 mihomo `config.yaml` 配置编写的中文结构化精要，按"全局 → 节点 → 代理组 → 规则 → 提供者 → DNS"组织，附最小可用模板与常见坑。概念与架构见同目录《官方文档-架构与核心概念-摘编.md》。
+
+## 证据分级
+
+- **字段定义**：来自官方文档与官方示例注释，可直接作为编写依据。
+- **模板示例**：按官方示例整理的最小组合，需按实际节点/需求替换占位符。
+- **注意事项**：含官方文档标注的废弃项与社区常见误区，编写新配置时避免。
+
+# 1. 全局配置（通用字段）
+
+```yaml
+mixed-port: 7890            # HTTP+SOCKS5 混合入口端口（也可分别用 port/socks-port）
+# redir-port / tproxy-port  # Linux 透明代理
+allow-lan: false            # 允许局域网设备使用（true 时可用 bind-address 限定）
+mode: rule                  # rule | global | direct
+log-level: info             # silent/error/warning/info/debug
+ipv6: true
+external-controller: 127.0.0.1:9090   # RESTful API；0.0.0.0 则对外
+secret: ""                  # API 访问密钥（Authorization: Bearer）
+external-ui: ./ui           # Web 面板目录（访问 /ui）
+profile:
+  store-selected: true      # 记住 API 上对 select 组的选择
+  store-fake-ip: true       # 持久化 fake-ip 映射
+unified-delay: true
+tcp-concurrent: true
+find-process-mode: strict   # always/strict/off（路由器建议 off）
+geox-url:                   # 自定义 geo 数据下载地址（GEOIP/GEOSITE/mmdb/asn）
+  geoip: "https://fastly.jsdelivr.net/gh/MetaCubeX/meta-rules-dat@release/geoip.dat"
+  geosite: "https://fastly.jsdelivr.net/gh/MetaCubeX/meta-rules-dat@release/geosite.dat"
+  mmdb: "https://fastly.jsdelivr.net/gh/MetaCubeX/meta-rules-dat@release/geoip.metadb"
+```
+
+- 认证：`authentication: ["user:pass"]` + `skip-auth-prefixes`（跳过验证的 IP 段）；`lan-allowed-ips`/`lan-disallowed-ips` 控制 allow-lan 时允许/禁止的网段（黑名单优先）。
+- hosts：类似 /etc/hosts，支持单 IP 或别名。
+- 已废弃：全局 `client-fingerprint`（改在节点内配置）、组内 `interface-name`/`routing-mark`（改在节点内配置）。
+
+# 2. 节点（proxies）
+
+## 2.1 通用字段
+
+| 字段 | 说明 |
+|---|---|
+| name | 必须，唯一 |
+| type | 必须：ss / vmess / vless / trojan / snell / tuic / hysteria2 / wireguard / direct / dns / reject / compatible(pass) / gost-relay 等 |
+| server / port | 服务器地址与端口（必须） |
+| udp | 是否允许 UDP 过代理，默认 false（tuic/hysteria2/direct/dns 默认开） |
+| ip-version | dual/ipv4/ipv6/ipv4-prefer/ipv6-prefer，默认 dual |
+| tfo / mptcp | TCP Fast Open / 多路径 TCP |
+| dialer-proxy | 经指定代理/组建立连接（链式代理） |
+| interface-name / routing-mark | 绑定网卡 / fwmark（Linux） |
+| smux | sing-mux 多路复用：enabled、protocol(smux/yamux/h2mux)、max-connections/min-streams/max-streams（互斥）、padding、brutal-opts（TCP Brutal 上下行 Mbps） |
+| client-fingerprint | TLS 指纹：chrome/firefox/safari/ios/random（TLS 传输的 vmess/vless/trojan 等） |
+| skip-cert-verify / name-cert-verify | 跳过证书校验 / 仅改 DNSName 校验目标（不改 SNI） |
+| sni / servername | 覆盖 SNI（优先级高于 ws host） |
+
+## 2.2 常用节点写法
+
+```yaml
+proxies:
+  - name: "ss-1"                      # Shadowsocks
+    type: ss
+    server: example.com
+    port: 443
+    cipher: chacha20-ietf-poly1305    # 也支持 aes-*-gcm、2022-blake3-* 等
+    password: "your-password"
+    udp: true
+    # plugin: obfs / v2ray-plugin / shadow-tls / restls / kcptun（plugin-opts 见官方示例）
+
+  - name: "vmess-ws"                  # VMess + WebSocket + TLS
+    type: vmess
+    server: example.com
+    port: 443
+    uuid: "uuid"
+    alterId: 0
+    cipher: auto
+    tls: true
+    network: ws
+    ws-opts:
+      path: "/path"
+      headers: { Host: example.com }
+
+  - name: "vless-reality"             # VLESS + REALITY（推荐自建）
+    type: vless
+    server: example.com
+    port: 443
+    uuid: "uuid"
+    network: tcp
+    tls: true
+    udp: true
+    flow: xtls-rprx-vision
+    servername: www.microsoft.com     # REALITY 借用域名
+    client-fingerprint: chrome        # 必填，不能为空
+    reality-opts:
+      public-key: xxx
+      short-id: xxx
+      # support-x25519mlkem768: false
+
+  - name: "trojan-1"                  # Trojan
+    type: trojan
+    server: example.com
+    port: 443
+    password: "your-password"
+    sni: example.com
+    udp: true
+
+  - name: "hy2-1"                     # Hysteria2（HTTP/3 + QUIC，UDP 默认开）
+    type: hysteria2
+    server: example.com
+    port: 443
+    password: "your-password"
+    up: "50 Mbps"                     # 客户端声明带宽，留空用 BBR 流控
+    down: "200 Mbps"
+    # obfs: salamander; obfs-password: xxx
+```
+
+- 其他类型要点：snell 需 `psk`（可选 obfs-opts: http/tls/shadow-tls/restls/jls）；wireguard 需 `private-key`、`ip`、`dns`、`public-key`、`mtu`；trojan 支持 grpc/ws 传输、reality-opts、shadow-tls/restls/jls-opts（需 tls: true）；`direct` 可配 interface-name 作"指定网卡直连"。
+
+# 3. 代理组（proxy-groups）
+
+```yaml
+proxy-groups:
+  - name: "PROXY"                     # 手动选择（select）
+    type: select
+    proxies: [DIRECT, auto, 节点名...]   # 可引用其他组和内置 DIRECT/REJECT
+    # use: [provider1]                # 引用代理集合
+    # default-selected: auto          # 默认选中项
+    # filter: "(?i)港|hk|hongkong"    # 正则筛选 use 引入的节点
+    # exclude-filter: "美|日"
+    # exclude-type: "Shadowsocks|Http"
+    # empty-fallback: COMPATIBLE      # 组为空时的回退 proxy
+
+  - name: "auto"                      # 按延迟自动选择（url-test）
+    type: url-test
+    proxies: [...]
+    url: "https://www.gstatic.com/generate_204"
+    interval: 300                     # 健康检查间隔（秒），0 关闭定时测试
+    tolerance: 150                    # 延迟容差（毫秒）
+    lazy: true                        # 未选中时不测试
+    expected-status: 204              # 期望 HTTP 状态码（支持 200/302、400-503 写法）
+
+  - name: "fallback-1"                # 按健康检查顺序优先（fallback）
+    type: fallback
+    proxies: [...]
+    url: "https://cp.cloudflare.com/generate_204"
+    interval: 300
+
+  - name: "lb"                        # 负载均衡
+    type: load-balance
+    proxies: [...]
+    url: "https://cp.cloudflare.com/generate_204"
+    interval: 300
+    strategy: round-robin             # 可选 consistent-hashing / sticky-sessions
+```
+
+- 健康检查要点：`url` 只检查 `proxies` 字段（不检查 `use` 引入的集合节点，集合节点需在 provider 内配置 health-check）；`lazy: true`（默认）避免后台持续测试；`timeout` 毫秒；`max-failed-times` 失败次数超限触发强制检查（默认 5）。
+- `include-all` / `include-all-proxies` / `include-all-providers`：自动引入全部节点/集合（按名称排序，不包含策略组）。
+- `hidden: true` / `icon: xxx`：供面板隐藏组或显示图标（需前端适配）。
+
+# 4. 规则（rules）
+
+- **匹配顺序**：自上而下，第一条命中生效；规则不命中继续向下，最后用 `MATCH` 兜底。
+- 常用规则类型：
+
+| 类型 | 说明 |
+|---|---|
+| DOMAIN / DOMAIN-SUFFIX / DOMAIN-KEYWORD | 完整域名 / 后缀（`google.com` 匹配 `www.google.com` 但不匹配 `content-google.com`）/ 关键字 |
+| DOMAIN-WILDCARD / DOMAIN-REGEX | 通配符（`*` `?`）/ 正则 |
+| GEOSITE, 分类名 | 匹配 geosite 域名集合（如 `GEOSITE,youtube,PROXY`） |
+| GEOIP, 国家码 | IP 归属国（`GEOIP,CN,DIRECT`）；`GEOIP,CN,DIRECT,no-resolve` 跳过 DNS 解析 |
+| IP-CIDR / IP-CIDR6 / IP-SUFFIX / IP-ASN | IP 段 / IP 段别名 / IP 后缀 / ASN 号 |
+| SRC-GEOIP / SRC-IP-ASN / SRC-IP-CIDR / SRC-IP-SUFFIX | 匹配来源 IP |
+| DST-PORT / SRC-PORT | 目标/来源端口 |
+| IN-PORT / IN-TYPE / IN-USER / IN-NAME | 匹配入站端口 / 类型 / 用户名 / 名称 |
+| PROCESS-PATH(-WILDCARD/-REGEX) / PROCESS-NAME(-WILDCARD/-REGEX) | 进程路径/名称匹配（Android 可匹配包名） |
+| UID / NETWORK / DSCP | Linux UID / tcp|udp / DSCP 标记（仅 tproxy udp 入站） |
+| RULE-SET, 名称 | 引用规则集（需 rule-providers） |
+| AND / OR / NOT | 逻辑组合，如 `AND,((DOMAIN,baidu.com),(NETWORK,UDP)),DIRECT`（注意括号） |
+| SUB-RULE | 匹配到子规则（`SUB-RULE,(NETWORK,tcp),sub-rule-name`） |
+| MATCH | 匹配一切，兜底 |
+
+```yaml
+rules:
+  - RULE-SET,reject,REJECT          # 广告拦截
+  - RULE-SET,proxy,PROXY            # 代理规则集（由 rule-providers 提供）
+  - GEOSITE,cn,DIRECT               # 国内域名直连
+  - GEOIP,CN,DIRECT,no-resolve
+  - MATCH,PROXY
+```
+
+- 附加参数：`no-resolve`（目标 IP 类规则跳过 DNS 解析，避免触发解析污染；若前面已解析则仍会匹配）、`src`（把目标 IP 匹配转为来源 IP 匹配）。
+
+# 5. 提供者（proxy-providers / rule-providers）
+
+```yaml
+proxy-providers:
+  airport:                          # 机场订阅
+    type: http
+    url: "https://example.com/sub"  # 支持 mihomo/Clash 格式或 v2ray 分享链接
+    interval: 86400                 # 更新间隔（秒）
+    path: ./providers/airport.yaml  # 默认限制在 HomeDir 内（SAFE_PATHS 可扩展）
+    proxy: DIRECT                   # 经哪个代理下载订阅（防订阅域名被墙）
+    health-check:
+      enable: true
+      url: "https://www.gstatic.com/generate_204"
+      interval: 300
+    override:                       # 覆写加载的节点
+      udp: true
+      # skip-cert-verify: true
+      # additional-prefix: "[机场] "
+      # proxy-name: [{pattern: "IPLC-(.*?)倍", target: "iplc x $1"}]
+    # override-expr:                # yq v4 风格表达式（高级）
+    #   - '.name = "[prov] " + .name'
+
+rule-providers:
+  reject:
+    type: http
+    behavior: domain                # domain / ipcidr / classical
+    format: yaml                    # yaml / text / mrs
+    url: "https://example.com/reject.yaml"
+    interval: 86400
+    path: ./rules/reject.yaml
+  # type: inline + payload 可内联定义；type: file 读本地文件
+```
+
+- provider 类型：`http`（远程）/ `file`（本地）/ `inline`（内联 payload；http/file 解析失败时 payload 可作备用）。
+- `size-limit` 限制下载大小（字节）；`header` 自定义请求头（UA、Authorization）；`age-secret-key` 支持 age 加密订阅。
+- rule-provider `behavior` 必须与文件内容格式一致：`domain`（每行一个域名）/ `ipcidr`（每行一个 CIDR）/ `classical`（完整 Clash 规则行）。`mrs` 格式二进制更省内存，`mihomo convert-ruleset` 可转换。
+- `path-in-bundle`：从 BundleMRS.7z（meta-rules-dat）按路径加载规则集。
+
+# 6. DNS 最小推荐配置（fake-ip + 防污染）
+
+```yaml
+dns:
+  enable: true
+  enhanced-mode: fake-ip
+  fake-ip-range: 198.18.0.1/16
+  fake-ip-filter:
+    - "*.lan"
+    - "+.local"
+    - "localhost.ptlogin2.qq.com"
+  default-nameserver:
+    - 223.5.5.5
+    - 119.29.29.29
+  nameserver:
+    - https://doh.pub/dns-query
+    - https://dns.alidns.com/dns-query
+  fallback:
+    - tls://8.8.8.8
+    - tls://1.1.1.1
+  fallback-filter:
+    geoip: true
+    geoip-code: CN
+    ipcidr:
+      - 240.0.0.0/4
+  nameserver-policy:
+    "geosite:cn,private,apple":
+      - https://doh.pub/dns-query
+      - https://dns.alidns.com/dns-query
+```
+
+- 开启 `listen: 0.0.0.0:53` 可给局域网设备提供 DNS。
+- 国内域名走 nameserver（精准、快），境外域名经 fallback-filter 判定后走 fallback（可信、防污染）。
+- 节点为域名时配置 `proxy-server-nameserver`（如 `https://doh.pub/dns-query`）避免节点域名解析污染。
+
+# 7. 最小可用配置模板（客户端，含 TUN）
+
+```yaml
+mixed-port: 7890
+allow-lan: false
+mode: rule
+log-level: info
+ipv6: true
+external-controller: 127.0.0.1:9090
+secret: "your-api-secret"
+profile:
+  store-selected: true
+  store-fake-ip: true
+
+dns:
+  enable: true
+  enhanced-mode: fake-ip
+  fake-ip-range: 198.18.0.1/16
+  default-nameserver: [223.5.5.5, 119.29.29.29]
+  nameserver:
+    - https://doh.pub/dns-query
+    - https://dns.alidns.com/dns-query
+  fallback:
+    - tls://8.8.8.8
+    - tls://1.1.1.1
+  fallback-filter:
+    geoip: true
+    geoip-code: CN
+
+tun:
+  enable: false          # Windows/macOS 客户端可开 true；stack: mixed
+  stack: mixed
+  dns-hijack: ["0.0.0.0:53"]
+  auto-route: true
+  auto-detect-interface: true
+
+proxy-providers:        # 或直接写 proxies 节点
+  airport:
+    type: http
+    url: "https://你的订阅地址"
+    interval: 86400
+    health-check:
+      enable: true
+      url: "https://www.gstatic.com/generate_204"
+      interval: 300
+
+proxy-groups:
+  - name: "PROXY"
+    type: select
+    proxies: [auto, DIRECT]
+    use: [airport]
+    default-selected: auto
+  - name: "auto"
+    type: url-test
+    proxies: [DIRECT]
+    use: [airport]
+    url: "https://www.gstatic.com/generate_204"
+    interval: 300
+
+rule-providers:
+  reject:
+    type: http
+    behavior: domain
+    url: "https://cdn.jsdelivr.net/gh/MetaCubeX/meta-rules-dat@release/cnc/ads.yaml"  # 示例地址，按实际规则集替换
+    interval: 86400
+    path: ./rules/reject.yaml
+  proxy:
+    type: http
+    behavior: domain
+    url: "https://你的代理规则集地址"
+    interval: 86400
+    path: ./rules/proxy.yaml
+
+rules:
+  - RULE-SET,reject,REJECT
+  - RULE-SET,proxy,PROXY
+  - GEOSITE,cn,DIRECT
+  - GEOIP,CN,DIRECT,no-resolve
+  - MATCH,PROXY
+```
+
+# 8. 常见坑（写配置时逐条核对）
+
+1. **YAML 缩进/引号**：节点名、密码含特殊字符（`:` `#` 等）必须加引号；组名含特殊符号同理。
+2. **规则顺序**：`MATCH` 必须放最后；GEOIP,CN,DIRECT 前先放 RULE-SET 代理规则，避免国内 CDN/境外域名误直连或误代理。
+3. **fake-ip 与直连内网**：内网/局域网域名（`*.lan`、`*.local`、NAS、路由器管理页）必须进 `fake-ip-filter`，否则 TUN 模式下无法访问。
+4. **节点域名解析**：订阅节点为域名时，务必配置 `proxy-server-nameserver`，否则可能解析失败或走错 DNS。
+5. **健康检查与 UDP**：url-test/fallback 组只测 `proxies` 里的节点；需要 UDP 的协议（游戏、VoIP）确认节点 `udp: true` 且组未 `disable-udp`。
+6. **allow-lan 安全**：对外监听时配 `authentication` 或限制 `lan-allowed-ips`，API 别绑 0.0.0.0 且无 secret。
+7. **路径限制**：provider 的 path 默认只能在 HomeDir（启动 `-d` 指定），其他位置需 `SAFE_PATHS` 环境变量。
+8. **已废弃字段**：`sniffing`/`port-whitelist`（用 `sniffer.sniff`）、组内 `interface-name`/`routing-mark`（用节点内）、全局 `client-fingerprint`（用节点内）、`fallback-filter.geosite`（用 nameserver-policy）。
+9. **规则集 behavior 必须匹配**：domain 规则集配 `behavior: domain`，写错会加载失败。
+10. **验证方式**：`mihomo -t -f config.yaml` 测试配置；`mihomo -d .` 指定工作目录；API `GET /configs` 可查运行状态。