Add hysteria2 realm service and support

Author: nekohasekai

constant/proxy.go

@@ -32,6 +32,7 @@ const (
 	TypeCCM                = "ccm"
 	TypeOCM                = "ocm"
 	TypeOOMKiller          = "oom-killer"
+	TypeHysteriaRealm      = "hysteria-realm"
 	TypeACME               = "acme"
 	TypeCloudflareOriginCA = "cloudflare-origin-ca"
 )

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.

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/) 了解详情。

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.

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/)。