DNS — sing-box

موتور DNS sing-box فهرستی از سرورهای نوع‌دار به‌علاوهٔ یک زنجیرهٔ قاعدهٔ ساختاریافته است. هر سرور یک type دارد که ترابرد آن را انتخاب می‌کند (UDP، TCP، TLS، QUIC، HTTPS، HTTP/3، فایل hosts، مخزن fake-ip، تأمین‌شده توسط DHCP، mDNS، systemd-resolved، Tailscale تعبیه‌شده، یا حل‌کننده‌های اعلام‌شده توسط یک نقطه‌انتهایی OpenVPN / OpenConnect). قواعد از همان مجموعه‌فیلد تطبیق قواعد مسیریابی استفاده می‌کنند اما با کنش‌های ویژهٔ DNS — و می‌توانند روی پاسخ نیز تطبیق دهند.

گزینه‌های سطح بالا

فیلد	نوع	پیش‌فرض	مقادیر مجاز	توضیحات
`servers`	`[]DNSServerOptions`	`[]`	`[DNSServerOptions]`	فهرست سرور DNS. هر ورودی یک `type` (local، hosts، tcp، udp، tls، quic، https، h3، dhcp، mdns، fakeip، tailscale، openconnect، openvpn، resolved) و مجموعهٔ گزینه‌های متناظر دارد. ورودی‌های بدون `type` (قالب بی‌نوع `address`) رد می‌شوند.
`rules`	`[]DNSRule`	`[]`	`[DNSRule]`	قواعد مسیریابی در سطح DNS. شکل یکسانی با قواعد مسیریابی دارند اما با مجموعهٔ کنش‌های ویژهٔ DNS.
`final`	`string`	`(unset)`	`<server tag>`	سرور DNS پیش‌فرض وقتی هیچ قاعده‌ای تطبیق نمی‌یابد. مقدار خالی به اولین سرور در `servers[]` بازگشت می‌کند.
`reverse_mapping`	`bool`	`false`	`true \| false`	نگه‌داری نگاشت معکوس (IP → دامنه) تا قواعد بتوانند پس از این‌که اتصالی مقصد را به IP حل کرد، روی دامنهٔ اصلی تطبیق دهند.

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

به علاوهٔ DNSClientOptions تعبیه‌شده:

فیلد	نوع	پیش‌فرض	مقادیر مجاز	توضیحات
`strategy`	`DomainStrategy`	`(prefer_ipv4)`	`prefer_ipv4 \| prefer_ipv6 \| ipv4_only \| ipv6_only`	اولویت پیش‌فرض خانوادهٔ آدرس.
`timeout`	`badoption.Duration`	`10s`	`<duration>`	مهلت پیش‌فرض هر پرس‌وجوی DNS. به ازای هر قاعده (`timeout` در کنش قاعدهٔ DNS) و در `domain_resolver` قابل بازنویسی است.
`disable_cache`	`bool`	`false`	`true \| false`	غیرفعال‌سازی کش پاسخ درون‌حافظه.
`disable_expire`	`bool`	`false`	`true \| false`	ورودی‌های کش‌شده را بر اساس TTL بیرون نراند — آن‌ها را برای همیشه نگه دار.
`independent_cache`	`bool`	`false`	`true \| false`	منسوخ: کش همیشه بر اساس سرور کلیدگذاری می‌شود، پس این گزینه اثری ندارد.
`cache_capacity`	`uint32`	`1024`	`<int>`	ظرفیت کش LRU (تعداد ورودی). مقادیر کمتر از 1024 به 1024 افزایش می‌یابند.
`optimistic`	`*OptimisticDNSOptions`	`false`	`true \| false \| {enabled, timeout}`	کش خوش‌بینانه: ورودی منقضی‌شده‌ای که هنوز در بازهٔ `timeout` (پیش‌فرض 3d) است فوراً بازگردانده می‌شود و هم‌زمان در پس‌زمینه تازه می‌شود. با `disable_cache` و `disable_expire` در تضاد است.
`client_subnet`	`*badoption.Prefixable`	`(unset)`	`<CIDR>`	ECS (EDNS Client Subnet) که در پرس‌وجوهای خروجی اعلان می‌شود.

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

انواع سرور

هر ورودی در servers[] یک فیلد type دارد. فیلدهای تطبیق:

`type: "local"`

