Add hysteria2 realm service and support

2026-05-13 13:57:05 +00:00 · 2026-05-10 13:31:53 +08:00 · 2026-05-10 13:31:53 +08:00 · 34c90e6f2e
commit 34c90e6f2e
parent 18f10561c9
20 changed files with 1167 additions and 33 deletions
--- a/docs/configuration/inbound/hysteria2.md
+++ b/docs/configuration/inbound/hysteria2.md
@ -4,7 +4,8 @@ icon: material/alert-decagram

 !!! quote "Changes in sing-box 1.14.0"

-    :material-plus: [bbr_profile](#bbr_profile)
+    :material-plus: [bbr_profile](#bbr_profile)  
+    :material-plus: [realm](#realm)

 !!! quote "Changes in sing-box 1.11.0"

@ -39,7 +40,14 @@ icon: material/alert-decagram

  "masquerade": "", // or {}
  "bbr_profile": "",
-  "brutal_debug": false
+  "brutal_debug": false,
+  "realm": {
+    "server_url": "https://realm.example.com",
+    "token": "",
+    "realm_id": "",
+    "stun_servers": [],
+    "http_client": {}
+  }
 }
 ```

@ -164,3 +172,47 @@ BBR congestion control algorithm profile, one of `conservative` `standard` `aggr
 #### brutal_debug

 Enable debug information logging for Hysteria Brutal CC.
+
+#### realm
+
+!!! question "Since sing-box 1.14.0"
+
+Register this inbound to a Hysteria Realm rendezvous service to enable NAT traversal.
+
+The inbound discovers its public addresses via STUN, registers them on the realm, and uses UDP hole-punching to accept incoming clients without a publicly reachable listen address.
+
+See [Hysteria Realm](/configuration/service/hysteria-realm/) for the rendezvous service.
+
+#### realm.server_url
+
+==Required==
+
+Realm rendezvous service URL.
+
+#### realm.token
+
+Bearer token for the realm. Must match one of `users[].token` configured on the realm.
+
+#### realm.realm_id
+
+==Required==
+
+Slot identifier on the realm.
+
+1–64 characters, must match `^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$`.
+
+Outbounds must use the same `realm_id` to find this server.
+
+#### realm.stun_servers
+
+==Required==
+
+List of STUN servers (`host` or `host:port`) used to discover public addresses.
+
+Port defaults to `3478`.
+
+#### realm.http_client
+
+HTTP client used to talk to the realm.
+
+See [HTTP Client](/configuration/shared/http-client/) for details.
--- a/docs/configuration/inbound/hysteria2.zh.md
+++ b/docs/configuration/inbound/hysteria2.zh.md
@ -4,7 +4,8 @@ icon: material/alert-decagram

 !!! quote "sing-box 1.14.0 中的更改"

-    :material-plus: [bbr_profile](#bbr_profile)
+    :material-plus: [bbr_profile](#bbr_profile)  
+    :material-plus: [realm](#realm)

 !!! quote "sing-box 1.11.0 中的更改"

@ -39,7 +40,14 @@ icon: material/alert-decagram

  "masquerade": "", // 或 {}
  "bbr_profile": "",
-  "brutal_debug": false
+  "brutal_debug": false,
+  "realm": {
+    "server_url": "https://realm.example.com",
+    "token": "",
+    "realm_id": "",
+    "stun_servers": [],
+    "http_client": {}
+  }
 }
 ```

@ -161,3 +169,47 @@ BBR 拥塞控制算法配置，可选 `conservative` `standard` `aggressive`。
 #### brutal_debug

 启用 Hysteria Brutal CC 的调试信息日志记录。
+
+#### realm
+
+!!! question "自 sing-box 1.14.0 起"
+
+将此入站注册到 Hysteria Realm 会合服务，以启用 NAT 穿透。
+
+入站通过 STUN 发现自己的公网地址并注册到 realm，借助 UDP 打洞接受客户端连接，无需可公网直达的监听地址。
+
+会合服务参阅 [Hysteria Realm](/zh/configuration/service/hysteria-realm/)。
+
+#### realm.server_url
+
+==必填==
+
+Realm 会合服务 URL。
+
+#### realm.token
+
+Realm 的 Bearer 令牌，需与 realm 上配置的 `users[].token` 之一匹配。
+
+#### realm.realm_id
+
+==必填==
+
+Realm 上的槽位标识符。
+
+1–64 字符，需匹配 `^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$`。
+
+出站需使用相同的 `realm_id` 才能找到本服务器。
+
+#### realm.stun_servers
+
+==必填==
+
+用于发现公网地址的 STUN 服务器列表（`host` 或 `host:port`）。
+
+端口默认为 `3478`。
+
+#### realm.http_client
+
+与 realm 通信使用的 HTTP 客户端。
+
+参阅 [HTTP 客户端](/zh/configuration/shared/http-client/) 了解详情。
--- a/docs/configuration/outbound/hysteria2.md
+++ b/docs/configuration/outbound/hysteria2.md
@ -1,7 +1,8 @@
 !!! quote "Changes in sing-box 1.14.0"

    :material-plus: [hop_interval_max](#hop_interval_max)  
-    :material-plus: [bbr_profile](#bbr_profile)
+    :material-plus: [bbr_profile](#bbr_profile)  
+    :material-plus: [realm](#realm)

 !!! quote "Changes in sing-box 1.11.0"

@ -36,6 +37,13 @@

  "bbr_profile": "",
  "brutal_debug": false,
+  "realm": {
+    "server_url": "https://realm.example.com",
+    "token": "",
+    "realm_id": "",
+    "stun_servers": [],
+    "http_client": {}
+  },

  ... // Dial Fields
 }
@ -61,6 +69,8 @@

 The server address.

+Conflicts with `realm`.
+
 #### server_port

 ==Required==
@ -69,13 +79,15 @@ The server port.

 Ignored if `server_ports` is set.

+Conflicts with `realm`.
+
 #### server_ports

 !!! question "Since sing-box 1.11.0"

 Server port range list.

-Conflicts with `server_port`.
+Conflicts with `server_port` and `realm`.

 #### hop_interval

@ -143,6 +155,50 @@ BBR congestion control algorithm profile, one of `conservative` `standard` `aggr

 Enable debug information logging for Hysteria Brutal CC.

+#### realm
+
+!!! question "Since sing-box 1.14.0"
+
+Connect to a Hysteria2 server through a Hysteria Realm rendezvous service.
+
+The outbound queries the realm for the server's current public addresses, performs UDP hole-punching, and proceeds with the normal QUIC handshake.
+
+Conflicts with `server`, `server_port` and `server_ports`.
+
+The TLS SNI defaults to the host portion of `server_url`. Set `tls.server_name` to match the certificate the Hysteria2 server presents.
+
+See [Hysteria Realm](/configuration/service/hysteria-realm/) for the rendezvous service.
+
+#### realm.server_url
+
+==Required==
+
+Realm rendezvous service URL.
+
+#### realm.token
+
+Bearer token for the realm. Must match one of `users[].token` configured on the realm.
+
+#### realm.realm_id
+
+==Required==
+
+The same slot identifier the target Hysteria2 server registered.
+
+#### realm.stun_servers
+
+==Required==
+
+List of STUN servers (`host` or `host:port`) used to discover this client's public addresses.
+
+Port defaults to `3478`.
+
+#### realm.http_client
+
+HTTP client used to talk to the realm.
+
+See [HTTP Client](/configuration/shared/http-client/) for details.
+
 ### Dial Fields

 See [Dial Fields](/configuration/shared/dial/) for details.
--- a/docs/configuration/outbound/hysteria2.zh.md
+++ b/docs/configuration/outbound/hysteria2.zh.md
@ -1,7 +1,8 @@
 !!! quote "sing-box 1.14.0 中的更改"

    :material-plus: [hop_interval_max](#hop_interval_max)  
-    :material-plus: [bbr_profile](#bbr_profile)
+    :material-plus: [bbr_profile](#bbr_profile)  
+    :material-plus: [realm](#realm)

 !!! quote "sing-box 1.11.0 中的更改"

@ -36,6 +37,13 @@

  "bbr_profile": "",
  "brutal_debug": false,
+  "realm": {
+    "server_url": "https://realm.example.com",
+    "token": "",
+    "realm_id": "",
+    "stun_servers": [],
+    "http_client": {}
+  },

  ... // 拨号字段
 }
@ -59,6 +67,8 @@

 服务器地址。

+与 `realm` 冲突。
+
 #### server_port

 ==必填==
@ -67,13 +77,15 @@

 如果设置了 `server_ports`，则忽略此项。

+与 `realm` 冲突。
+
 #### server_ports

 !!! question "自 sing-box 1.11.0 起"

 服务器端口范围列表。

-与 `server_port` 冲突。
+与 `server_port` 和 `realm` 冲突。

 #### hop_interval

@ -141,6 +153,50 @@ BBR 拥塞控制算法配置，可选 `conservative` `standard` `aggressive`。

 启用 Hysteria Brutal CC 的调试信息日志记录。

+#### realm
+
+!!! question "自 sing-box 1.14.0 起"
+
+通过 Hysteria Realm 会合服务连接 Hysteria2 服务器。
+
+出站从 realm 查询服务器当前的公网地址，执行 UDP 打洞，然后进行常规的 QUIC 握手。
+
+与 `server`、`server_port` 和 `server_ports` 冲突。
+
+TLS SNI 默认使用 `server_url` 中的主机名。需设置 `tls.server_name` 以匹配 Hysteria2 服务器证书覆盖的名字。
+
+会合服务参阅 [Hysteria Realm](/zh/configuration/service/hysteria-realm/)。
+
+#### realm.server_url
+
+==必填==
+
+Realm 会合服务 URL。
+
+#### realm.token
+
+Realm 的 Bearer 令牌，需与 realm 上配置的 `users[].token` 之一匹配。
+
+#### realm.realm_id
+
+==必填==
+
+目标 Hysteria2 服务器注册时使用的相同槽位标识符。
+
+#### realm.stun_servers
+
+==必填==
+
+用于发现本客户端公网地址的 STUN 服务器列表（`host` 或 `host:port`）。
+
+端口默认为 `3478`。
+
+#### realm.http_client
+
+与 realm 通信使用的 HTTP 客户端。
+
+参阅 [HTTP 客户端](/zh/configuration/shared/http-client/) 了解详情。
+
 ### 拨号字段

 参阅 [拨号字段](/zh/configuration/shared/dial/)。
--- a/docs/configuration/service/hysteria-realm.md
+++ b/docs/configuration/service/hysteria-realm.md
@ -0,0 +1,66 @@
+---
+icon: material/new-box
+---
+
+!!! question "Since sing-box 1.14.0"
+
+# Hysteria Realm
+
+Hysteria Realm is a rendezvous service for Hysteria2 NAT traversal.
+
+A Hysteria2 server behind NAT registers its STUN-discovered public addresses to a stable realm endpoint; clients query the realm to learn the server's current addresses and perform UDP hole-punching to establish a direct QUIC connection.
+
+The realm only carries control-plane signaling. Once hole-punching succeeds, all proxy traffic flows directly between client and server.
+
+### Structure
+
+```json
+{
+  "type": "hysteria-realm",
+
+  ... // Listen Fields
+
+  "tls": {},
+  "users": [
+    {
+      "name": "",
+      "token": "",
+      "max_realms": 0
+    }
+  ]
+}
+```
+
+### Listen Fields
+
+See [Listen Fields](/configuration/shared/listen/) for details.
+
+### Fields
+
+#### tls
+
+TLS configuration, see [TLS](/configuration/shared/tls/#inbound).
+
+When configured, the realm serves HTTP/2 over TLS; otherwise plain HTTP/1.1.
+
+#### users
+
+==Required==
+
+Authorized users.
+
+#### users.name
+
+==Required==
+
+Username, used in logs and as the quota key.
+
+#### users.token
+
+==Required==
+
+Bearer token presented by Hysteria2 inbounds and outbounds via `Authorization: Bearer <token>`.
+
+#### users.max_realms
+
+Maximum number of realm slots this user may hold concurrently.
--- a/docs/configuration/service/hysteria-realm.zh.md
+++ b/docs/configuration/service/hysteria-realm.zh.md
@ -0,0 +1,66 @@
+---
+icon: material/new-box
+---
+
+!!! question "自 sing-box 1.14.0 起"
+
+# Hysteria Realm
+
+Hysteria Realm 是用于 Hysteria2 NAT 穿透的会合服务。
+
+位于 NAT 后面的 Hysteria2 服务器将其通过 STUN 发现的公网地址注册到一个稳定的 realm 端点；客户端从 realm 查询服务器当前的地址并执行 UDP 打洞，以建立直连的 QUIC 连接。
+
+Realm 只承载控制信令。打洞成功后，所有代理流量在客户端和服务器之间直连传输。
+
+### 结构
+
+```json
+{
+  "type": "hysteria-realm",
+
+  ... // 监听字段
+
+  "tls": {},
+  "users": [
+    {
+      "name": "",
+      "token": "",
+      "max_realms": 0
+    }
+  ]
+}
+```
+
+### 监听字段
+
+参阅 [监听字段](/zh/configuration/shared/listen/) 了解详情。
+
+### 字段
+
+#### tls
+
+TLS 配置，参阅 [TLS](/zh/configuration/shared/tls/#入站)。
+
+配置后，realm 将通过 TLS 提供 HTTP/2 服务；否则提供明文 HTTP/1.1。
+
+#### users
+
+==必填==
+
+授权用户。
+
+#### users.name
+
+==必填==
+
+用户名，用于日志记录和配额键。
+
+#### users.token
+
+==必填==
+
+Hysteria2 入站和出站通过 `Authorization: Bearer <token>` 出示的 Bearer 令牌。
+
+#### users.max_realms
+
+此用户可同时持有的 realm 槽位数量上限。
--- a/docs/configuration/service/index.md
+++ b/docs/configuration/service/index.md
@ -21,13 +21,14 @@ icon: material/new-box

 ### Fields

-| Type       | Format                 |
-|------------|------------------------|
-| `ccm`      | [CCM](./ccm)           |
-| `derp`     | [DERP](./derp)         |
-| `ocm`      | [OCM](./ocm)           |
-| `resolved` | [Resolved](./resolved) |
-| `ssm-api`  | [SSM API](./ssm-api)   |
+| Type              | Format                                |
+|-------------------|---------------------------------------|
+| `ccm`             | [CCM](./ccm)                          |
+| `derp`            | [DERP](./derp)                        |
+| `hysteria-realm`  | [Hysteria Realm](./hysteria-realm)    |
+| `ocm`             | [OCM](./ocm)                          |
+| `resolved`        | [Resolved](./resolved)                |
+| `ssm-api`         | [SSM API](./ssm-api)                  |

 #### tag

--- a/docs/configuration/service/index.zh.md
+++ b/docs/configuration/service/index.zh.md
@ -21,13 +21,14 @@ icon: material/new-box

 ### 字段

-| 类型       | 格式                   |
-|-----------|------------------------|
-| `ccm`     | [CCM](./ccm)           |
-| `derp`    | [DERP](./derp)         |
-| `ocm`     | [OCM](./ocm)           |
-| `resolved`| [Resolved](./resolved) |
-| `ssm-api` | [SSM API](./ssm-api)   |
+| 类型              | 格式                                  |
+|-------------------|---------------------------------------|
+| `ccm`             | [CCM](./ccm)                          |
+| `derp`            | [DERP](./derp)                        |
+| `hysteria-realm`  | [Hysteria Realm](./hysteria-realm)    |
+| `ocm`             | [OCM](./ocm)                          |
+| `resolved`        | [Resolved](./resolved)                |
+| `ssm-api`         | [SSM API](./ssm-api)                  |

 #### tag