Hysteria2 — sing-box

sing-box 的 Hysteria2 实现是三个内核中最简洁的：两端各一个扁平块、 多态伪装、出站显式的端口跳变字段。

入站

type: "hysteria2" 入站：

字段	类型	默认值	允许值	描述
up_mbps	int	0	<Mbps>	估算的上行带宽（Mbps）。服务端把它作为拥塞控制的提示。
down_mbps	int	0	<Mbps>	估算的下行带宽（Mbps）。
obfs	*Hysteria2Obfs	(disabled)	Hysteria2Obfs	Salamander 混淆块。设置后两端必须一致。
users	[]Hysteria2User	[]	[Hysteria2User]	可接受的用户。
ignore_client_bandwidth	bool	false	true | false	丢弃客户端宣告的带宽，单方面使用服务端的带宽设置。
masquerade	*Hysteria2Masquerade	(disabled)	Hysteria2Masquerade	对未鉴权流量返回 HTTP 响应伪装。接受字符串 URL 或类型化对象。
brutal_debug	bool	false	true | false	记录 Brutal 拥塞控制的内部状态。

源码： option/hysteria2.go:13-23 · 锚定版本 v1.13.11 (553cfa1)

该结构体内嵌 ListenOptions 与 InboundTLSOptionsContainer。 必须 配置 TLS —— Hysteria2 跑在 QUIC 上，没有明文模式。

obfs

字段	类型	默认值	允许值	描述
type	string	(required)	salamander	混淆类型。目前仅定义了 `salamander`。
password	string	(required)	<string>	混淆密码（与用户密码相互独立）。

源码： option/hysteria2.go:25-28 · 锚定版本 v1.13.11 (553cfa1)

users[]

字段	类型	默认值	允许值	描述
name	string	(unset)	<string>	统计与日志中使用的显示名。
password	string	(required)	<string>	用户鉴权密码。

源码： option/hysteria2.go:30-33 · 锚定版本 v1.13.11 (553cfa1)

masquerade

masquerade 字段是多态的（option/hysteria2.go:44-95）：

• 一个纯 字符串 URL。可识别的 scheme：
  • file:///var/www —— 等价于 { "type": "file", "directory": "/var/www" }。
  • https://upstream.example.com —— 等价于 { "type": "proxy", "url": "..." }。
• 一个 对象，由 type 字段选择三种形态之一：

字段	类型	默认值	允许值	描述
type	string	(unset)	file | proxy | string	选择启用的子块。

源码： option/hysteria2.go:35-40 · 锚定版本 v1.13.11 (553cfa1)

type: "file"

字段	类型	默认值	允许值	描述
directory	string	(required)	<dir path>	在伪装端点上托管的本地目录。

源码： option/hysteria2.go:97-99 · 锚定版本 v1.13.11 (553cfa1)

type: "proxy"

字段	类型	默认值	允许值	描述
url	string	(required)	<URL>	伪装端点反向代理到的上游 URL。
rewrite_host	bool	false	true | false	改写 Host 头以匹配上游 URL。

源码： option/hysteria2.go:101-104 · 锚定版本 v1.13.11 (553cfa1)

type: "string"

字段	类型	默认值	允许值	描述
status_code	int	200	<int>	返回的 HTTP 状态码。
headers	badoption.HTTPHeader	{}	{<header>: <value>}	附加响应头。
content	string	(required)	<text>	响应体内容。

源码： option/hysteria2.go:106-110 · 锚定版本 v1.13.11 (553cfa1)

出站

type: "hysteria2" 出站：

字段	类型	默认值	允许值	描述
server_ports	badoption.Listable[string]	[]	<range>	端口跳变列表。每个条目是端口（如 `"20001"`）或带连字符的范围（如 `"20001-20100"`）。
hop_interval	badoption.Duration	30s	<duration>	切换新端口的频率。接受 Go 风格时长。
up_mbps	int	0	<Mbps>	估算的上行带宽（Mbps）。
down_mbps	int	0	<Mbps>	估算的下行带宽（Mbps）。
obfs	*Hysteria2Obfs	(disabled)	Hysteria2Obfs	Salamander 混淆；必须与服务端一致。
password	string	(required)	<string>	用户鉴权密码。
network	NetworkList	(tcp+udp)	tcp | udp |	限定为仅 TCP 或仅 UDP。
brutal_debug	bool	false	true | false	在客户端侧记录 Brutal CC 内部状态。

源码： option/hysteria2.go:112-124 · 锚定版本 v1.13.11 (553cfa1)

同时内嵌 DialerOptions、ServerOptions（server、server_port） 与 OutboundTLSOptionsContainer（tls —— 必填）。

示例

不暴露端口跳变（服务端只监听单端口）、带 Salamander 混淆与 file 伪装的入站：

{
  "inbounds": [
    {
      "type": "hysteria2",
      "tag": "hy2-in",
      "listen": "::",
      "listen_port": 443,
      "users": [
        { "name": "alice", "password": "<password>" }
      ],
      "obfs": { "type": "salamander", "password": "<obfs>" },
      "tls": {
        "enabled": true,
        "alpn": ["h3"],
        "certificate_path": "/etc/ssl/cert.pem",
        "key_path": "/etc/ssl/key.pem"
      },
      "masquerade": "file:///var/www"
    }
  ]
}

带端口跳变（20000-20100，每 30 秒切换）的出站：

{
  "outbounds": [
    {
      "type": "hysteria2",
      "tag": "hy2-out",
      "server": "example.com",
      "server_port": 443,
      "server_ports": ["20000-20100"],
      "hop_interval": "30s",
      "password": "<password>",
      "obfs": { "type": "salamander", "password": "<obfs>" },
      "up_mbps": 100,
      "down_mbps": 300,
      "tls": { "enabled": true, "server_name": "example.com" }
    }
  ]
}

说明

• 带宽这里是 纯整数 Mbps —— 不带单位字符串。Xray 与 mihomo 接受带后缀的字符串（"100mbps"），sing-box 不支持。
• obfs.type 当前只定义一个值（salamander）。省略 obfs 的 配置走未混淆路径。
• masquerade 同时接受多态类型化对象与纯字符串 URL —— 两者都会 解组到相同的内部表示（option/hysteria2.go:59-78）。
• 管理员已知真实带宽时，推荐设置 ignore_client_bandwidth: true —— 可防止恶意客户端通过低报自身带宽从服务端榨取更多资源。

跨内核说明

• Xray-core 支持 Hysteria2，但把配置拆到 settings 与 streamSettings.hysteriaSettings。参见 Hysteria2 — Xray-core。
• mihomo 使用单块出站，up / down 是带单位后缀的字符串 （与 Xray 一样）。端口跳变由 ports + hop-interval 表达。 入站的用户是 map[string]string（用户名 → 密码）而非对象列表。 参见 Hysteria2 — mihomo。

源码： option/hysteria2.go:13-124 · v1.13.11 (553cfa1)