حل‌وفصل از طریق حل‌کنندهٔ سیستم‌عامل (در macOS/iOS که حل‌کنندهٔ سیستم مسیر معتبر است مفید است). برای انتخاب حل‌کنندهٔ گو بدون CGO، prefer_go را اضافه می‌کند. neighbor_domain نام‌های تک‌برچسبی LAN را از حل‌کنندهٔ همسایه پاسخ می‌دهد. در پلتفرم‌های غیر Apple، سرور local همچنین *.local. و ناحیه‌های معکوس link-local را از طریق mDNS حل می‌کند (در Apple از طریق حل‌کنندهٔ سیستم).

فیلد	نوع	پیش‌فرض	مقادیر مجاز	توضیحات
`prefer_go`	`bool`	`false`	`true \| false`	استفاده از net.Resolver گو (بدون CGO) به‌جای حل‌کنندهٔ بومی پلتفرم. در سیستم‌هایی که حل‌کنندهٔ بومی شکسته یا نرخ‌محدود است مفید است.
`neighbor_domain`	`badoption.Listable[string]`	`[]`	`[<.suffix>]`	پسوندهای دامنه (هر کدام با `.` آغاز می‌شود) که پرس‌وجوهای A/AAAA تک‌برچسبی آن‌ها به‌جای بالادست از حل‌کنندهٔ همسایه (نام میزبان‌های LAN از اجاره‌های DHCP) پاسخ داده می‌شود. `.` با هر نام تک‌برچسبی تطبیق دارد، مثلاً [".", ".lan"].

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

`type: "udp"` و `type: "tcp"` — RemoteDNSServerOptions

json

{ "type": "udp", "tag": "local-udp", "server": "8.8.8.8", "server_port": 53 }

فیلد	نوع	پیش‌فرض	مقادیر مجاز	توضیحات
`server`	`string`	`(required)`	`<host>`	نام میزبان یا IP سرور.
`server_port`	`uint16`	`53 (udp/tcp), 853 (tls), 443 (https/h3)`	`<port>`	پورت سرور.

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

`type: "tls"` — DNS-over-TLS

همان فیلدهای udp/tcp به‌علاوهٔ بلوک استاندارد tls:. type: "quic" (DNS-over-QUIC) دقیقاً همین فیلدها را می‌گیرد.

`type: "https"` و `type: "h3"` — DNS-over-HTTPS / -H3

فیلد	نوع	پیش‌فرض	مقادیر مجاز	توضیحات
`path`	`string`	`/dns-query`	`/<path>`	مسیر نقطه‌انتهایی DoH.
`method`	`string`	`POST`	`POST \| GET`	روش HTTP استفاده‌شده برای پرس‌وجوهای DoH.
`headers`	`badoption.HTTPHeader`	`{}`	`{<header>: <value>}`	هدرهای HTTP اضافی.

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

`type: "hosts"` — فایل hosts محلی

فیلد	نوع	پیش‌فرض	مقادیر مجاز	توضیحات
`path`	`badoption.Listable[string]`	`[/etc/hosts]`	`[<file path>]`	فهرست مسیرهای فایل hosts برای ادغام.
`predefined`	`*badjson.TypedMap[string, badoption.Listable[netip.Addr]]`	`{}`	`{<domain>: [<IP>]}`	جدول hosts درون‌خطی. اولویت بالاتری نسبت به `path` دارد.

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

`type: "fakeip"`

فیلد	نوع	پیش‌فرض	مقادیر مجاز	توضیحات
`inet4_range`	`*badoption.Prefix`	`(required for v4)`	`<CIDR>`	محدودهٔ CIDR IPv4 اختصاص‌یافته برای IPهای جعلی.
`inet6_range`	`*badoption.Prefix`	`(required for v6)`	`<CIDR>`	محدودهٔ CIDR IPv6 اختصاص‌یافته برای IPهای جعلی.

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

`type: "dhcp"`

فیلد	نوع	پیش‌فرض	مقادیر مجاز	توضیحات
`interface`	`string`	`(auto)`	`<interface>`	رابطی که حل‌کننده‌های ارائه‌شده توسط DHCP آن استفاده می‌شوند.

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

انواع دیگر

