TUIC — mihomo

mihomo 双端同时支持 TUIC v4（基于 token）与 TUIC v5（UUID + 密码）。 声明入站有两种方式：标准的 listeners: 条目，或顶层 tuic-server 块。

出站

proxies: 下 type: tuic 条目。内嵌 BasicOption。

字段	类型	默认值	允许值	描述
name	string	(required)	<string>	唯一的代理名。
server	string	(required)	<host>	上游服务器主机名或 IP。
port	int	(required)	<port>	上游服务器端口。
token	string	(unset)	<string>	旧式 TUIC v4 令牌。与 `uuid` + `password`（v5）互斥。
uuid	string	(required for v5)	<UUID>	用户 UUID（TUIC v5）。
password	string	(required for v5)	<string>	用户密码（TUIC v5）。
ip	string	(unset)	<host>	解析后覆盖目的 IP。当 SNI / 证书对应的名称与真实服务器 IP 不同时使用。
heartbeat-interval	int	10000	<milliseconds>	QUIC 心跳间隔。**毫秒**，不是秒。
alpn	[]string	[h3]	h3	ALPN 列表。TUIC 要求 HTTP/3 ALPN。
reduce-rtt	bool	false	true | false	重连时使用 0-RTT 握手。
request-timeout	int	8000	<milliseconds>	等待 connect 帧响应的超时（毫秒）。
udp-relay-mode	string	native	native | quic	UDP 隧道方式。`native`（数据报）更快；`quic`（每包一流）能穿透屏蔽 QUIC 数据报的中间盒。
congestion-controller	string	cubic	cubic | new_reno | bbr | bbr_meta_v1 | bbr_meta_v2	QUIC 拥塞控制器。`bbr` 是 mihomo 的 v2 BBR；`bbr_meta_v1` / `bbr_meta_v2` 保留旧变体以保兼容。
disable-sni	bool	false	true | false	完全省略 ClientHello 中的 SNI 扩展。
max-udp-relay-packet-size	int	1252	<bytes>	分片前的 UDP 载荷最大字节数。
fast-open	bool	false	true | false	把代理请求帧与 QUIC 握手并发送出。
max-open-streams	int	100	<int>	每个 QUIC 连接的最大并发流数。
cwnd	int	32	<int>	初始拥塞窗口（包数）。默认 32（`transport/tuic/common/congestion.go:17-19`）。
bbr-profile	string	(unset)	default | aggressive	`congestion-controller: bbr` 时的 BBR 调优 profile。
skip-cert-verify	bool	false	true | false	禁用 TLS 校验（仅供测试）。
fingerprint	string	(unset)	<SHA256 hex>	锚定服务端 TLS 证书指纹。
certificate	string	(unset)	<PEM file path>	客户端证书（mTLS）。
private-key	string	(unset)	<key file path>	与 `certificate` 配对的私钥。
recv-window-conn	int	0	<bytes>	整连接初始接收窗口。0 使用 quic-go 默认。
recv-window	int	0	<bytes>	单流初始接收窗口。0 使用 quic-go 默认。
disable-mtu-discovery	bool	false	true | false	跳过路径 MTU 探测；在丢弃 probe 的网络上有用。
max-datagram-frame-size	int	1252	<bytes>	QUIC 数据报帧最大字节数。
sni	string	(server)	<SNI>	TLS Server Name Indication。
ech-opts	ECHOptions	(disabled)	ECHOptions	Encrypted Client Hello 配置。
udp-over-stream	bool	false	true | false	使用 UDP-over-stream 帧替代 QUIC 数据报。
udp-over-stream-version	int	1	1	帧版本。当前仅定义 1。

源码： adapter/outbound/tuic.go:34-69 · 锚定版本 v1.19.27 (5184081)

入站（listeners 下）

listeners: 下 type: tuic 条目。内嵌 BaseOption。

字段	类型	默认值	允许值	描述
token	[]string	[]	[<string>]	旧式 TUIC v4 令牌列表。为空则禁用 v4。
users	map[string]string	{}	{<uuid>: <password>}	TUIC v5 用户表。键为 UUID，值为密码。
certificate	string	(required)	<PEM file path>	TLS 服务端证书。
private-key	string	(required)	<key file path>	TLS 私钥。
client-auth-type	string	(none)	no-client-cert | request-client-cert | require-any-client-cert | verify-client-cert-if-given | require-and-verify-client-cert	mTLS 客户端鉴权模式。
client-auth-cert	string	(unset)	<PEM file path>	作为客户端根的 CA 集合。
ech-key	string	(unset)	<ECH config>	Encrypted Client Hello 配置 / 密钥。
congestion-controller	string	cubic	cubic | new_reno | bbr | bbr_meta_v1 | bbr_meta_v2	服务端 QUIC 拥塞控制器。
max-idle-time	int	0	<milliseconds>	QUIC 连接空闲超时。0 使用 QUIC 默认。
authentication-timeout	int	1000	<milliseconds>	等待客户端鉴权帧的最长时间（毫秒）。
alpn	[]string	[h3]	h3	TLS 握手时宣告的 ALPN 列表。
max-udp-relay-packet-size	int	1252	<bytes>	接受的最大 UDP 载荷。
cwnd	int	32	<int>	初始拥塞窗口（包数）。
bbr-profile	string	(unset)	default | aggressive	BBR 调优 profile。
mux-option	MuxOption	(disabled)	MuxOption	sing 风格多路复用设置。

