Add hysteria2 realm service and support

2026-05-10 13:31:53 +08:00
parent 89d83aa6d2
commit 094808a4fa
20 changed files with 1167 additions and 33 deletions
@@ -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.
@@ -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 槽位数量上限。
@@ -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

@@ -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