Bobay Stack 波贝自建栈

网络与代理 / 2026-10-18

Hysteria2 的 finalmask 与 mihomo:一个类型错误踩了两小时

服务端开了 salamander 混淆,客户端却在 yaml 里写成了嵌套 map。mihomo 只报一句 obfs expected type string,剩下全靠猜。

8 MIN READ BY BOBAY.TOP 更新于 2026-10-23 ↖ 全部笔记
Hysteria2 的 finalmask 与 mihomo:一个类型错误踩了两小时

服务端 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.19obfs + obfs-passwordobfs 必须是字符串
ShadowrocketObfuscation / Obfuscation Password图形界面里是两个输入框
旧版 Clash(dreamacro)无不支持 Hysteria2,换内核
sing-boxobfs.type + obfs.password这里是对象结构

最后一行是坑的来源之一:sing-box 用对象,mihomo 用字符串。两个项目都在演进,抄错一个字段就白排查。

排查顺序

现在我会按这个顺序走,基本十分钟内定位:

  1. 服务端先取配置原文,确认 finalmask.udp[].type 与 settings.password 都有值,注意口令是否只打印过一次就丢了。
  2. 客户端版本先核对。mihomo 1.19 之前对混淆支持不完整,mihomo -v 是最快的检查。
  3. 字段形状对照。obfs 是不是字符串,这一条就能解释掉大部分报错。
  4. 最后才怀疑 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 握手超时,日志里没有任何明确报错——这就是"一个类型错误耽误两小时"的由来。

排查顺序

  1. nc -vz host 443 看端口通不通(UDP 要 nc -vzu)
  2. 服务端日志有没有 QUIC handshake 记录
  3. 客户端 obfs 参数逐字符比对
  4. 换端口试(部分网络封 443/UDP)

第 4 条经常被跳过,但它是唯一能区分"配置错"和"链路被封"的方法。

一个取舍

开混淆会增加约 3–5% 的 CPU 与少量延迟。只在"被限速/被丢包"的链路上开,内网或干净链路上没必要。

一句总结:把"出问题的地方"和"验证的方法"写在一起,比只写配置更有用——配置抄得到,判断顺序抄不到。

Hysteria2mihomo混淆客户端兼容

参考

mihomo 配置文档 ↗ Hysteria2 混淆说明 ↗