源码： listener/inbound/tuic.go:12-29 · 锚定版本 v1.19.27 (5184081)

入站（顶层 tuic-server）

顶层 tuic-server 块是声明 TUIC 入站的另一种方式，出于历史原因 保留。新配置建议使用 listener 形式（与入站模型其余部分组合更自然）。

字段	类型	默认值	允许值	描述
enable	bool	false	true | false	顶层 TUIC 入站总开关。为 false 时块内其他字段被忽略。
listen	string	127.0.0.1:0	<host:port>	监听地址。语法与 mihomo 其他位置一致。
token	[]string	[]	[<string>]	TUIC v4 令牌列表。
users	map[string]string	{}	{<uuid>: <password>}	TUIC v5 用户表。
certificate	string	(required)	<PEM file path>	TLS 服务端证书。
private-key	string	(required)	<key file path>	TLS 私钥。
congestion-controller	string	cubic	cubic | new_reno | bbr | bbr_meta_v1 | bbr_meta_v2	服务端 QUIC 拥塞控制器。
max-idle-time	int	0	<milliseconds>	QUIC 空闲超时。
authentication-timeout	int	1000	<milliseconds>	客户端鉴权帧超时。
alpn	[]string	[h3]	h3	ALPN 列表。
max-udp-relay-packet-size	int	1252	<bytes>	最大 UDP 载荷。
cwnd	int	32	<int>	初始拥塞窗口。

源码： config/config.go:323-336 · 锚定版本 v1.19.27 (5184081)

示例

出站 —— TUIC v5：

proxies:
  - name: tuic-v5
    type: tuic
    server: example.com
    port: 443
    uuid: a3482e88-686a-4a58-8126-99c9df64b7bf
    password: <password>
    udp-relay-mode: native
    congestion-controller: bbr
    sni: example.com
    alpn: [h3]
    heartbeat-interval: 10000
    reduce-rtt: true

出站 —— TUIC v4（旧式）：

proxies:
  - name: tuic-v4
    type: tuic
    server: example.com
    port: 443
    token: <token>
    udp-relay-mode: native
    sni: example.com
    alpn: [h3]

listeners 下的入站：

listeners:
  - name: tuic-in
    type: tuic
    listen: 0.0.0.0
    port: 443
    users:
      a3482e88-686a-4a58-8126-99c9df64b7bf: <alice password>
      6f4e6c2c-8b1d-4b4f-8e2e-1f2b5c9e0a3b: <bob password>
    certificate: /etc/mihomo/server.crt
    private-key: /etc/mihomo/server.key
    congestion-controller: bbr
    alpn: [h3]

顶层 tuic-server（旧形态）：

tuic-server:
  enable: true
  listen: 0.0.0.0:443
  users:
    a3482e88-686a-4a58-8126-99c9df64b7bf: <password>
  certificate: /etc/mihomo/server.crt
  private-key: /etc/mihomo/server.key
  congestion-controller: bbr
  alpn: [h3]

说明

• mihomo 的 TUIC 出站使用 毫秒 表示超时与间隔（不是秒）—— heartbeat-interval: 10000 即 10 秒。request-timeout 与入站的 authentication-timeout 也遵循同样约定。
• 五种拥塞控制器在 transport/tuic/common/congestion.go:20-53 中接入。 bbr 是现代 v2 实现；bbr_meta_v1 / bbr_meta_v2 仅为兼容旧客户端 保留。
• cwnd: 0 在运行时按 32 包处理 （transport/tuic/common/congestion.go:17-19）。
• 顶层 tuic-server 块只能声明 一个 TUIC 入站。多端口多入站 请使用 listeners: 形式。

跨内核说明

• Xray-core 不支持 TUIC。参见 TUIC — Xray-core。
• sing-box 仅支持 TUIC v5（无 token 形式），字段名为 snake_case （congestion_control、udp_relay_mode），超时接受 Go 风格时长 字符串（"3s"），且拥塞控制选择更少（cubic、new_reno、bbr）。 参见 TUIC — sing-box。

源码： adapter/outbound/tuic.go:34-69 · v1.19.27 (5184081)