You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
|
|
1 month ago | |
|---|---|---|
| .. | ||
| LINGYUN/Abp/MaxMindGeoIP2 | 1 month ago | |
| LINGYUN.Abp.MaxMindGeoIP2.csproj | 1 month ago | |
| README.EN.md | 1 month ago | |
| README.md | 1 month ago | |
README.md
LINGYUN.Abp.MaxMindGeoIP2
介绍
LINGYUN.Abp.MaxMindGeoIP2 是一个基于 MaxMind.GeoIP2 的 ABP 框架模块,
通过 mmdb 离线库(需由使用方提供, 见下文)解析 IP 地理位置,并注册 LINGYUN.Abp.IP.Location 的位置解析贡献者,
可与 LINGYUN.Abp.IP2Region 互换使用(备注规则保持一致)。
功能
- 通过 mmdb 离线库解析 IP 地理位置(国家/省份/城市)
- 不内置离线库:GeoLite2 受 MaxMind 许可约束、不得随包分发,需通过
MaxMindGeoIP2:DatabaseFile指向使用方自行下载的 mmdb 文件 - 离线库文件不存在时使用
EmptyGeoIP2DatabaseReader(解析空内容,位置为空并记录警告日志),不会阻断业务 - 同时支持 IPv4 与 IPv6(取决于离线库)
- 按当前文化解析地理名称(从
Names获取,缺失时回退Name) - 本地回环、内网、保留地址等无记录地址不返回数据(备注为空)
- 支持 ABP 虚拟文件系统
安装
dotnet add package LINGYUN.Abp.MaxMindGeoIP2
使用
- 添加
[DependsOn(typeof(AbpMaxMindGeoIP2Module))]到你的模块类上。
[DependsOn(typeof(AbpMaxMindGeoIP2Module))]
public class YourModule : AbpModule
{
// ...
}
- 注入
IIPLocationResolver解析 IP 位置:
public class YourService
{
private readonly IIPLocationResolver _ipLocationResolver;
public YourService(IIPLocationResolver ipLocationResolver)
{
_ipLocationResolver = ipLocationResolver;
}
public async Task<string?> ResolveAsync(string ip)
{
var result = await _ipLocationResolver.ResolveAsync(ip);
// 223.5.5.5 => 浙江杭州
return result.Location?.Remarks;
}
}
选项
Configure<AbpMaxMindGeoIP2Options>(options =>
{
// 离线库文件路径(必填): 需自行从 MaxMind 下载并接受其许可协议
options.DatabaseFile = "/data/GeoLite2-City.mmdb";
// 文件打开方式,默认内存映射
options.FileAccessMode = FileAccessMode.MemoryMapped;
});
{
"MaxMindGeoIP2": {
"DatabaseFile": "/data/GeoLite2-City.mmdb",
"FileAccessMode": "MemoryMapped"
}
}
地理名称与文化
查询器不指定 locales(即以离线库默认名称 Name 打开),地理名称在解析时按当前文化
(CultureInfo.CurrentUICulture)从 MaxMind 的 Names 字典中获取:
- 先按完整文化名称匹配(如
zh-CN),未命中再按语言名称匹配(如es-MX→es); - 仍未命中时回退到
Name(离线库默认语言,通常为英语); - GeoLite2-City 离线库提供
de,en,es,fr,ja,pt-BR,ru,zh-CN语言,部分实体只提供少数语言(此时按上述规则回退)。
因此同一个单例查询器可为所有文化提供服务,无需按语言创建多个查询器。
| 当前文化 | 8.8.8.8 的备注 |
223.5.5.5 的备注 |
|---|---|---|
zh-CN |
美国 | 浙江杭州 |
en-US |
United States | China |
ja-JP |
アメリカ | 中国 |
ko-KR(离线库无该语言,回退 Name) |
United States | China |
备注(Remarks)规则
备注(Remarks)规则由 LINGYUN.Abp.IP.Location 统一处理,与 LINGYUN.Abp.IP2Region 共用同一份配置:
Configure<AbpIPLocationResolveOptions>(options =>
{
// 匹配到的国家名称从备注中移除(仅中国IP不显示国家)
options.RemoveCountry = new[] { "中国" };
// 匹配到的省份名称从备注中移除
// options.RemoveProvince = new[] { "香港特别行政区" };
});
也可以直接使用配置节(LINGYUN.Abp.IP.Location 模块绑定 IPLocation 节):
{
"IPLocation": {
"RemoveCountry": [ "中国" ]
}
}
# docker-compose environment
- IPLocation__RemoveCountry__0=中国
| 场景 | Remarks 示例 |
|---|---|
国家名称匹配 RemoveCountry,且有省份与城市 |
浙江杭州(省市同名时仅显示市,如 重庆市) |
国家名称匹配 RemoveCountry,且仅有省份 |
香港特别行政区 |
国家名称匹配 RemoveCountry,且仅有国家数据 |
空 |
省份名称匹配 RemoveProvince |
杭州(仅使用城市) |
| 都未匹配 | 美国、日本、德国(仅国家名称) |
| 本地回环 / 内网 / 保留 / 离线库未收录 | 空 |
名称匹配忽略大小写与首尾空白,适用于所有国家的 IP 地址解析。
性能基准
使用 BenchmarkDotNet(MemoryDiagnoser + InProcessEmitToolchain)测得:
BenchmarkDotNet v0.15.8, Windows 10.0.26100
Intel Core i7-14700K (20C/28T), .NET 10.0.12 (SDK 10.0.401), X64 RyuJIT x86-64-v3
GC=Concurrent Workstation, Toolchain=InProcessEmitToolchain (IterationCount=15)
| 方法 | Mean | Error | StdDev | Ratio | Gen0 | Gen1 | Allocated |
|---|---|---|---|---|---|---|---|
DatabaseReader_TryCity_IPv4(基线) |
3.428 μs | 0.0415 μs | 0.0388 μs | 1.00 | 0.4807 | 0.0038 | 8.15 KB |
DatabaseReader_TryCity_IPv6 |
3.496 μs | 0.0273 μs | 0.0228 μs | 1.02 | 0.4807 | 0.0038 | 8.15 KB |
DatabaseReader_TryCity_String_IPv4 |
3.428 μs | 0.0611 μs | 0.0542 μs | 1.00 | 0.4845 | 0.0038 | 8.19 KB |
ResolveAsync_IPv4(模块全链路) |
3.753 μs | 0.0426 μs | 0.0399 μs | 1.09 | 0.5112 | 0.0076 | 8.73 KB |
ResolveAsync_IPv6(模块全链路) |
3.812 μs | 0.0364 μs | 0.0323 μs | 1.11 | 0.5188 | 0.0076 | 8.78 KB |
- 单次查询约 3.4 μs(单线程理论吞吐约 29 万次/秒),IPv6 与 IPv4 基本一致(
Ratio1.02); TryCity(IPAddress)与TryCity(string)无差异,字符串解析开销可忽略;- 经
IIPLocationResolver的完整链路(DI Scope + 贡献者 + 按当前文化解析名称)仅增加约 9%~11%; - 每次查询分配约 8.15 KB(
CityResponse模型对象图),完整链路约 8.73 KB —— 高并发场景建议关注 GC(例如对热点 IP 做结果缓存); - 测量场景:
TryCity使用物理 mmdb + 内存映射(FileAccessMode.MemoryMapped,推荐的部署方式);ResolveAsync使用模块默认配置(配置的离线库 +IIPLocationResolver); - 基准使用 in-process 工具链(当前环境无法派生独立基准进程),数值会略优于独立进程模式,仅用于横向对比。
mmdb 离线库说明
- 本模块不内置离线库:GeoLite2 数据库受 MaxMind 最终用户许可协议(EULA)
约束,不得随包分发,因此需要由使用方自行下载并通过
MaxMindGeoIP2:DatabaseFile指定文件路径; - 未配置(或文件不存在)时,模块注册
EmptyGeoIP2DatabaseReader——相当于解析一份空内容:TryCity/TryCountry等返回false、City/Country等抛出AddressNotFoundException(与真实解读器未命中时一致),位置解析结果为空并记录一条警告日志,不影响业务流程; - GeoLite2 需要 MaxMind 账号 与 License Key 才能下载与定期更新,
生产环境建议通过
DatabaseFile指向物理文件并定期替换; - 离线 mmdb 文件也可从 wp-statistics/GeoLite2-City 仓库下载:
仓库中提供的是压缩包
GeoLite2-City.mmdb.gz,解压后得到GeoLite2-City.mmdb, 再通过MaxMindGeoIP2:DatabaseFile指向该文件; 直接下载地址:https://raw.githubusercontent.com/wp-statistics/GeoLite2-City/master/GeoLite2-City.mmdb.gz - GeoLite2-City 同时支持 IPv4 与 IPv6,并提供
de,en,es,fr,ja,pt-BR,ru,zh-CN语言; - 非法地址、本地回环与未指定地址由
IIPLocationResolver统一处理(返回空结果,不进入位置解析模块); - 离线库没有记录的地址(内网、保留、未收录)返回空的
IPLocation(国家/省份/城市与备注均为空); - 查询异常(例如离线库文件损坏)不会阻断业务流程:记录警告日志并按无数据处理(返回空位置)。