ip2region 升级支持 IPv6 地址解析

2025-12-20后端4 分钟355 次阅读
AI 摘要salmon-ai

本文详细解析了 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 字段格式解析

官方资源

总结

  1. 旧版 Searcher 类只支持 IPv4,新版 Ip2Region 类支持 IPv4/IPv6 双栈
  2. 低内存服务器(2G 以下)建议使用 VIndexCache 策略,避免 OOM
  3. 从 jar 包资源加载时,VIndexCache 需要先复制到临时文件
  4. 新版返回格式统一为 4 字段:国家|省份|城市|ISP
  5. 应用关闭时记得调用 ip2Region.close() 释放资源
觉得有用就点个赞,不用登录也能读

评论

0 条
登录 之后才能评论
—
还没有评论,来说第一句