mirror of
https://github.com/XTLS/Xray-docs-next.git
synced 2026-10-13 01:38:22 +03:00
140 lines
7.5 KiB
Markdown
140 lines
7.5 KiB
Markdown
# xray.dns
|
||
|
||
Предоставляет интерфейсы DNS-запросов и доступа к вышестоящим серверам.
|
||
|
||
```lua
|
||
local dns = require("xray.dns")
|
||
```
|
||
|
||
## Указатель API
|
||
|
||
| Категория | Член API | Описание |
|
||
| --------- | ----------------------------------------------------- | ---------------------------------- |
|
||
| Функция | [`dns.Query(domain, ipv4, ipv6, fake)`](#dns-query) | Запрос через DNS-клиент Xray |
|
||
| Поле | [`dns.Servers`](#dns-servers) | Массив вышестоящих серверов |
|
||
| Объект | [`serverObj`](#server) | Отдельный вышестоящий DNS-сервер |
|
||
| Поле | [`serverObj.ID`](#id) | Идентификатор сервера |
|
||
| Метод | [`serverObj:Query(domain, ipv4, ipv6, fake)`](#query) | Прямой запрос к указанному серверу |
|
||
|
||
## Функции
|
||
|
||
### dns.Query
|
||
|
||
```lua
|
||
local ips, ttl, err = dns.Query(domain, ipv4, ipv6, fake)
|
||
```
|
||
|
||
Запрашивает домен через DNS-клиент Xray. В Hook DNS недоступен, поскольку скрипт заменяет именно этот процесс обработки запросов.
|
||
|
||
**Параметры**
|
||
|
||
| Параметр | Тип | Описание |
|
||
| -------- | --------- | ------------------------- |
|
||
| `domain` | `string` | Запрашиваемый домен |
|
||
| `ipv4` | `boolean` | Разрешены ли запросы IPv4 |
|
||
| `ipv6` | `boolean` | Разрешены ли запросы IPv6 |
|
||
| `fake` | `boolean` | Разрешён ли FakeDNS |
|
||
|
||
**Возвращаемые значения**
|
||
|
||
| Значение | Тип | Описание |
|
||
| -------- | ------------------------------------------------ | ------------------------------------------------------------ |
|
||
| `ips` | [`[]net.IP`](./data-types.md#net-ip-1) или `nil` | Результаты запроса |
|
||
| `ttl` | `number` | TTL в секундах, диапазон `0 .. 4294967295`; никогда не `nil` |
|
||
| `err` | [`error`](./data-types.md#error) или `nil` | Ошибка запроса; `nil` означает отсутствие ошибки |
|
||
|
||
**Поведение**
|
||
|
||
Все четыре параметра нужно передать явно с правильными типами, иначе возникает исключение Lua.
|
||
|
||
Запрос учитывает глобальные ограничения типов запросов клиента, Hosts и настройки вышестоящих серверов. Если настроен [скрипт DNS](../guide/dns.md), запрос также передаётся ему. Если встроенный DNS не настроен, используется системный DNS.
|
||
|
||
При успехе возвращается непустой срез IP; при ошибке запроса или отсутствии доступных адресов — `nil, 0, err`.
|
||
|
||
**Пример**
|
||
|
||
```lua
|
||
local ips, ttl, err = dns.Query("example.com", true, true, false)
|
||
if err == nil and ips ~= nil and #ips > 0 then
|
||
local firstIP = ips[1]:String()
|
||
end
|
||
```
|
||
|
||
## Поля
|
||
|
||
### dns.Servers
|
||
|
||
```lua
|
||
local servers = dns.Servers
|
||
```
|
||
|
||
| Имя | Тип | Описание |
|
||
| ------------- | ------- | ------------------------------------------------------------------------------ |
|
||
| `dns.Servers` | `table` | Массив [`serverObj`](#server), индексы с 1, порядок соответствует конфигурации |
|
||
|
||
При использовании встроенного DNS список содержит настроенные вышестоящие серверы. Если DNS или его серверы не настроены, список содержит только `localhost` (системный DNS).
|
||
|
||
Для перебора списка используйте `ipairs`; при выходе индекса за границы `servers[i]` равен `nil`.
|
||
|
||
**Пример**
|
||
|
||
```lua
|
||
for _, serverObj in ipairs(dns.Servers) do
|
||
local id = serverObj.ID
|
||
end
|
||
```
|
||
|
||
## Объекты
|
||
|
||
### server
|
||
|
||
`serverObj` представляет вышестоящий DNS-сервер с его идентификатором и методом запроса.
|
||
|
||
| Свойство | Описание |
|
||
| ------------------- | --------------------------------------------- |
|
||
| Реализация в Go | `luaDNSServer` из `app/dns` |
|
||
| Представление в Lua | `table` |
|
||
| Получение | Элемент массива [`dns.Servers`](#dns-servers) |
|
||
|
||
#### ID
|
||
|
||
```lua
|
||
local id = serverObj.ID
|
||
```
|
||
|
||
| Имя | Тип | Описание |
|
||
| -------------- | -------- | ------------------------------------------------------------------------------------------------ |
|
||
| `serverObj.ID` | `string` | Поле `id` в [конфигурации DNS-сервера](../../../config/dns.md#dnsserverobject); никогда не `nil` |
|
||
|
||
Если `id` не задан, значение равно `""`, в том числе у серверов, настроенных строками. Автоматически добавленный системный DNS имеет ID `"localhost"`.
|
||
|
||
Если нужно различать серверы по ID, самостоятельно задайте уникальные значения: ядро не проверяет дубликаты.
|
||
|
||
#### Query
|
||
|
||
```lua
|
||
local ips, ttl, err = serverObj:Query(domain, ipv4, ipv6, fake)
|
||
```
|
||
|
||
Запрашивает вышестоящий сервер, представленный `serverObj`.
|
||
|
||
**Параметры и возвращаемые значения**
|
||
|
||
Требования к параметрам и типы возвращаемых значений такие же, как у [`dns.Query`](#dns-query).
|
||
|
||
**Поведение**
|
||
|
||
Обычно настроенный сервер при успехе возвращает непустой срез IP, TTL и `nil`. При ошибке запроса, отсутствии адресов, удовлетворяющих условиям, или запросе FakeDNS с `fake == false` возвращается `nil, 0, err`.
|
||
|
||
Запрашивает этот сервер напрямую, обходя глобальные Hosts и скрипт DNS. Собственные настройки сервера `queryStrategy`, кеш, `timeoutMs`, `clientIP`, `tag`, а также `expectedIPs` / `unexpectedIPs` и соответствующие `actPrior` / `actUnprior` продолжают действовать.
|
||
|
||
**Пример**
|
||
|
||
Вернуть результат запроса к первому серверу напрямую из Hook DNS:
|
||
|
||
```lua
|
||
function HandleDNSQuery(domain, ipv4, ipv6, fake)
|
||
return dns.Servers[1]:Query(domain, ipv4, ipv6, fake)
|
||
end
|
||
```
|