mirror of
https://github.com/XTLS/Xray-docs-next.git
synced 2026-10-13 09:48:13 +03:00
345 lines
12 KiB
Markdown
345 lines
12 KiB
Markdown
# xray.geodata
|
||
|
||
提供域名和 IP 的规则匹配功能。
|
||
|
||
```lua
|
||
local geodata = require("xray.geodata")
|
||
```
|
||
|
||
## 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, ...)
|
||
```
|
||
|
||
根据 IP 规则创建 [`IPMatcher`](#ipmatcher)。
|
||
|
||
**参数**
|
||
|
||
| 参数 | 类型 | 说明 / 要求 |
|
||
| ------------------- | -------- | -------------------------------- |
|
||
| `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 的 slice |
|
||
|
||
**行为约定**
|
||
|
||
规则编号从 **0** 开始，对应构建时传入的规则顺序。结果顺序不保证，可能包含重复编号；GeoSite 展开的条目沿用其所属规则的编号。
|
||
|
||
若将同一组规则保存在 Lua 数组中，可用 `rules[ruleNumber + 1]` 取得原规则。slice 的访问方式见[数据类型](./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` | 有效 IP 命中时为 `true`；`nil` 或无效 IP 为 `false` |
|
||
|
||
**行为约定**
|
||
|
||
传入 `""` 或空 table `{}` 时，会被视为空 IP 并返回 `false`；字符串不会按 IP 地址文本解析。
|
||
|
||
#### AnyMatch
|
||
|
||
```lua
|
||
local matched = ipMatcherObj:AnyMatch(ips)
|
||
```
|
||
|
||
判断是否至少有一个有效 IP 命中规则。
|
||
|
||
**参数**
|
||
|
||
| 参数 | 类型 | 说明 / 要求 |
|
||
| ----- | ------------------------------------------ | ---------------------------- |
|
||
| `ips` | [IP 列表输入](./data-types.md#ip-列表输入) | 必填，须显式传入，允许 `nil` |
|
||
|
||
**返回值**
|
||
|
||
| 返回值 | 类型 | 说明 |
|
||
| --------- | --------- | ------------------------------------------------------------------ |
|
||
| `matched` | `boolean` | 至少一个有效 IP 命中时为 `true`；`nil`、空列表或未命中时为 `false` |
|
||
|
||
#### Matches
|
||
|
||
```lua
|
||
local matched = ipMatcherObj:Matches(ips)
|
||
```
|
||
|
||
判断整个 IP 列表是否命中规则。
|
||
|
||
**参数**
|
||
|
||
| 参数 | 类型 | 说明 / 要求 |
|
||
| ----- | ------------------------------------------ | ---------------------------- |
|
||
| `ips` | [IP 列表输入](./data-types.md#ip-列表输入) | 必填，须显式传入，允许 `nil` |
|
||
|
||
**返回值**
|
||
|
||
| 返回值 | 类型 | 说明 |
|
||
| --------- | --------- | ---------------------------------------------------------------------- |
|
||
| `matched` | `boolean` | 整个列表满足匹配要求时为 `true`；`nil`、空列表或含无效 IP 时为 `false` |
|
||
|
||
**行为约定**
|
||
|
||
组合规则可能包含多个内部匹配器，必须有一个内部匹配器命中整个列表。
|
||
|
||
例如，用 `geodata.BuildIPMatcher("192.168.1.0/24", "geoip:us")` 构建匹配器，输入列表同时包含 `192.168.1.1` 和 `8.8.8.8` 时，`Matches` 返回 `false`：前者命中 custom 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` |
|
||
|
||
**行为约定**
|
||
|
||
没有结果的一组为空 slice；传入 `nil`、空列表或全部无效 IP 时，两组均为空 slice。
|
||
|
||
无效 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#池化实例内状态)。
|