type: "resolved" — خواندن سرورهای نام per-link از systemd-resolved (فقط Linux).
type: "tailscale" — استفاده از حل‌کنندهٔ MagicDNS دیمن Tailscale.
type: "mdns" — پرس‌وجوی چندپخشی روی شبکهٔ محلی (mDNS)، با فهرست اختیاری interface. در کنار یک سرور local معمولاً لازم نیست (آن سرور *.local. را از قبل از طریق mDNS مسیریابی می‌کند)؛ برای ارجاع از preferred_by آن را اضافه کنید.
type: "openvpn" / type: "openconnect" — استفاده از حل‌کننده‌هایی که یک نقطه‌انتهایی کلاینت OpenVPN / OpenConnect (endpoint: "<tag>") اعلام کرده است، با accept_default_resolvers و accept_search_domain. تنظیمات اعلام‌شده در سیستم‌عامل نصب نمی‌شوند.

نوع سروری به نام predefined یا rcode وجود ندارد: پاسخ‌های ثابت از کنش قاعدهٔ DNS predefined می‌آیند (پایین‌تر).

قواعد DNS

قواعد DNS از همان شکل چندریختی _Rule قواعد مسیریابی استفاده می‌کنند (type: "default" یا type: "logical") با ۵۴ کلید تطبیق RawDefaultDNSRule — از جمله کلیدهای query_client_subnet، query_dnssec، package_name_regex، source_mac_address، source_hostname، preferred_by (تطبیق نام‌هایی که سرورهای فهرست‌شده متعلق به خود می‌دانند: ورودی‌های hosts، نام‌های mDNS، DNS تفکیکی و دامنه‌های جست‌وجوی اعلام‌شده توسط Tailscale / VPN) و فیلدهای تطبیق پاسخ زیر. تفاوت‌ها در سطح کنش است:

کنش DNS	معنا
`route` (پیش‌فرض)	ارسال پرس‌وجو به `server: "<tag>"`. اختیاری: `disable_cache`، `disable_optimistic_cache`، `rewrite_ttl`، `timeout`، `client_subnet` / `remove_client_subnet`، `speculative`؛ `strategy` منسوخ است.
`route-options`	اعمال گزینه‌های DNS-route (همان فیلدهای اختیاری) روی تطبیق‌های بعدی قاعده.
`evaluate`	پرس‌وجو از `server` و نگه‌داشتن پاسخ (به‌صورت اختیاری با یک `tag`) تا قواعد بعدی از طریق `match_response` روی آن تطبیق دهند؛ ارزیابی قواعد را پایان نمی‌دهد. فقط در قواعد سطح بالا.
`respond`	بازگرداندن پاسخی که یک `evaluate` قبلی نگه داشته، بدون پرس‌وجوی جدید.
`reject`	رد پرس‌وجو. `method: "default"` با REFUSED پاسخ می‌دهد؛ `method: "drop"` پاسخی نمی‌فرستد.
`predefined`	بازگشت یک پاسخ کدشده (`rcode`، `answer`، `ns`، `extra`).

race: true (روی قواعد route / respond / reject / predefined که از match_response استفاده می‌کنند) اجازه می‌دهد قواعد وابسته به پاسخ به‌صورت موازی داوری شوند — نخستین قاعدهٔ منطبق برنده است و پرس‌وجوهای باقی‌مانده لغو می‌شوند.

تطبیق پاسخ

قواعد می‌توانند به‌جای فقط پرس‌وجو، پاسخ را تطبیق دهند. یک قاعدهٔ evaluate پاسخی را دریافت می‌کند؛ قاعدهٔ بعدی با match_response: true (یا tag آن قاعدهٔ evaluate) آن را با ip_cidr / ip_is_private / ip_accept_any، یک مجموعه قواعد IP، یا فیلدهای پاسخ response_rcode، response_answer، response_ns، response_extra تطبیق می‌دهد. استفاده از ip_cidr / ip_is_private بدون match_response (فیلتر آدرس قدیمی)، گزینهٔ کنش strategy و rule_set_ip_cidr_accept_empty منسوخ شده‌اند و برای حذف برنامه‌ریزی شده‌اند. مهاجرت برای یک تقسیم مبتنی بر GeoIP:

json

{
  "dns": {
    "rules": [
      { "action": "evaluate", "server": "remote" },
      { "match_response": true, "rule_set": "geoip-cn",
        "action": "route", "server": "local" },
      { "action": "route", "server": "remote" }
    ]
  }
}

مثال‌ها

تقسیم دو سروری — داخلی روی DoH محلی، بقیه روی DoH Cloudflare:

json

