Hysteria2 — sing-box

پیاده‌سازی Hysteria2 در sing-box تمیزترین از میان سه هسته است: یک بلوک مسطح واحد در هر سمت، تظاهر چندریختی و فیلدهای صریح port-hopping در خروجی.

ورودی

ورودی type: "hysteria2":

فیلد	نوع	پیش‌فرض	مقادیر مجاز	توضیحات
`up_mbps`	`int`	`0`	`<Mbps>`	پهنای باند تخمینی آپ‌لینک به Mbps. سرور این مقدار را به‌عنوان راهنمایی برای کنترل ازدحام استفاده می‌کند.
`down_mbps`	`int`	`0`	`<Mbps>`	پهنای باند تخمینی دانلینک به Mbps.
`obfs`	`*Hysteria2Obfs`	`(disabled)`	`Hysteria2Obfs`	بلوک مبهم‌سازی (`salamander` یا `gecko`). وقتی تنظیم شود، هر دو سمت باید تطبیق داشته باشند.
`users`	`[]Hysteria2User`	`[]`	`[Hysteria2User]`	کاربران پذیرفته‌شده.
`ignore_client_bandwidth`	`bool`	`false`	`true \| false`	اعلان پهنای باند کلاینت را نادیده می‌گیرد و تنظیمات پهنای باند سرور را یک‌جانبه استفاده می‌کند.
`masquerade`	`*Hysteria2Masquerade`	`(disabled)`	`Hysteria2Masquerade`	تظاهر به پاسخ HTTP برای ترافیک احراز نشده. یک URL رشته‌ای یا یک شیء نوع‌دار می‌پذیرد.
`bbr_profile`	`string`	`standard`	`conservative \| standard \| aggressive`	نمایهٔ کنترل ازدحام BBR؛ هر زمان BBR انتخاب شود به کار می‌رود.
`brutal_debug`	`bool`	`false`	`true \| false`	لاگ کردن جزئیات داخلی کنترل ازدحام Brutal.
`realm`	`*Hysteria2InboundRealm`	`(disabled)`	`Hysteria2InboundRealm`	ثبت این سرور نزد سرویس ملاقات Hysteria Realm برای عبور از NAT: آدرس‌های عمومی خود را با STUN کشف می‌کند، آن‌ها را زیر `realm_id` ثبت می‌کند و کلاینت‌ها را با سوراخ‌زنی UDP می‌پذیرد — بدون نیاز به آدرس شنود عمومی.

منبع: option/hysteria2.go:17-30 · ثابت‌شده در v1.14.2 (af6e64c)

این ساختار ListenOptions، InboundTLSOptionsContainer و QUICOptions را درون خود جای می‌دهد (بخش «فیلدهای QUIC» در پایین). یک پیکربندی TLS الزامی است — Hysteria2 روی QUIC اجرا می‌شود و هیچ حالت متن ساده‌ای ندارد.

`obfs`

فیلد	نوع	پیش‌فرض	مقادیر مجاز	توضیحات
`type`	`string`	`(required)`	`salamander \| gecko`	نوع مبهم‌سازی. `gecko` علاوه بر این `min_packet_size` / `max_packet_size` را هم می‌پذیرد.
`password`	`string`	`(required)`	`<string>`	گذرواژهٔ مبهم‌سازی (جدا از گذرواژهٔ کاربر).

منبع: option/hysteria2.go:64-68 · ثابت‌شده در v1.14.2 (af6e64c)

با type: "gecko" همین شیء این فیلدها را هم می‌پذیرد:

فیلد	نوع	پیش‌فرض	مقادیر مجاز	توضیحات
`min_packet_size`	`int`	`512`	`<bytes>`	کمینهٔ اندازهٔ بسته روی سیم، به بایت. فقط gecko.
`max_packet_size`	`int`	`1200`	`<bytes>`	بیشینهٔ اندازهٔ بسته روی سیم، به بایت. فقط gecko.

منبع: option/hysteria2.go:59-62 · ثابت‌شده در v1.14.2 (af6e64c)

`users[]`

فیلد	نوع	پیش‌فرض	مقادیر مجاز	توضیحات
`name`	`string`	`(unset)`	`<string>`	نام نمایشی استفاده‌شده در آمار و لاگ‌ها.
`password`	`string`	`(required)`	`<string>`	گذرواژهٔ احراز هویت کاربر.

