Tun 模块

范围与目标

TUN 模式会捕获主机的三层流量，并将其送入代理管线，无需每个应用具备代理能力。相比 HTTP/SOCKS 监听器，TUN 最接近“系统级代理”行为，通常与策略路由和 DNS 控制联合使用。

本页遵循 clash-rs 的语义与配置键，以便后续 chimera_client 对齐更加直接。

当前项目状态

chimera_client（当前主线）在配置解析器中尚未暴露 tun 配置块。
下方 TUN 章节是与 clash-rs 对齐的目标形态和运维指引，不代表 chimera_client 中所有字段都已生效。
当前建议在 chimera_client 中使用基于 SOCKS/监听器的工作流，除非你正在验证开发中的 TUN 分支。

配置结构（与 Clash-rs 对齐）

tun:
  enable: true
  device-id: "dev://utun1989"
  route-all: true
  gateway: "198.18.0.1/24"
  gateway-v6: "fd00:fac::1/64"
  mtu: 1500
  so-mark: 3389
  route-table: 2468
  dns-hijack: true
  # dns-hijack:
  #   - 1.1.1.1:53
  #   - 8.8.8.8:53
  # routes:
  #   - 1.1.1.1/32
  #   - 2001:4860:4860::8888/128

关键字段与语义

键名	类型	默认值	注意事项
`enable`	`bool`	`false`	启用 TUN 运行时。
`device-id`	`string`	`utun1989`	支持 `dev://<name>`、`fd://<n>` 或纯名称（按设备名处理）。
`gateway`	`CIDR string`	`198.18.0.1/24`	分配给 TUN 接口的 IPv4 地址/前缀。
`gateway-v6`	`CIDR string`	未设置	双栈 TUN 的可选 IPv6 地址/前缀。
`route-all`	`bool`	`false`	将主机全部流量通过 TUN 路由。
`routes`	`list<CIDR>`	空	在 `route-all: false` 时使用，仅路由选定前缀。
`mtu`	`u16`	平台默认值	若未设置，运行时默认使用 `1500`（Windows 为 `65535`）。
`so-mark`	`u32`	未设置	Linux fwmark，用于防环路和策略路由集成。
`route-table`	`u32`	`2468`	TUN 全局路由路径使用的 Linux 策略路由表。
`dns-hijack`	`bool` 或 `list`	`false`	在 TUN 路径中启用 DNS 劫持行为。

按选项说明的行为（以 Clash-rs 为准）

本节会展开说明 clash-rs 中 TunConfig 的每个 tun 字段，并解释其实际影响。

`enable`

控制整个 TUN 流水线的启用 / 关闭。
false 表示运行时会忽略其他所有 tun 字段。

`device-id`

接口标识符与创建模式。
clash-rs 解析器接受的形式：
- dev://<name>：创建或使用具名 TUN 设备。
- 纯 <name>：按 dev://<name> 处理。
- fd://<n>：接管一个已经打开的文件描述符（高级嵌入 / systemd 风格）。
解析器接受的别名键：device-url、device。

`gateway`

分配给 TUN 网卡的 IPv4 CIDR，例如 198.18.0.1/24。
它同时定义本地 TUN IP 和用于路由决策的前缀。

`gateway-v6`

分配给 TUN 网卡的可选 IPv6 CIDR。
若省略，则 TUN 路径中的 IPv6 处理实际上会被禁用。

`route-all`

true：全隧道，安装默认路径风格的路由 / 规则。
false：分流，仅将 routes 中的前缀送入 TUN。
如果 route-all: true，则 routes 列表在运行时基本失去意义。

`routes`

用于分流模式（route-all: false）的 CIDR 列表。
典型用法：仅路由特定公共解析器、目标地区或服务网络。

`mtu`

TUN 接口 MTU 覆盖值。
不设置时使用运行时 / 平台默认值；遇到分片 / PMTU 问题时再显式设置。

`so-mark`

仅 Linux 使用，附加到出站数据包上的 fwmark。
与 ip rule / iptables / nftables 配合使用，以避免代理环路并集成自定义策略路由。

`route-table`

仅 Linux 使用的策略路由表索引，由 clash-rs 的 TUN 路由安装逻辑使用。
默认值为 2468；若你的系统已占用该表号，则应修改。

`dns-hijack`

false：不在 TUN 路径中重定向 DNS。
true：将 UDP/53 查询劫持到 Clash DNS 服务。
list：clash-rs 当前会把列表模式视为启用劫持行为（效果与 true 相同）。