{
  "dns": {
    "servers": [
      { "type": "https", "tag": "local",
        "server": "doh.pub", "path": "/dns-query" },
      { "type": "https", "tag": "remote",
        "server": "cloudflare-dns.com", "path": "/dns-query",
        "detour": "proxy" },
      { "type": "fakeip", "tag": "fakeip",
        "inet4_range": "198.18.0.0/15",
        "inet6_range": "fc00::/18" }
    ],
    "rules": [
      { "rule_set": ["geosite-cn"], "server": "local" }
    ],
    "final": "remote",
    "strategy": "prefer_ipv4"
  }
}

مسدودسازی تبلیغات از طریق DNS:

json

{
  "dns": {
    "servers": [
      { "type": "https", "tag": "main",
        "server": "cloudflare-dns.com" }
    ],
    "rules": [
      {
        "domain_keyword": ["ads", "doubleclick", "googlesyndication"],
        "action": "reject",
        "method": "default"
      }
    ],
    "final": "main"
  }
}

نکات

بلوک سطح بالای fakeip: {...} و ورودی‌های سرور بدون type (قالب بی‌نوع address: "tls://…") پشتیبانی نمی‌شوند — هر دو در راه‌اندازی شکست می‌خورند. از ورودی‌های نوع‌دار استفاده کنید (type: "fakeip"، type: "tls" و …).
reverse_mapping: true به قواعد مسیریابی بعدی اجازه می‌دهد حتی پس از این‌که اسنیف، مقصد را به IP حل کرده، روی نام دامنه تطبیق دهند. هنگام استفاده از fake-ip در کنار قواعد دامنهٔ پیچیده، ضروری است.
independent_cache اثری ندارد: کش همیشه بر اساس برچسب سرور (و client subnet) کلیدگذاری می‌شود، پس سرورهای split-horizon هرگز پاسخ مشترک ندارند. این گزینه منسوخ است؛ آن را حذف کنید.
ip_version و query_type روی جست‌وجوهای داخلی‌ای که سرور مشخصی را هدف نمی‌گیرند نیز اعمال می‌شوند (مثلاً کنش مسیریابی resolve بدون server). ترکیب آن‌ها با فیلدهای فیلتر آدرس قدیمیِ منسوخ در همان پیکربندی DNS هنگام راه‌اندازی رد می‌شود.
قلم منسوخ قاعدهٔ DNS یعنی outbound هنوز تجزیه می‌شود، اما باید با route.default_domain_resolver یا domain_resolver روی هر خروجی جایگزین شود.
قواعد DNS و قواعد مسیریابی یک واژگان مشترک کلید تطبیق دارند اما در زمان‌های متفاوت عمل می‌کنند: قواعد DNS روی پرس‌وجوی حل‌کننده اجرا می‌شوند؛ قواعد مسیریابی روی اتصال نهایی اجرا می‌شوند.
type: "resolved" از D-Bus API systemd-resolved می‌خواند — فقط روی سیستم‌های Linux که resolved واقعاً حل‌کنندهٔ در حال اجرا است کار می‌کند.

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

Xray-core از یک بلوک تخت dns: با servers[] حامل رشته‌های URL (یا اشیاء NameServerConfig) استفاده می‌کند — بدون فیلد type، اسکیمای URL ترابرد را تعیین می‌کند. بنگرید به DNS — Xray-core.
mihomo یک بلوک ۲۵ فیلدی dns: با فهرست‌های جداگانهٔ nameserver / fallback و یک نگاشت nameserver-policy دارد. بنگرید به DNS — mihomo.

منبع: option/dns.go:18-224 · v1.14.2 (af6e64c)

DNS — sing-box ​

گزینه‌های سطح بالا ​

انواع سرور ​

type: "local" ​

type: "udp" و type: "tcp" — RemoteDNSServerOptions ​

type: "tls" — DNS-over-TLS ​

type: "https" و type: "h3" — DNS-over-HTTPS / -H3 ​

type: "hosts" — فایل hosts محلی ​

type: "fakeip" ​

type: "dhcp" ​

انواع دیگر ​

قواعد DNS ​

تطبیق پاسخ ​

مثال‌ها ​

نکات ​

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

DNS — sing-box

گزینه‌های سطح بالا

انواع سرور

`type: "local"`

`type: "udp"` و `type: "tcp"` — RemoteDNSServerOptions

`type: "tls"` — DNS-over-TLS

`type: "https"` و `type: "h3"` — DNS-over-HTTPS / -H3

`type: "hosts"` — فایل hosts محلی

`type: "fakeip"`

`type: "dhcp"`

انواع دیگر

قواعد DNS

تطبیق پاسخ

مثال‌ها

نکات

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