mirror of
https://github.com/XTLS/Xray-docs-next.git
synced 2026-10-12 09:18:19 +03:00
140 lines
5.0 KiB
Markdown
140 lines
5.0 KiB
Markdown
# xray.dns
|
|
|
|
提供 DNS 查询和上游服务器访问接口。
|
|
|
|
```lua
|
|
local dns = require("xray.dns")
|
|
```
|
|
|
|
## API 索引
|
|
|
|
| 分类 | 成员 | 说明 |
|
|
| ---- | ----------------------------------------------------- | ------------------------ |
|
|
| 函数 | [`dns.Query(domain, ipv4, ipv6, fake)`](#dns-query) | 通过 Xray DNS 客户端查询 |
|
|
| 字段 | [`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)
|
|
```
|
|
|
|
通过 Xray 的 DNS 客户端查询域名。在 DNS Hook 中不可用，因为脚本接管的就是它。
|
|
|
|
**参数**
|
|
|
|
| 参数 | 类型 | 说明 |
|
|
| -------- | --------- | -------------------- |
|
|
| `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 slice；查询失败或没有可用地址时返回 `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 侧实现 | `app/dns` 中的 `luaDNSServer` |
|
|
| Lua 表现 | `table` |
|
|
| 取得方式 | [`dns.Servers`](#dns-servers) 的数组元素 |
|
|
|
|
#### ID
|
|
|
|
```lua
|
|
local id = serverObj.ID
|
|
```
|
|
|
|
| 名称 | 类型 | 说明 |
|
|
| -------------- | -------- | ----------------------------------------------------------------------------------------- |
|
|
| `serverObj.ID` | `string` | 对应 [DNS 服务器配置](../../../config/dns.md#dnsserverobject)中的 `id` 字段，始终非 `nil` |
|
|
|
|
未填写 `id` 时为 `""`，包括用字符串形式配置的服务器；自动添加的系统 DNS 上游 ID 为 `"localhost"`。
|
|
|
|
需要通过 ID 区分服务器时，请自行配置唯一的值，核心不会检查是否重复。
|
|
|
|
#### Query
|
|
|
|
```lua
|
|
local ips, ttl, err = serverObj:Query(domain, ipv4, ipv6, fake)
|
|
```
|
|
|
|
查询 `serverObj` 对应的上游。
|
|
|
|
**参数与返回值**
|
|
|
|
参数要求和返回值类型与 [`dns.Query`](#dns-query) 相同。
|
|
|
|
**行为约定**
|
|
|
|
正常配置的上游成功时返回非空 IP slice、TTL 和 `nil`；查询失败、没有符合条件的地址，或 `fake == false` 却查询 FakeDNS 时返回 `nil, 0, err`。
|
|
|
|
直接查询该服务器，跳过全局 Hosts 和 DNS 脚本。服务器自身的 `queryStrategy`、缓存、`timeoutMs`、`clientIP`、`tag`，以及 `expectedIPs` / `unexpectedIPs` 和对应的 `actPrior` / `actUnprior` 仍然生效。
|
|
|
|
**示例**
|
|
|
|
在 DNS Hook 中直接返回首个上游的查询结果：
|
|
|
|
```lua
|
|
function HandleDNSQuery(domain, ipv4, ipv6, fake)
|
|
return dns.Servers[1]:Query(domain, ipv4, ipv6, fake)
|
|
end
|
|
```
|