xray.geodata

提供域名和 IP 的规则匹配功能。

lua

local geodata = require("xray.geodata")

API 索引

分类	成员	说明
函数	`geodata.BuildDomainMatcher(...)`	创建 `DomainMatcher`
函数	`geodata.BuildIPMatcher(...)`	创建 `IPMatcher`
对象	`DomainMatcher`	域名匹配器
方法	`domainMatcherObj:MatchAny(domain)`	判断域名是否命中任意规则
方法	`domainMatcherObj:Match(domain)`	取得命中的域名规则编号
对象	`IPMatcher`	IP 匹配器
方法	`ipMatcherObj:Match(ip)`	匹配单个 IP
方法	`ipMatcherObj:AnyMatch(ips)`	判断是否有 IP 命中
方法	`ipMatcherObj:Matches(ips)`	判断整个 IP 列表是否命中
方法	`ipMatcherObj:FilterIPs(ips)`	分离命中和未命中的 IP
方法	`ipMatcherObj:SetReverse(reverse)`	设置反选标记
方法	`ipMatcherObj:ToggleReverse()`	切换反选标记

函数

geodata.BuildDomainMatcher

lua

local domainMatcherObj = geodata.BuildDomainMatcher(rule1, rule2, ...)

根据域名规则创建 DomainMatcher。

参数

参数	类型	说明 / 要求
`rule1, rule2, ...`	`string`	必填，至少一条域名规则，逐个传入

返回值

返回值	类型	说明
`domainMatcherObj`	`DomainMatcher`	域名匹配器实例

行为约定

未传入规则、参数类型错误，或规则解析、资源加载、构建失败时，抛出 Lua 异常。

支持 domain:、full:、keyword:、regexp:、dotless:、geosite:、ext:（亦可写为 ext-domain: / ext-site:），格式见路由域名规则。GeoSite 文件从资源目录加载。

无前缀字符串默认使用 domain: 规则。

除正则表达式外，规则在构建时转为小写。

示例

lua

local sitesObj = geodata.BuildDomainMatcher(
    "example.com", "full:other.example"
)

geodata.BuildIPMatcher

lua

local ipMatcherObj = geodata.BuildIPMatcher(rule1, rule2, ...)

根据 IP 规则创建 IPMatcher。

参数

参数	类型	说明 / 要求
`rule1, rule2, ...`	`string`	必填，至少一条 IP 规则，逐个传入

返回值

返回值	类型	说明
`ipMatcherObj`	`IPMatcher`	IP 匹配器实例

行为约定

未传入规则、参数类型错误、规则为空字符串，或规则解析、资源加载、构建失败时，抛出 Lua 异常。

支持 IP、CIDR、geoip:、ext:（亦可写为 ext-ip:）及 ! 反选规则，组合方式见路由 IP 规则。GeoIP 文件从资源目录加载。

示例

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(...)` 的返回值

通用约定

匹配方法接收一个域名字符串。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` 或 `nil`	命中的规则编号；未命中时为 `nil` 或长度为 0 的 slice

行为约定

规则编号从 0 开始，对应构建时传入的规则顺序。结果顺序不保证，可能包含重复编号；GeoSite 展开的条目沿用其所属规则的编号。

若将同一组规则保存在 Lua 数组中，可用 rules[ruleNumber + 1] 取得原规则。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(...)` 的返回值

通用约定

匹配单个 IP 时使用 net.IP；匹配或筛选列表时，输入形式见 IP 列表输入。IP 地址字符串不会自动解析为 net.IP。

匹配和筛选方法均接受显式的 nil。省略参数、类型或参数数量错误会抛出 Lua 异常。

Match

lua

local matched = ipMatcherObj:Match(ip)

判断单个 IP 是否命中规则。

参数

参数	类型	说明 / 要求
`ip`	`net.IP` 或 `nil`	必填，须显式传入

返回值

返回值	类型	说明
`matched`	`boolean`	有效 IP 命中时为 `true`；`nil` 或无效 IP 为 `false`

行为约定

传入 "" 或空 table {} 时，会被视为空 IP 并返回 false；字符串不会按 IP 地址文本解析。

AnyMatch

lua

local matched = ipMatcherObj:AnyMatch(ips)

判断是否至少有一个有效 IP 命中规则。

参数

参数	类型	说明 / 要求
`ips`	IP 列表输入	必填，须显式传入，允许 `nil`

返回值

返回值	类型	说明
`matched`	`boolean`	至少一个有效 IP 命中时为 `true`；`nil`、空列表或未命中时为 `false`

Matches

lua

local matched = ipMatcherObj:Matches(ips)

判断整个 IP 列表是否命中规则。

参数

参数	类型	说明 / 要求
`ips`	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。

FilterIPs

lua

local matched, unmatched = ipMatcherObj:FilterIPs(ips)

将有效 IP 分为命中和未命中两组。

参数

参数	类型	说明 / 要求
`ips`	IP 列表输入	必填，须显式传入，允许 `nil`

返回值

返回值	类型	说明
`matched`	`[]net.IP`	命中的 IP，始终非 `nil`
`unmatched`	`[]net.IP`	未命中的 IP，始终非 `nil`

行为约定

没有结果的一组为空 slice；传入 nil、空列表或全部无效 IP 时，两组均为空 slice。

无效 IP 会被丢弃，结果顺序不保证与输入相同。

SetReverse

lua

ipMatcherObj:SetReverse(reverse)

设置各内部匹配器的反选标记。

参数

参数	类型	说明 / 要求
`reverse`	`boolean`	必填，`true` 开启反选，`false` 关闭反选

返回值

无返回值。

行为约定

nil、省略参数或类型错误会抛出 Lua 异常。此操作覆盖各内部匹配器原有的反选标记，包括规则中 ! 指定的标记。反选只作用于原规则包含的地址族，且不会匹配无效 IP。

设置后的反选状态保存在当前匹配器对象中。如果后续 Hook 调用复用该对象，修改后的状态也会继续生效，见池化实例内状态。

示例

对 10.0.0.0/8 反选后，匹配该范围以外的有效 IPv4 地址：

lua

local ipMatcherObj = geodata.BuildIPMatcher("10.0.0.0/8")
ipMatcherObj:SetReverse(true)

ToggleReverse

lua

ipMatcherObj:ToggleReverse()

切换各内部匹配器的反选标记。

参数

无额外参数。

返回值

无返回值。

行为约定

组合规则中的各内部匹配器分别切换反选标记，结果不等同于对整个组合结果取逻辑反。切换后的反选状态保存在当前匹配器对象中。如果后续 Hook 调用复用该对象，修改后的状态也会继续生效，见池化实例内状态。

入门

编写指南

参考

xray.geodata

API 索引

函数

geodata.BuildDomainMatcher

geodata.BuildIPMatcher

对象

DomainMatcher

MatchAny

Match

IPMatcher

Match

AnyMatch

Matches

FilterIPs

SetReverse

ToggleReverse

xray.geodata ​

API 索引 ​

函数 ​

geodata.BuildDomainMatcher ​

geodata.BuildIPMatcher ​

对象 ​

DomainMatcher ​

MatchAny ​

Match ​

IPMatcher ​

Match ​

AnyMatch ​

Matches ​

FilterIPs ​

SetReverse ​

ToggleReverse ​

xray.geodata

API 索引

函数

geodata.BuildDomainMatcher

geodata.BuildIPMatcher

对象

DomainMatcher

MatchAny

Match

IPMatcher

Match

AnyMatch

Matches

FilterIPs

SetReverse

ToggleReverse