ip2region 升级支持 IPv6 地址解析
本文详细解析了 ip2region 在升级支持 IPv6 地址解析时遇到的兼
问题背景
线上日志出现 IPv6 地址解析异常:
ip2region 解析 IP 地址发生异常: 2409:8a55:4c6:4451:9809:5d17:fbb6:7d55
java.lang.Exception: invalid ip address `2409:8a55:4c6:4451:9809:5d17:fbb6:7d55`
at org.lionsoul.ip2region.xdb.Searcher.checkIP(Searcher.java:256)
at org.lionsoul.ip2region.xdb.Searcher.search(Searcher.java:75)
问题原因
旧版 ip2region 2.7.0 的 Searcher.search(String ip) 方法内部 checkIP() 只支持 IPv4 格式(如 192.168.1.1),对于 IPv6 格式会直接抛出异常。
解决方案
升级到 ip2region 新版 API(3.0.0+),使用 Ip2Region 服务类,原生支持 IPv4/IPv6 双栈查询。
1. Maven 依赖
xml
<!-- ip2region 离线IP地址库(新版支持 IPv6) -->
<dependency>
<groupId>org.lionsoul</groupId>
<artifactId>ip2region</artifactId>
<version>3.0.0</version>
</dependency>
2. 数据库文件
需要准备两个 xdb 数据库文件:
ip2region_v4.xdb- IPv4 数据库(约 11MB)ip2region_v6.xdb- IPv6 数据库(约 100MB+)
放置路径:src/main/resources/ip2region/
数据库下载地址:https://gitee.com/lionsoul/ip2region/tree/master/data
3. 缓存策略说明
| 策略 | 说明 | 内存占用 | 适用场景 |
|---|---|---|---|
Config.NoCache |
不缓存,每次查询都读取文件 | 最小 | 内存极度敏感场景 |
Config.VIndexCache |
只缓存向量索引 | 约几MB | 推荐:低内存服务器 |
Config.BufferCache |
全量缓存到内存 | 约 100MB+ | 高并发、内存充足场景 |
4. 代码实现
方案一:高内存方案(BufferCache)
适用于内存充足的服务器(建议 4G+ 内存)。
java
import org.lionsoul.ip2region.service.Config;
import org.lionsoul.ip2region.service.Ip2Region;
import org.springframework.core.io.ClassPathResource;
public class IpUtils {
private static Ip2Region ip2Region;
static {
try {
// 加载 IPv4 数据库
ClassPathResource resourceV4 = new ClassPathResource("ip2region/ip2region_v4.xdb");
InputStream inputStreamV4 = resourceV4.getInputStream();
// 加载 IPv6 数据库
ClassPathResource resourceV6 = new ClassPathResource("ip2region/ip2region_v6.xdb");
InputStream inputStreamV6 = resourceV6.getInputStream();
// 创建 IPv4 配置
// 注意:从 InputStream 加载时只能使用 BufferCache 缓存策略
Config v4Config = Config.custom()
.setCachePolicy(Config.BufferCache) // 全量缓存
.setSearchers(10) // 查询器数量
.setXdbInputStream(inputStreamV4) // 数据库输入流
.asV4(); // 指定为 IPv4 配置
// 创建 IPv6 配置
Config v6Config = Config.custom()
.setCachePolicy(Config.BufferCache)
.setSearchers(10)
.setXdbInputStream(inputStreamV6)
.asV6();
// 创建 Ip2Region 查询服务
ip2Region = Ip2Region.create(v4Config, v6Config);
} catch (Exception e) {
log.error("ip2region 初始化失败", e);
}
}
}
方案二:低内存方案(VIndexCache)⭐ 推荐
适用于内存较小的服务器(如 2G 内存的云服务器)。
踩坑记录:使用 BufferCache 策略时,会把整个 xdb 文件加载到内存,IPv4 + IPv6 数据库加起来超过 100MB,在 2G 内存的服务器上容易触发 OOM:
java.lang.OutOfMemoryError: Java heap space
at org.lionsoul.ip2region.xdb.Searcher.loadContentFromInputStream(Searcher.java:294)
at org.lionsoul.ip2region.service.ConfigBuilder.build(ConfigBuilder.java:77)
解决方案:使用 VIndexCache 策略,只缓存向量索引,内存占用从 100MB+ 降到几 MB。
但 VIndexCache 需要文件路径,不能直接用 InputStream,所以需要先把 xdb 文件从 jar 包解压到临时目录:
java
import cn.hutool.core.io.FileUtil;
import org.lionsoul.ip2region.service.Config;
import org.lionsoul.ip2region.service.Ip2Region;
import org.springframework.core.io.ClassPathResource;
import java.io.File;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.StandardCopyOption;
public class IpUtils {
private static Ip2Region ip2Region;
private static File tempV4File;
private static File tempV6File;
static {
try {
// 将 xdb 文件从 classpath 复制到临时目录
tempV4File = copyToTempFile("ip2region/ip2region_v4.xdb", "ip2region_v4", ".xdb");
tempV6File = copyToTempFile("ip2region/ip2region_v6.xdb", "ip2region_v6", ".xdb");
// 创建 IPv4 配置:使用 VIndexCache 缓存策略(低内存占用)
Config v4Config = Config.custom()
.setCachePolicy(Config.VIndexCache) // 只缓存向量索引
.setSearchers(5) // 减少查询器数量
.setXdbPath(tempV4File.getAbsolutePath())
.asV4();
// 创建 IPv6 配置
Config v6Config = Config.custom()
.setCachePolicy(Config.VIndexCache)
.setSearchers(5)
.setXdbPath(tempV6File.getAbsolutePath())
.asV6();
// 创建 Ip2Region 查询服务
ip2Region = Ip2Region.create(v4Config, v6Config);
log.info("ip2region 初始化成功(VIndexCache 低内存模式)");
} catch (Exception e) {
log.error("ip2region 初始化失败", e);
}
}
/**
* 将 classpath 资源复制到临时文件
*/
private static File copyToTempFile(String resourcePath, String prefix, String suffix) throws Exception {
ClassPathResource resource = new ClassPathResource(resourcePath);
File tempFile = File.createTempFile(prefix, suffix);
tempFile.deleteOnExit(); // JVM 退出时删除
try (InputStream is = resource.getInputStream()) {
Files.copy(is, tempFile.toPath(), StandardCopyOption.REPLACE_EXISTING);
}
return tempFile;
}
/**
* 关闭服务(应用关闭时调用)
*/
public static void close() {
if (ip2Region != null) {
try {
ip2Region.close();
} catch (Exception e) {
log.error("关闭 ip2region 服务失败", e);
}
}
// 清理临时文件
if (tempV4File != null && tempV4File.exists()) {
FileUtil.del(tempV4File);
}
if (tempV6File != null && tempV6File.exists()) {
FileUtil.del(tempV6File);
}
}
}
5. 返回格式
新版 API 统一返回 4 个字段:国家|省份|城市|ISP
⚠️ 注意:与旧版 5 字段格式(国家|区域|省份|城市|ISP)不同,新版去掉了"区域"字段。
实际测试结果:
===== IPv4 测试 =====
IP: 114.114.114.114
原始结果: 中国|江苏省|南京市|0
解析: country=中国, province=江苏省, city=南京市, isp=
IP: 8.8.8.8
原始结果: 美国|0|0|Level3
解析: country=美国, province=, city=, isp=Level3
IP: 47.119.142.252
原始结果: 中国|上海|上海市|阿里巴巴
解析: country=中国, province=上海, city=上海市, isp=阿里巴巴
===== IPv6 测试 =====
IP: 2409:8a55:4c6:4451:9809:5d17:fbb6:7d55
原始结果: 中国|广东省|东莞市|移动网络
解析: country=中国, province=广东省, city=东莞市, isp=移动网络
IP: 2001:4860:4860::8888
原始结果: 美国|加利福尼亚州|圣克拉拉|专线用户
解析: country=美国, province=加利福尼亚州, city=圣克拉拉, isp=专线用户
6. 解析代码示例
java
String region = ip2Region.search(ipAddress); // 如:中国|广东省|东莞市|移动网络
String[] parts = region.split("\\|");
// 统一 4 字段格式:国家|省份|城市|ISP
String country = parts.length >= 1 ? parts[0] : ""; // 中国
String province = parts.length >= 2 ? parts[1] : ""; // 广东省
String city = parts.length >= 3 ? parts[2] : ""; // 东莞市
String isp = parts.length >= 4 ? parts[3] : ""; // 移动网络
// 处理 "0" 表示无数据的情况
if ("0".equals(country)) country = "";
if ("0".equals(province)) province = "";
if ("0".equals(city)) city = "";
if ("0".equals(isp)) isp = "";
踩坑总结
坑1:旧版 Searcher 不支持 IPv6
现象:查询 IPv6 地址时抛出 invalid ip address 异常
原因:旧版 Searcher.checkIP() 只校验 IPv4 格式
解决:升级到新版 Ip2Region 服务类
坑2:BufferCache 导致 OOM
现象:服务启动时或首次查询时触发 OutOfMemoryError: Java heap space
原因:BufferCache 策略会把整个 xdb 文件加载到内存,IPv6 数据库超过 100MB
解决:使用 VIndexCache 策略,先复制到临时文件再加载
坑3:InputStream 加载只能用 BufferCache
现象:使用 setXdbInputStream() 时设置 VIndexCache 无效
原因:VIndexCache 需要随机读取文件,InputStream 只能顺序读取
解决:先复制到临时文件,再用 setXdbPath() 加载
坑4:新版返回格式变了
现象:解析结果字段错位,省份变成了城市
原因:旧版返回 5 字段(国家|区域|省份|城市|ISP),新版返回 4 字段(国家|省份|城市|ISP)
解决:按新版 4 字段格式解析
官方资源
- GitHub: https://github.com/lionsoul2014/ip2region
- Gitee: https://gitee.com/lionsoul/ip2region
- Java Binding: https://gitee.com/lionsoul/ip2region/tree/master/binding/java
总结
- 旧版
Searcher类只支持 IPv4,新版Ip2Region类支持 IPv4/IPv6 双栈 - 低内存服务器(2G 以下)建议使用
VIndexCache策略,避免 OOM - 从 jar 包资源加载时,
VIndexCache需要先复制到临时文件 - 新版返回格式统一为 4 字段:
国家|省份|城市|ISP - 应用关闭时记得调用
ip2Region.close()释放资源