Hysteria2 realm 监听器 — mihomo

Hysteria2 realm 监听器在单个端点之后承载多个 Hysteria2“realm”—— 即多个租户。每个 realm 都是一个独立的 Hysteria2 服务，多路复用到同一个 监听地址上，通过 realm 身份而非单独的端口来区分。客户端通过在其普通的 Hysteria2 代理上设置 realm-opts 来接入某个 realm：它们指向 此监听器的控制端点，出示共享令牌，并指定要加入的 realm 名称。

这是 realm 功能的服务端。realm 支持较新且偏高级——大多数部署改用普通的 hysteria2 监听器。

监听器

位于 listeners: 下、type: hysteria2-realm 的条目。内嵌 BaseOption （listen、port）。

字段	类型	默认值	允许值	描述
token	string	(unset)	<string>	realm 必须出示该共享认证令牌才能向此监听器注册或由其提供服务。
max-realms	int	0	<int>	此监听器承载的 realm 最大数量。0 表示不限。
max-realms-per-ip	int	0	<int>	按客户端 IP 限制承载的 realm 数量。0 表示不限。
trusted-proxy-header	string	(unset)	<header name>	当监听器位于前置代理之后时，携带真实客户端 IP 的 HTTP 头。
realm-name-pattern	string	(unset)	<pattern>	约束所接受的 realm 名称的模式。
certificate	string	(required)	<PEM file path>	TLS 服务器证书（PEM 路径）。
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	双向 TLS 客户端认证模式（例如 `require-and-verify-client-cert`）。
client-auth-cert	string	(unset)	<PEM file path>	作为客户端根证书接受的 CA 包。
ech-key	string	(unset)	<ECH config>	Encrypted Client Hello 密钥材料。
alpn	[]string	[h3]	h3	TLS 握手期间提供的 ALPN（通常为 `h3`）。

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

示例

带共享令牌和按 IP realm 上限的最简 realm 监听器：

listeners:
  - name: hy2-realm-server
    type: hysteria2-realm
    listen: 0.0.0.0
    port: 443
    token: <realm-token>
    max-realms: 16
    max-realms-per-ip: 2
    certificate: /etc/mihomo/server.crt
    private-key: /etc/mihomo/server.key
    alpn: [h3]

客户端通过在其出站上添加 realm-opts 来加入此监听器上的某个 realm—— 参见 Hysteria2 — mihomo。

说明

• token 是共享密钥。客户端的 realm-opts.token 必须与之匹配，该客户端 才能向监听器注册或由其提供服务。
• max-realms 限制监听器承载的 realm 总数；max-realms-per-ip 按客户端 IP 限制。两者均保持默认值即可不设上限。
• trusted-proxy-header 仅在监听器位于会改写源地址的前置代理之后时才有意义 ——它指定携带原始客户端 IP 的头，从而使按 IP 的上限保持准确。
• TLS 是必需的：提供 certificate 和 private-key。添加 client-auth-type 加上 client-auth-cert 以要求双向 TLS，并用 ech-key 启用 Encrypted Client Hello。

跨内核说明

• realm 是 mihomo / Hysteria2 的功能。Xray-core 与 sing-box 均未提供等价的 多 realm 监听器——它们每个入站只承载单个 Hysteria2 服务。参见 Hysteria2 — Xray-core 与 Hysteria2 — sing-box 了解它们的单租户监听器。

源码： listener/inbound/hysteria2_realm.go:12-25 · v1.19.27 (5184081)