منبع: option/hysteria2.go:116-119 · ثابت‌شده در v1.14.2 (af6e64c)

`masquerade`

فیلد masquerade چندریختی است (option/hysteria2.go:121-181):

یک URL رشته‌ای ساده. طرح‌ها:
- 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:121-126 · ثابت‌شده در v1.14.2 (af6e64c)

`type: "file"`

فیلد	نوع	پیش‌فرض	مقادیر مجاز	توضیحات
`directory`	`string`	`(required)`	`<dir path>`	دایرکتوری محلی که در نقطه‌انتهایی تظاهر سرو می‌شود.

منبع: option/hysteria2.go:195-197 · ثابت‌شده در v1.14.2 (af6e64c)

`type: "proxy"`

فیلد	نوع	پیش‌فرض	مقادیر مجاز	توضیحات
`url`	`string`	`(required)`	`<URL>`	URL بالادست که نقطه‌انتهایی تظاهر به آن پراکسی معکوس می‌کند.
`rewrite_host`	`bool`	`false`	`true \| false`	هدر Host را برای تطبیق با URL بالادست بازنویسی می‌کند.

منبع: option/hysteria2.go:199-202 · ثابت‌شده در v1.14.2 (af6e64c)

`type: "string"`

فیلد	نوع	پیش‌فرض	مقادیر مجاز	توضیحات
`status_code`	`int`	`200`	`<int>`	کد وضعیت HTTP بازگردانده‌شده.
`headers`	`badoption.HTTPHeader`	`{}`	`{<header>: <value>}`	هدرهای پاسخ اضافی.
`content`	`string`	`(required)`	`<text>`	بدنهٔ پاسخ.

منبع: option/hysteria2.go:204-208 · ثابت‌شده در v1.14.2 (af6e64c)

خروجی

خروجی type: "hysteria2":

فیلد	نوع	پیش‌فرض	مقادیر مجاز	توضیحات
`server_ports`	`badoption.Listable[string]`	`[]`	`<range>`	فهرست port-hopping. هر ورودی یک پورت (مثلاً `"20001"`) یا یک محدودهٔ خط‌فاصله‌ای (مثلاً `"20001-20100"`) است.
`hop_interval`	`badoption.Duration`	`30s`	`<duration>`	هر چند وقت به یک پورت جدید سوئیچ می‌کند. مدت‌زمان‌های به سبک Go را می‌پذیرد.
`hop_interval_max`	`badoption.Duration`	`(unset)`	`<duration>`	حد بالای پرش پورت تصادفی: هر پرش مدتی تصادفی میان `hop_interval` و این مقدار صبر می‌کند.
`up_mbps`	`int`	`0`	`<Mbps>`	پهنای باند تخمینی آپ‌لینک به Mbps.
`down_mbps`	`int`	`0`	`<Mbps>`	پهنای باند تخمینی دانلینک به Mbps.
`obfs`	`*Hysteria2Obfs`	`(disabled)`	`Hysteria2Obfs`	مبهم‌سازی (`salamander` یا `gecko`)؛ باید با سرور تطبیق داشته باشد.
`password`	`string`	`(required)`	`<string>`	گذرواژهٔ احراز هویت کاربر.
`network`	`NetworkList`	`(tcp+udp)`	`tcp \| udp \|`	محدود کردن به فقط TCP یا فقط UDP.
`bbr_profile`	`string`	`standard`	`conservative \| standard \| aggressive`	نمایهٔ کنترل ازدحام BBR؛ هر زمان BBR انتخاب شود به کار می‌رود.
`brutal_debug`	`bool`	`false`	`true \| false`	لاگ کردن جزئیات داخلی کنترل ازدحام Brutal در سمت کلاینت.
`disable_chrome_parrot`	`bool`	`false`	`true \| false`	خاموش کردن تقلید دست‌دهی QUIC کروم، که به‌طور پیش‌فرض روشن است. تقلید، پارامترهای QUIC کروم را اعمال می‌کند (`idle_timeout` ثابت روی 30 ثانیه؛ `max_concurrent_streams` و `initial_packet_size` با مقادیر کروم؛ پنجره‌های دریافت از مقادیر اولیهٔ کروم آغاز می‌شوند) و دست‌دهی با سرورهایی که گواهی Ed25519 دارند را ناموفق می‌کند.
`realm`	`*Hysteria2Realm`	`(disabled)`	`Hysteria2Realm`	اتصال به سرور از طریق Hysteria Realm: آدرس‌های ثبت‌شده زیر `realm_id` را از realm می‌پرسد، سوراخ‌زنی می‌کند و سپس دست‌دهی عادی QUIC را انجام می‌دهد. با `server`، `server_port` و `server_ports` در تضاد است.

