Max/XTLS_Xray-docs-next
1
0
Fork 0
mirror of https://github.com/XTLS/Xray-docs-next.git synced 2026-10-11 16:58:22 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
f179efd35d1fda797a853ed8fa98c98235e69fb2
XTLS_Xray-docs-next/docs/ru/development/lua/reference/module-geodata.md
T

345 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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#состояние-в-экземплярах-пула).
Reference in New Issue View Git Blame Copy Permalink