Max/XTLS_Xray-docs-next
1
0
Fork 0
mirror of https://github.com/XTLS/Xray-docs-next.git synced 2026-10-12 01:08:24 +03:00
Code Issues Packages Projects Releases Wiki Activity

Xray-core: Add Lua script for dns and routing

Browse Source 
https://github.com/XTLS/Xray-core/pull/6823
This commit is contained in:
Meow
2026-10-11 09:55:19 +08:00
parent 4c8f3b2b7e
commit f179efd35d
48 changed files with 4950 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ru/development/lua/reference/module-geodata.md
+344
View File
@@ -0,0 +1,344 @@
# xray.geodata
Предоставляет сопоставление доменов и IP по правилам.
```lua
local geodata = require("xray.geodata")
```
## Указатель API
| Категория | Член API | Описание |
| --------- | ---------------------------------------------------------------- | ------------------------------------------- |
| Функция | [`geodata.BuildDomainMatcher(...)`](#geodata-builddomainmatcher) | Создание `DomainMatcher` |
| Функция | [`geodata.BuildIPMatcher(...)`](#geodata-buildipmatcher) | Создание `IPMatcher` |
| Объект | [`DomainMatcher`](#domainmatcher) | Объект сопоставления доменов |
| Метод | [`domainMatcherObj:MatchAny(domain)`](#matchany) | Проверка совпадения домена с любым правилом |
| Метод | [`domainMatcherObj:Match(domain)`](#match) | Получение номеров совпавших правил домена |
| Объект | [`IPMatcher`](#ipmatcher) | Объект сопоставления IP |
| Метод | [`ipMatcherObj:Match(ip)`](#match-1) | Сопоставление отдельного IP |
| Метод | [`ipMatcherObj:AnyMatch(ips)`](#anymatch) | Проверка наличия совпавшего IP |
| Метод | [`ipMatcherObj:Matches(ips)`](#matches) | Проверка совпадения всего списка IP |
| Метод | [`ipMatcherObj:FilterIPs(ips)`](#filterips) | Разделение совпавших и несовпавших IP |
| Метод | [`ipMatcherObj:SetReverse(reverse)`](#setreverse) | Установка флага инверсии |
| Метод | [`ipMatcherObj:ToggleReverse()`](#togglereverse) | Переключение флага инверсии |
## Функции
### geodata.BuildDomainMatcher
```lua
local domainMatcherObj = geodata.BuildDomainMatcher(rule1, rule2, ...)
```
Создаёт [`DomainMatcher`](#domainmatcher) из правил доменов.
**Параметры**
| Параметр | Тип | Описание / Требования |
| ------------------- | -------- | -------------------------------------------------------------------- |
| `rule1, rule2, ...` | `string` | Обязательны; хотя бы одно правило домена, каждое передаётся отдельно |
**Возвращаемые значения**
| Значение | Тип | Описание |
| ------------------ | --------------------------------- | ------------------------------- |
| `domainMatcherObj` | [`DomainMatcher`](#domainmatcher) | Экземпляр сопоставления доменов |
**Поведение**
Если правила не переданы, тип аргумента неверен или произошла ошибка разбора правил, загрузки ресурсов или создания объекта, возникает исключение Lua.
Поддерживаются `domain:`, `full:`, `keyword:`, `regexp:`, `dotless:`, `geosite:` и `ext:` (также `ext-domain:` / `ext-site:`). Форматы описаны в [правилах доменов маршрутизации](../../../config/routing.md#ruleobject). Файлы GeoSite загружаются из [каталога ресурсов](../../../config/env.md#путь-к-фаилам-ресурсов).
Строки без префикса по умолчанию используют правило `domain:`.
Кроме регулярных выражений, правила при создании приводятся к нижнему регистру.
**Пример**
```lua
local sitesObj = geodata.BuildDomainMatcher(
"example.com", "full:other.example"
)
```
### geodata.BuildIPMatcher
```lua
local ipMatcherObj = geodata.BuildIPMatcher(rule1, rule2, ...)
```
Создаёт [`IPMatcher`](#ipmatcher) из правил IP.
**Параметры**
| Параметр | Тип | Описание / Требования |
| ------------------- | -------- | ---------------------------------------------------------------- |
| `rule1, rule2, ...` | `string` | Обязательны; хотя бы одно правило IP, каждое передаётся отдельно |
**Возвращаемые значения**
| Значение | Тип | Описание |
| -------------- | ------------------------- | -------------------------- |
| `ipMatcherObj` | [`IPMatcher`](#ipmatcher) | Экземпляр сопоставления IP |
**Поведение**
Если правила не переданы, тип аргумента неверен, правило является пустой строкой или произошла ошибка разбора правил, загрузки ресурсов или создания объекта, возникает исключение Lua.
Поддерживаются IP, CIDR, `geoip:`, `ext:` (также `ext-ip:`) и правила инверсии `!`. Сочетание правил описано в [правилах IP маршрутизации](../../../config/routing.md#ruleobject). Файлы GeoIP загружаются из [каталога ресурсов](../../../config/env.md#путь-к-фаилам-ресурсов).
**Пример**
```lua
local privateIPsObj = geodata.BuildIPMatcher(
"10.0.0.0/8", "192.168.0.0/16", "fc00::/7"
)
```
## Объекты
### DomainMatcher
| Свойство | Описание |
| ------------------- | -------------------------------------------------------------------------------------- |
| Базовый тип Go | Реализация интерфейса `geodata.DomainMatcher` |
| Представление в Lua | `userdata` |
| Получение | Возвращаемое значение [`geodata.BuildDomainMatcher(...)`](#geodata-builddomainmatcher) |
**Общие соглашения**
Методы сопоставления принимают одну строку домена. `nil`, отсутствие аргумента, неверный тип или число аргументов вызывают исключение Lua.
Входной домен не приводится к нижнему регистру автоматически; при необходимости это должен делать скрипт.
#### MatchAny
```lua
local matched = domainMatcherObj:MatchAny(domain)
```
Проверяет, совпадает ли домен хотя бы с одним правилом.
**Параметры**
| Параметр | Тип | Описание / Требования |
| -------- | -------- | ----------------------------------- |
| `domain` | `string` | Обязателен; домен для сопоставления |
**Возвращаемые значения**
| Значение | Тип | Описание |
| --------- | --------- | ------------------------------------ |
| `matched` | `boolean` | `true` при совпадении, иначе `false` |
**Пример**
```lua
local matched = sitesObj:MatchAny("www.example.com")
```
#### Match
```lua
local indices = domainMatcherObj:Match(domain)
```
Получает номера правил, с которыми совпал домен.
**Параметры**
| Параметр | Тип | Описание / Требования |
| -------- | -------- | ----------------------------------- |
| `domain` | `string` | Обязателен; домен для сопоставления |
**Возвращаемые значения**
| Значение | Тип | Описание |
| --------- | ---------------------------------------------- | --------------------------------------------------------------------------- |
| `indices` | [`[]uint32`](./data-types.md#uint32) или `nil` | Номера совпавших правил; при отсутствии совпадений — `nil` или срез длины 0 |
**Поведение**
Номера правил начинаются с **0** и соответствуют порядку правил, переданных при создании. Порядок результатов не гарантируется; возможны повторяющиеся номера. Записи, развёрнутые из GeoSite, сохраняют номер исходного правила.
Если те же правила сохранены в массиве Lua, исходное правило можно получить через `rules[ruleNumber + 1]`. Доступ к срезам описан в разделе [Типы данных](./data-types.md#slice).
**Пример**
```lua
local indices = sitesObj:Match("www.example.com")
if indices ~= nil then
for i = 1, #indices do
local ruleNumber = indices[i]
end
end
```
### IPMatcher
| Свойство | Описание |
| ------------------- | ------------------------------------------------------------------------------ |
| Базовый тип Go | Реализация интерфейса `geodata.IPMatcher` |
| Представление в Lua | `userdata` |
| Получение | Возвращаемое значение [`geodata.BuildIPMatcher(...)`](#geodata-buildipmatcher) |
**Общие соглашения**
Для отдельного IP используется [`net.IP`](./data-types.md#net-ip); для сопоставления или фильтрации списков формы ввода описаны в разделе [Ввод списка IP](./data-types.md#ввод-списка-ip). Строки IP-адресов не преобразуются в `net.IP` автоматически.
Методы сопоставления и фильтрации принимают явно переданный `nil`. Отсутствие аргументов, неверный тип или число аргументов вызывают исключение Lua.
#### Match
```lua
local matched = ipMatcherObj:Match(ip)
```
Проверяет, совпадает ли отдельный IP с правилами.
**Параметры**
| Параметр | Тип | Описание / Требования |
| -------- | -------------------------------------------- | ------------------------------- |
| `ip` | [`net.IP`](./data-types.md#net-ip) или `nil` | Обязателен; нужно передать явно |
**Возвращаемые значения**
| Значение | Тип | Описание |
| --------- | --------- | ------------------------------------------------------------------------- |
| `matched` | `boolean` | `true`, если допустимый IP совпал; `false` для `nil` или недопустимого IP |
**Поведение**
`""` или пустая таблица `{}` трактуются как пустой IP и возвращают `false`. Строки не разбираются как текст IP-адреса.
#### AnyMatch
```lua
local matched = ipMatcherObj:AnyMatch(ips)
```
Проверяет, совпадает ли с правилами хотя бы один допустимый IP.
**Параметры**
| Параметр | Тип | Описание / Требования |
| -------- | ------------------------------------------------ | -------------------------------------------------- |
| `ips` | [Ввод списка IP](./data-types.md#ввод-списка-ip) | Обязателен; нужно передать явно; допускается `nil` |
**Возвращаемые значения**
| Значение | Тип | Описание |
| --------- | --------- | ----------------------------------------------------------------------------------------------------------- |
| `matched` | `boolean` | `true`, если совпал хотя бы один допустимый IP; `false` для `nil`, пустого списка или отсутствия совпадений |
#### Matches
```lua
local matched = ipMatcherObj:Matches(ips)
```
Проверяет, совпадает ли с правилами весь список IP.
**Параметры**
| Параметр | Тип | Описание / Требования |
| -------- | ------------------------------------------------ | -------------------------------------------------- |
| `ips` | [Ввод списка IP](./data-types.md#ввод-списка-ip) | Обязателен; нужно передать явно; допускается `nil` |
**Возвращаемые значения**
| Значение | Тип | Описание |
| --------- | --------- | ---------------------------------------------------------------------------------------------------------------- |
| `matched` | `boolean` | `true`, если весь список удовлетворяет условиям; `false` для `nil`, пустого списка или списка с недопустимыми IP |
**Поведение**
Сочетание правил может содержать несколько внутренних объектов сопоставления. Один внутренний объект должен сопоставить весь список.
Например, для `geodata.BuildIPMatcher("192.168.1.0/24", "geoip:us")` список с `192.168.1.1` и `8.8.8.8` даёт `false` у `Matches`: первый IP совпадает с пользовательским CIDR, второй — с `geoip:us`, но эти правила принадлежат разным внутренним объектам, и ни один не сопоставляет весь список.
Если нужно проверить лишь наличие совпавшего адреса, используйте [`AnyMatch`](#anymatch).
#### FilterIPs
```lua
local matched, unmatched = ipMatcherObj:FilterIPs(ips)
```
Разделяет допустимые IP на совпавшие и несовпавшие группы.
**Параметры**
| Параметр | Тип | Описание / Требования |
| -------- | ------------------------------------------------ | -------------------------------------------------- |
| `ips` | [Ввод списка IP](./data-types.md#ввод-списка-ip) | Обязателен; нужно передать явно; допускается `nil` |
**Возвращаемые значения**
| Значение | Тип | Описание |
| ----------- | -------------------------------------- | -------------------------------- |
| `matched` | [`[]net.IP`](./data-types.md#net-ip-1) | Совпавшие IP; никогда не `nil` |
| `unmatched` | [`[]net.IP`](./data-types.md#net-ip-1) | Несовпавшие IP; никогда не `nil` |
**Поведение**
Группа без результатов является пустым срезом. При передаче `nil`, пустого списка или только недопустимых IP обе группы — пустые срезы.
Недопустимые IP отбрасываются; порядок результатов не обязательно совпадает с порядком ввода.
#### SetReverse
```lua
ipMatcherObj:SetReverse(reverse)
```
Устанавливает флаг инверсии каждого внутреннего объекта сопоставления.
**Параметры**
| Параметр | Тип | Описание / Требования |
| --------- | --------- | ------------------------------------------------------- |
| `reverse` | `boolean` | Обязателен; `true` включает инверсию, `false` отключает |
**Возвращаемые значения**
Нет возвращаемых значений.
**Поведение**
`nil`, отсутствие аргумента или неверный тип вызывают исключение Lua. Операция заменяет прежний флаг инверсии каждого внутреннего объекта, включая флаги `!` из правил. Инверсия действует только на семейства адресов исходного правила и не сопоставляет недопустимые IP.
Установленное состояние инверсии сохраняется в текущем объекте сопоставления. Если последующие вызовы Hook повторно используют этот объект, изменённое состояние продолжает действовать. См. [Состояние в экземплярах пула](../guide/lifecycle.md#состояние-в-экземплярах-пула).
**Пример**
После инверсии `10.0.0.0/8` сопоставляются допустимые адреса IPv4 вне этого диапазона:
```lua
local ipMatcherObj = geodata.BuildIPMatcher("10.0.0.0/8")
ipMatcherObj:SetReverse(true)
```
#### ToggleReverse
```lua
ipMatcherObj:ToggleReverse()
```
Переключает флаг инверсии каждого внутреннего объекта сопоставления.
**Параметры**
Дополнительных параметров нет.
**Возвращаемые значения**
Нет возвращаемых значений.
**Поведение**
Каждый внутренний объект в сочетании правил переключает собственный флаг инверсии. Результат не равнозначен логическому отрицанию всего сочетания.
Новое состояние инверсии сохраняется в текущем объекте сопоставления. Если последующие вызовы Hook повторно используют этот объект, изменённое состояние продолжает действовать. См. [Состояние в экземплярах пула](../guide/lifecycle.md#состояние-в-экземплярах-пула).