منبع: option/hysteria2.go:210-227 · ثابت‌شده در v1.14.2 (af6e64c)

DialerOptions، ServerOptions (server، server_port)، OutboundTLSOptionsContainer (tls — الزامی) و QUICOptions را درون خود جای می‌دهد.

Realm (عبور از NAT)

سروری که پشت NAT است realm را روی ورودی خود تنظیم می‌کند و نزد یک سرویس Hysteria Realm ثبت می‌شود؛ کلاینت‌ها realm را روی خروجی (به‌جای server) تنظیم می‌کنند تا آن را پیدا کنند. هر دو سمت این شکل مشترک را دارند:

فیلد	نوع	پیش‌فرض	مقادیر مجاز	توضیحات
`server_url`	`string`	`(required)`	`<URL>`	URL سرویس ملاقات realm.
`token`	`string`	`(unset)`	`<string>`	توکن Bearer؛ باید با یکی از `users[].token`های realm تطبیق داشته باشد.
`realm_id`	`string`	`(required)`	`<id>`	شناسهٔ جایگاه. سرور زیر آن ثبت می‌شود و کلاینت‌ها باید همان مقدار را به کار ببرند؛ 1 تا 64 نویسه، مطابق `^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$`.
`stun_servers`	`badoption.Listable[string]`	`(required)`	`<host[:port]> \| …`	سرورهای STUN برای کشف آدرس‌های عمومی. در خروجی، نام‌های دامنه با `domain_resolver` از فیلدهای شماره‌گیری حل می‌شوند.
`ip_version`	`int`	`(both)`	`4 \| 6`	STUN، سوراخ‌زنی و مسیر QUIC حاصل را به یک نسخهٔ IP محدود می‌کند.
`port_mapping`	`*Hysteria2RealmPortMapping`	`(disabled)`	`Hysteria2RealmPortMapping`	نگه‌داشتن نگاشت پورت UDP روی دروازهٔ محلی با UPnP یا NAT-PMP؛ شکست‌ها مهلک نیستند. به IPv4 نیاز دارد.
`http_client`	`*HTTPClientOptions`	`(default)`	`<tag> \| HTTPClientOptions`	کلاینت HTTP برای گفت‌وگو با realm (شیء درون‌خطی یا tag یک مدخل `http_clients`).

منبع: option/hysteria2.go:32-40 · ثابت‌شده در v1.14.2 (af6e64c)

شکل ورودی این را اضافه می‌کند:

فیلد	نوع	پیش‌فرض	مقادیر مجاز	توضیحات
`stun_domain_resolver`	`*DomainResolveOptions`	`(default resolver)`	`<dns server tag> \| DomainResolveOptions`	فقط ورودی: حل‌کننده برای نام‌های دامنهٔ سرورهای STUN (همان قالب `domain_resolver`).

منبع: option/hysteria2.go:54-57 · ثابت‌شده در v1.14.2 (af6e64c)

port_mapping:

فیلد	نوع	پیش‌فرض	مقادیر مجاز	توضیحات
`enabled`	`bool`	`false`	`true \| false`	فعال‌سازی نگاشت پورت.
`timeout`	`badoption.Duration`	`10s`	`<duration>`	مهلت کشف دروازه و عملیات نگاشت.
`lifetime`	`badoption.Duration`	`10m`	`<duration>`	مدت اجارهٔ نگاشت؛ در نیمهٔ آن تمدید می‌شود.

منبع: option/hysteria2.go:48-52 · ثابت‌شده در v1.14.2 (af6e64c)

فیلدهای QUIC

هر دو سمت پارامترهای QUIC مشترک با Hysteria، ‏TUIC و کلاینت‌های HTTP/3 را درون خود دارند (QUICOptions که خود HTTP2Options را دربر می‌گیرد). با فعال بودن تقلید کروم (پیش‌فرض کلاینت)، idle_timeout روی 30 ثانیه ثابت می‌شود و max_concurrent_streams / initial_packet_size با مقادیر کروم جایگزین می‌شوند.

