04.22 ip2region 离线IP定位接入与部署说明

102353 于 2026-10-17 14:14:33 +08:00 修改了此页面

ip2region 离线IP定位接入与部署说明

一、功能说明

项目通过 ip2region_v4.xdb 本地离线库查询 IPv4 归属地，用于登录日志地址记录、商城用户省市更新等场景。

核心工具类：

joolun-common/joolun-common-core/src/main/java/com/joolun/cloud/common/core/util/IpUtils.java

依赖模块：

joolun-common/joolun-common-core

依赖坐标：

<dependency>
    <groupId>org.lionsoul</groupId>
    <artifactId>ip2region</artifactId>
</dependency>

如果离线库不存在、IP 格式异常或查询失败，系统会返回空地址，不抛出异常，不影响登录、注册、用户资料更新等主流程。

二、离线库文件

需要准备文件：

ip2region_v4.xdb

下载地址：

https://raw.githubusercontent.com/lionsoul2014/ip2region/master/data/ip2region_v4.xdb

IPv6 数据文件：

https://raw.githubusercontent.com/lionsoul2014/ip2region/master/data/ip2region_v6.xdb

本项目统一使用官方当前 IPv4 数据文件名 ip2region_v4.xdb，不需要重命名。

官方目录：

https://github.com/lionsoul2014/ip2region/tree/master/data

建议从 ip2region 官方仓库或可信发布渠道获取，并在上线前确认文件来源可靠。

生产环境推荐路径：

/data/ip2region/ip2region_v4.xdb

Windows 环境示例路径：

C:\data\ip2region\ip2region_v4.xdb

三、配置方式

1. Nacos 或 application.yml

推荐使用该方式：

joolun:
  ip2region:
    xdb-path: /data/ip2region/ip2region_v4.xdb

2. 环境变量

适合 Docker、K8s 部署：

IP2REGION_XDB_PATH=/data/ip2region/ip2region_v4.xdb

3. JVM 参数

适合 jar 方式部署：

java -Djoolun.ip2region.xdb-path=/data/ip2region/ip2region_v4.xdb -jar joolun-auth.jar

兼容参数：

java -Dip2region.xdb.path=/data/ip2region/ip2region_v4.xdb -jar joolun-auth.jar

4. classpath 内置

如果未配置外部路径，系统会尝试从以下位置读取：

classpath:/ip2region/ip2region_v4.xdb
classpath:/ip2region_v4.xdb

源码目录可放在：

joolun-common/joolun-common-core/src/main/resources/ip2region/ip2region_v4.xdb

该方式适合测试环境或单机部署，生产环境建议使用外部挂载路径。

五、jar 部署

Linux 目录示例：

/data/app/joolun-auth.jar
/data/ip2region/ip2region_v4.xdb

启动命令：

java -Djoolun.ip2region.xdb-path=/data/ip2region/ip2region_v4.xdb -jar /data/app/joolun-auth.jar

Windows 示例：

$env:IP2REGION_XDB_PATH="C:\data\ip2region\ip2region_v4.xdb"
java -jar C:\data\app\joolun-auth.jar

六、验证方法

1. 启动日志

首次调用 IP 查询时，应看到类似日志：

加载 ip2region 离线IP库：/data/ip2region/ip2region_v4.xdb

如果文件不存在，会看到类似日志：

未找到 ip2region 离线IP库，请配置 joolun.ip2region.xdb-path 或将 ip2region_v4.xdb 放入 classpath:/ip2region/

该日志只会打印一次，避免持续刷屏。

2. 登录日志

登录后台后，检查登录日志地址字段是否有值。

涉及服务：

joolun-auth

3. 小程序用户省市

小程序用户登录或触发省市更新后，检查用户表中的省份和城市字段是否有值。

涉及服务：

joolun-mall-api

七、故障排查

1. 提示找不到 ip2region_v4.xdb

检查配置路径是否正确：

ls -l /data/ip2region/ip2region_v4.xdb

K8s 中检查 Pod 内路径：

kubectl exec -it <pod-name> -- ls -l /data/ip2region/ip2region_v4.xdb

2. 配置了路径但仍无效

检查环境变量：

kubectl exec -it <pod-name> -- printenv IP2REGION_XDB_PATH

检查 Nacos 或 YAML 配置：

joolun:
  ip2region:
    xdb-path: /data/ip2region/ip2region_v4.xdb

3. 地址为空但没有报错

常见原因：

ip2region_v4.xdb 不存在。
IP 是内网地址，例如 127.0.0.1、10.x.x.x、172.16.x.x、192.168.x.x。
网关或代理没有正确透传真实客户端 IP。
IP 库版本较旧，查询不到最新地址。

4. K8s 中拿到的是 Pod IP 或网关 IP

需要检查：

Ingress 是否透传 X-Forwarded-For。
网关是否保留真实客户端 IP。
应用读取 IP 的工具是否从正确请求头取值。
负载均衡器是否开启真实 IP 透传。

八、运维建议

ip2region_v4.xdb 建议按季度或半年更新一次。
生产环境建议使用外部挂载路径，避免每次更新都重新发版。
不要把 IP 解析作为核心业务强依赖，失败时应允许业务继续执行。
如果业务需要高精度定位，应改用用户授权地理位置或地图服务。

九、关闭定位

如需临时关闭 IP 定位，不配置 ip2region_v4.xdb 文件即可。系统会自动降级为空地址，不影响主流程。