Mihomo 差异说明（基于公开 Tun 文档）

与上面的 clash-rs 结构相比，以下项目在 mihomo 中未被记录为一等的 tun 键（同名或同形）：

带 fd://<n> 文件描述符形式的 device-id。
- Mihomo 文档暴露了 device，但没有记录基于 fd 的接管语法。
gateway / gateway-v6 这类显式接口地址分配字段。
- Mihomo 的 tun 文档更关注 route / rule 控制，没有暴露 clash-rs 风格的 gateway CIDR 键。
route-all + routes 这对精确键。
- Mihomo 使用 auto-route、route-address、route-exclude-address 这类控制项，而不是 clash-rs 的键形态。
route-table 的准确命名。
- Mihomo 暴露的是 iproute2-table-index / iproute2-rule-index；功能上接近，但键契约并不相同。

注意：clash-rs 中的 so-mark 与 mihomo 中的 routing-mark 在概念上相近（都是 Linux packet mark），因此这是命名 / 兼容性差异，而不是能力缺失。

Device-ID 格式

dev://utun1989 或 utun1989：创建/使用具名 TUN 设备。
dev://tun0：常见 Linux 写法。
fd://3：使用现有文件描述符，适用于由其他组件创建 TUN 的场景。

在 macOS 上，设备名必须使用 utun 前缀。

路由行为

`route-all: true`

Linux：使用策略路由规则和独立路由表（route-table）。
macOS/Windows：通过 TUN 安装较宽泛的默认路由项。
在 Linux 上，DNS 劫持集成绑定于该路径（目标端口 53 的策略规则）。

`route-all: false`

仅 routes 中的 CIDR 会通过 TUN 路由。
这更适合分阶段上线，并避免接管主机全部流量。

若两者同时配置，运行时以 route-all 为准。

DNS 交互

dns-hijack 控制 TUN 流中的 DNS 劫持，但它不能替代可工作的 DNS 模块配置。
要获得可预测的基于域名路由效果，应将 TUN 与 DNS 设置（dns.enable、解析器列表、按需 fake-IP 策略）配套使用。
在实践中，Clash 风格部署通常将 dns-hijack: true 与 fake-IP 模式搭配使用。

Linux 注意事项（策略路由）

确保已安装 iproute2（ip 命令可用）。
以足够权限运行（CAP_NET_ADMIN 或等效 root 权限）。
建议设置 so-mark，并与外部策略规则保持一致，以避免代理环路。

快速检查：

ip rule
ip route show table 2468
ip -6 route show table 2468

示例配置

全隧道配置

tun:
  enable: true
  device-id: "dev://utun1989"
  route-all: true
  gateway: "198.18.0.1/24"
  dns-hijack: true

分流配置

tun:
  enable: true
  device-id: "dev://tun0"
  route-all: false
  gateway: "198.18.0.1/24"
  routes:
    - 1.1.1.1/32
    - 8.8.8.8/32
  dns-hijack: false

基于 FD 的配置

tun:
  enable: true
  device-id: "fd://3"
  route-all: true
  gateway: "198.18.0.1/24"

故障排查清单

先确认进程权限；在许多受限环境中，TUN 创建和路由变更会静默失败。
确认接口已存在（ip addr、ifconfig 或平台等效命令）。
启动后验证路由/规则是否正确安装。
若 DNS 异常，请确认 DNS 监听器可达，且系统解析路径确实经过 TUN。
若流量出现环路或卡顿，请检查 so-mark/策略规则的一致性以及主机现有防火墙规则。

参考与对齐说明

Clash-rs 配置结构：clash-lib/src/config/def.rs（TunConfig、默认值、dns-hijack 形态）。
Clash-rs 配置转换：clash-lib/src/config/internal/convert/tun.rs。
Clash-rs TUN 运行时与设备解析：clash-lib/src/proxy/tun/inbound.rs。
Clash-rs 路由行为：clash-lib/src/proxy/tun/routes/{linux,macos,windows}.rs。
Clash-rs 示例配置：clash-bin/tests/data/config/tun.yaml。
Chimera_Client 当前解析器快照：clash-lib/src/config/def.rs（主线尚无 tun 配置块）。
Mihomo tun 文档（用于键形态对比）：https://wiki.metacubex.one/config/inbound/tun/。

Proxy Wiki