فیلد	نوع	پیش‌فرض	مقادیر مجاز	توضیحات
`initial_packet_size`	`int`	`(QUIC default)`	`<bytes>`	اندازهٔ بستهٔ اولیهٔ QUIC.
`disable_path_mtu_discovery`	`bool`	`false`	`true \| false`	غیرفعال کردن کشف MTU مسیر در QUIC.

منبع: option/http.go:22-26 · ثابت‌شده در v1.14.2 (af6e64c)

فیلد	نوع	پیش‌فرض	مقادیر مجاز	توضیحات
`idle_timeout`	`badoption.Duration`	`(default)`	`<duration>`	مهلت بیکاری اتصال.
`keep_alive_period`	`badoption.Duration`	`(default)`	`<duration>`	دورهٔ keep-alive.
`stream_receive_window`	`*byteformats.MemoryBytes`	`(default)`	`<size>`	پنجرهٔ دریافت کنترل جریان برای هر جریان، به قالب اندازهٔ حافظه (مثلاً 64 MB).
`connection_receive_window`	`*byteformats.MemoryBytes`	`(default)`	`<size>`	پنجرهٔ دریافت کنترل جریان برای هر اتصال، به قالب اندازهٔ حافظه.
`max_concurrent_streams`	`int`	`(default)`	`<int>`	بیشینهٔ جریان‌های هم‌زمان در هر اتصال.

منبع: option/http.go:14-20 · ثابت‌شده در v1.14.2 (af6e64c)

مثال‌ها

ورودی بدون port-hopping آشکار (سمت سرور فقط روی یک پورت شنود می‌کند)، با obfs Salamander و تظاهر فایل:

json

{
  "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"
    }
  ]
}

خروجی با port-hopping (۲۰۰۰۰-۲۰۱۰۰، هر ۳۰ ثانیه سوئیچ):

json

{
  "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 یا gecko است. پیکربندی‌هایی که obfs را حذف می‌کنند از مسیر بدون مبهم‌سازی استفاده می‌کنند.
کلاینت به‌طور پیش‌فرض از دست‌دهی QUIC کروم تقلید می‌کند. کروم پشتیبانی از Ed25519 را اعلام نمی‌کند، پس سروری با گواهی Ed25519 در دست‌دهی شکست می‌خورد — از گواهی ECDSA یا RSA استفاده کنید یا روی کلاینت disable_chrome_parrot: true را تنظیم کنید.
در خروجی، اگر up_mbps / down_mbps تنظیم نشوند، به‌جای Brutal از BBR استفاده می‌شود (قابل تنظیم با bbr_profile).
masquerade هم شیء نوع‌دار چندریختی و هم یک URL رشته‌ای ساده را می‌پذیرد — هر دو به همان نمایش داخلی unmarshal می‌شوند (option/hysteria2.go:145-164).
ignore_client_bandwidth: true تنظیم توصیه‌شده برای سرورهایی است که مدیر آن از قبل پهنای باند واقعی را می‌داند — از این جلوگیری می‌کند که یک کلاینت بدخواه ظرفیت خود را کمتر اعلام کند و بیشتر از سرور بگیرد.

نکات بین‌هسته‌ای

Xray-core از Hysteria2 پشتیبانی می‌کند اما پیکربندی را میان settings و streamSettings.hysteriaSettings تقسیم می‌کند، و پهنای باند، کنترل ازدحام و پرش پورت در streamSettings.finalmask قرار دارند. به Hysteria2 — Xray-core مراجعه کنید.
mihomo از یک خروجی تک‌بلوکی با up/down به‌صورت رشته (با پسوندهای واحد مانند Xray) استفاده می‌کند. Port-hopping به‌صورت ports + hop-interval است. کاربران در ورودی یک map[string]string (نام‌کاربری → گذرواژه) هستند نه فهرستی از اشیاء. به Hysteria2 — mihomo مراجعه کنید.

منبع: option/hysteria2.go:17-227 · v1.14.2 (af6e64c)

Hysteria2 — sing-box ​

ورودی ​

obfs ​

users[] ​

masquerade ​

type: "file" ​

type: "proxy" ​

type: "string" ​

خروجی ​

Realm (عبور از NAT) ​

فیلدهای QUIC ​

مثال‌ها ​

نکات ​

نکات بین‌هسته‌ای ​