跳到主要内容

地区管理

核心概念：系统管理 | 地区管理 | 概述 | MaxMind 数据库 | 只读查询

1. 概述​

系统内目前存在两套 IP 数据库，但在实际业务中，我们主要使用 MaxMind 国家地区数据库（GeoLite2-Country.mmdb）来进行 IP 定位和国家识别。

页面上的【地区管理】功能主要用于只读查询，方便运营和开发人员快速查找 IP 对应的归属地信息，或查看系统支持的国家/地区列表。

核心概念：系统管理 | 地区管理 | 页面功能说明 | 地区树形结构 | IP 归属地查询

2. 页面功能说明​

2.1 地区树形结构（旧版）​

下图展示了国内省市区的树形结构。请注意，这套数据主要用于旧版逻辑或简单的国内地址展示，不再用于核心的业务 IP 定位。

国内省市区树形结构

2.2 IP 归属地查询​

通过页面左上角的查询入口，可以输入 IP 地址，系统会基于 MaxMind 数据库 返回该 IP 对应的国家信息。这也是业务系统实际使用的定位逻辑。

点击左上角弹窗根据IP查国家

核心概念：系统管理 | 地区管理 | 业务开发集成 | Geoip2CountryIPUtils | Geoip2AreaUtils | 设备活跃统计 | APP 活跃上报

3. 业务开发集成​

在后端业务开发中，我们通过封装好的工具类来获取地区信息。

3.1 核心工具类​

  • Geoip2CountryIPUtils: 用于动态解析 IP 地址，获取对应的国家信息。这是业务中最常用的工具类。
  • Geoip2AreaUtils: 用于管理静态的地区列表数据（如加载 geoip2Area.csv），常用于前端“国家/地区”下拉框的数据源。

3.2 典型应用场景​

场景一：设备活跃统计​

在 设备管理模块 (yudao-module-device) 中，系统需要统计设备的活跃区域分布。

  • 代码位置: DeviceActivityDetailServiceImpl.java
  • 逻辑: 调用 Geoip2CountryIPUtils.getCountryArea(ip) 解析设备 IP，获取国家 ID 并存入数据库 (region_id)。

场景二：APP 活跃上报​

在 任务模块 (yudao-module-task) 中，处理机顶盒 APP 活跃日志时，需要记录用户所在国家。

  • 代码位置: ForeignThirdAppApiController.java
  • 逻辑: 使用 Geoip2CountryIPUtils.getCountryChineseName(ip) 获取国家中文名称，补充到上报数据中。

场景三：前端国家选择​

在 系统管理模块 (yudao-module-system) 的接口中，提供给前端使用的国家列表直接来源于 MaxMind 的数据映射。

  • 代码位置: AreaController.java
  • 逻辑: 接口 /system/area/country/list 调用 Geoip2AreaUtils.getAreaListByParentId(Area.ID_GLOBAL) 返回所有国家供前端下拉选择。
核心概念：系统管理 | 地区管理 | IP 数据库更新流程 | MaxMind 更新 | mmdb 文件替换 | sys_region 更新

4. IP 数据库更新流程​

由于 MaxMind 数据库会定期更新，为了保证定位的准确性，我们需要人工定期更新系统中的 .mmdb 文件。

4.1 流程概览​

Mermaid Diagram Code:

graph TD
    A["开始"] --> B["下载最新 mmdb 文件"]
    B --> C["替换项目资源文件 GeoLite2.mmdb"]
    C --> D["运行单元测试 testPrintAllCountriesFromDatabase"]
    D --> E{"是否有新增国家?"}
    E -- "是" --> F["控制台打印 SQL 和 CSV 数据"]
    F --> G["人工执行 SQL 更新数据库 sys_region"]
    G --> H["人工更新 geoip2Area.csv"]
    H --> I["结束"]
    E -- "否" --> I

4.2 详细操作步骤​

  1. 下载最新库: 人工访问MaxMind官网https://dev.maxmind.com 或相关渠道，下载最新的 GeoLite2-Country.mmdb 文件。

  2. 替换文件: 将下载的文件替换项目中的资源文件：

    • 路径: yudao-framework/yudao-spring-boot-starter-biz-ip/src/main/resources/GeoLite2.mmdb

  3. 验证变更:

    • 运行单元测试: cn.iocoder.yudao.framework.ip.geoip2.Geoip2IPUtilsTest.testPrintAllCountriesFromDatabase()
    • 该测试会调用 printAllCountriesFromDatabase 方法，遍历新数据库中的所有国家记录。

  4. 数据同步:

    • 无新增国家: 如果日志输出显示无新增国家，则无需操作。
    • 有新增国家: 如果发现新的国家或地区代码，测试代码会自动输出需要执行的 SQL 语句和CSV 数据行。请根据日志提示，分别手动更新数据库和项目中的 geoip2Area.csv 文件。

    有新增国家时的日志示例：

    需要人工更新csv和数据库中的国家数据结果示例截图

    日志说明与操作指南：

    如上图所示，当检测到新国家（例如 ID 为 249-252 的地区）时，控制台会输出两部分关键信息：

    1. 数据库更新语句 (INSERT INTO ...):

      INSERT INTO sys_region (`id`, `name`, `iso_name`, `short_name`) VALUES (249,'法属南部领地','French Southern Territories','TF');
      INSERT INTO sys_region (`id`, `name`, `iso_name`, `short_name`) VALUES (250,'布维岛','Bouvet Island','BV');
      ...

      操作: 请直接复制这些 SQL 语句，在生产环境和开发环境的数据库中执行，以确保 sys_region 表包含最新的国家数据。

    2. CSV 数据行 ("249","法属南部领地"...):

      "249","法属南部领地","1","0","French Southern Territories","TF"
      "250","布维岛","1","0","Bouvet Island","BV"
      ...

      操作: 请将这些行追加到项目文件 yudao-framework/yudao-spring-boot-starter-biz-ip/src/main/resources/geoip2Area.csv 的末尾。这确保了 Geoip2AreaUtils 工具类加载内存缓存时能包含这些新地区。

AI 问答