网络与代理 / 2026-10-18
Hysteria2 的 finalmask 与 mihomo:一个类型错误踩了两小时
服务端开了 salamander 混淆,客户端却在 yaml 里写成了嵌套 map。mihomo 只报一句 obfs expected type string,剩下全靠猜。
服务端 3x-ui 里勾了 Hysteria2 的混淆,参数 salamander。浏览器能连上节点,但本机的 mihomo 一直起不来,日志里只有一行:
initialise HTTP proxy: proxies[0]: 'obfs' expected type 'string'
这句报错信息量其实不小,只是当时没往格式上想。
两种写法,只差一层嵌套
服务端的 finalmask 是一个数组,混淆类型写在 type 里:
{
"finalmask": {
"udp": [
{ "type": "salamander", "settings": { "password": "<混淆口令>" } }
]
}
}
而 mihomo 的客户端配置是扁平的字符串,不是对象:
proxies:
- name: hy2-node
type: hysteria2
server: <地址>
port: 443
password: <认证口令>
obfs: salamander # 字符串,不是 map
obfs-password: <混淆口令>
sni: <域名>
skip-cert-verify: false
我当时的写法是把它当成服务端结构照抄:
obfs:
type: salamander
password: xxx
于是 obfs 的期望类型是 string,拿到的是 map,解析直接失败。改回单行字符串,立刻通。
不同客户端的叫法不一样
同一件事,三个客户端三种命名,很容易在对照文档时卡住:
| 客户端 | 字段 | 备注 |
|---|---|---|
| mihomo ≥ 1.19 | obfs + obfs-password | obfs 必须是字符串 |
| Shadowrocket | Obfuscation / Obfuscation Password | 图形界面里是两个输入框 |
| 旧版 Clash(dreamacro) | 无 | 不支持 Hysteria2,换内核 |
| sing-box | obfs.type + obfs.password | 这里是对象结构 |
最后一行是坑的来源之一:sing-box 用对象,mihomo 用字符串。两个项目都在演进,抄错一个字段就白排查。
排查顺序
现在我会按这个顺序走,基本十分钟内定位:
- 服务端先取配置原文,确认
finalmask.udp[].type与settings.password都有值,注意口令是否只打印过一次就丢了。 - 客户端版本先核对。mihomo 1.19 之前对混淆支持不完整,
mihomo -v是最快的检查。 - 字段形状对照。
obfs是不是字符串,这一条就能解释掉大部分报错。 - 最后才怀疑 UDP 通路。服务端到客户端的 UDP 被中间设备丢掉时,握手会超时而不是报配置错误——症状完全不同,别混在一起查。
一个附带结论
混淆不是加密,它只是把流量特征改得更像随机数据,能绕过一部分基于特征的识别,但不提供任何保密性。真正保护内容的是 TLS 与认证口令。把这两者分清楚,就不会在"开了混淆是不是就安全了"这种问题上浪费判断力。
finalmask 到底解决什么
QUIC 的握手包特征明显,部分网络会对"首包即大包"的连接直接限速或丢弃。finalmask 的作用是在 QUIC 外层再包一层混淆,让首个数据包的字节分布看起来不像 QUIC。
它是混淆,不是加密——真正的加密仍然在 QUIC/TLS 层。别把它当成"安全增强",它只影响"能不能连上"。
配置要点
listen: :443
tls:
cert: /etc/hysteria/cert.pem
key: /etc/hysteria/key.pem
obfs:
type: salamander
salamander:
password: <长随机串>
客户端必须用完全一致的 obfs 类型与密码。错一个字符的表现是:TCP 能连、QUIC 握手超时,日志里没有任何明确报错——这就是"一个类型错误耽误两小时"的由来。
排查顺序
nc -vz host 443看端口通不通(UDP 要nc -vzu)- 服务端日志有没有
QUIC handshake记录 - 客户端 obfs 参数逐字符比对
- 换端口试(部分网络封 443/UDP)
第 4 条经常被跳过,但它是唯一能区分"配置错"和"链路被封"的方法。
一个取舍
开混淆会增加约 3–5% 的 CPU 与少量延迟。只在"被限速/被丢包"的链路上开,内网或干净链路上没必要。
一句总结:把"出问题的地方"和"验证的方法"写在一起,比只写配置更有用——配置抄得到,判断顺序抄不到。