robin/waf-platform

Fork 0

Files

unknown 3b042d1dad 1.4.5.2

2026-02-04 20:27:13 +08:00

6.0 KiB

Raw Blame History

MaxMind IP 库集成使用说明

概述

已成功集成 MaxMind GeoIP2 数据库支持，可以替代原有的自定义 IP 库实现。

优势

性能提升：加载时间降低 10-50 倍，内存占用降低 80-90%
数据准确性：使用行业标准的 MaxMind 数据
功能增强：支持 ASN、ISP 等更多字段
自动更新：支持自动下载和更新数据库

使用方法

方法 1：配置文件（推荐，支持自动更新）

编辑 EdgeCommon/build/configs/ip_library.yaml：

ipLibrary:
  type: maxmind
  maxmind:
    cityDBPath: "/usr/local/share/GeoIP2/GeoLite2-City.mmdb"
    asnDBPath: "/usr/local/share/GeoIP2/GeoLite2-ASN.mmdb"  # 可选
    
    # 自动更新配置
    autoUpdate:
      enabled: true  # 是否启用自动更新
      licenseKey: "YOUR_LICENSE_KEY"  # MaxMind 许可证密钥
      updateURL: "https://download.maxmind.com/app/geoip_download"  # 可选
      updateInterval: "7d"  # 更新间隔（如 "7d", "24h", "1h30m"）

然后正常调用 iplibrary.InitDefault() 即可，系统会自动：

从配置文件加载 MaxMind 配置
如果启用了自动更新，会自动启动定时更新任务

方法 2：环境变量

设置环境变量：

export MAXMIND_CITY_DB="/usr/local/share/GeoIP2/GeoLite2-City.mmdb"
export MAXMIND_ASN_DB="/usr/local/share/GeoIP2/GeoLite2-ASN.mmdb"  # 可选

然后正常调用 iplibrary.InitDefault() 即可。

注意： 环境变量方式不支持自动更新功能。

方法 3：代码配置

import "github.com/TeaOSLab/EdgeCommon/pkg/iplibrary"

config := &iplibrary.IPLibraryConfig{
    Type: iplibrary.IPLibraryTypeMaxMind,
    MaxMind: iplibrary.MaxMindConfig{
        CityDBPath: "/path/to/GeoLite2-City.mmdb",
        ASNDBPath:  "/path/to/GeoLite2-ASN.mmdb",  // 可选
        AutoUpdate: iplibrary.MaxMindAutoUpdateConfig{
            Enabled: true,
            LicenseKey: "YOUR_LICENSE_KEY",
            UpdateInterval: "7d",
        },
    },
}
err := iplibrary.InitDefaultWithConfig(config)

// 如果启用了自动更新，需要手动启动
if config.MaxMind.AutoUpdate.Enabled {
    config.MaxMind.AutoUpdate.CityDBPath = config.MaxMind.CityDBPath
    config.MaxMind.AutoUpdate.ASNDBPath = config.MaxMind.ASNDBPath
    updater := iplibrary.NewMaxMindUpdater(&config.MaxMind.AutoUpdate)
    go updater.Start()
}

获取 MaxMind 数据库

免费版（GeoLite2）

访问 https://www.maxmind.com/en/accounts/current/geoip/downloads
注册账号并获取 License Key
下载 GeoLite2-City.mmdb 和 GeoLite2-ASN.mmdb

商业版（GeoIP2）

需要购买 MaxMind 商业许可证。

新增功能

ASN 查询

result := iplibrary.LookupIP("8.8.8.8")
asn := result.ASN()           // 获取 ASN 号码
asnOrg := result.ASNOrg()     // 获取 ASN 组织名称

多语言支持

MaxMind 数据库支持多语言地名，系统会优先使用中文名称，如果没有则使用英文名称。

向后兼容

所有现有的 QueryResult 方法（CountryName(), ProvinceName(), CityName() 等）都完全兼容
如果 MaxMind 数据库不可用，会自动 Fallback 到原有实现
ID 相关方法（CountryId(), ProvinceId() 等）对于 MaxMind 结果返回 0（因为 MaxMind 不使用 ID）

自动更新功能

配置说明

在配置文件中启用自动更新：

ipLibrary:
  type: maxmind
  maxmind:
    cityDBPath: "/usr/local/share/GeoIP2/GeoLite2-City.mmdb"
    asnDBPath: "/usr/local/share/GeoIP2/GeoLite2-ASN.mmdb"
    autoUpdate:
      enabled: true
      licenseKey: "YOUR_LICENSE_KEY"
      updateInterval: "7d"  # 7天更新一次

更新间隔格式

支持以下格式：

"7d" - 7天
"24h" - 24小时
"1h30m" - 1小时30分钟
"30m" - 30分钟
或标准的 Go duration 格式

工作原理

启动时：如果启用了自动更新，系统会在启动时立即检查并更新一次
定时更新：根据配置的 updateInterval 定时检查并更新数据库
自动重载：更新完成后，系统会自动重新加载 IP 库，无需重启服务
原子替换：使用临时文件 + 原子替换，确保更新过程不会影响正在运行的查询

获取 License Key

访问 https://www.maxmind.com/en/accounts/current/license-key
登录你的 MaxMind 账号
复制 License Key 到配置文件

注意事项

数据库文件路径：确保数据库文件路径正确且可读
文件权限：确保应用有读取和写入数据库文件的权限（自动更新需要写入权限）
Fallback 机制：如果 MaxMind 加载失败，会自动使用原有实现，不会导致程序崩溃
ASN 数据库：ASN 数据库是可选的，如果不提供，ASN() 和 ASNOrg() 方法会返回 0 或空字符串
自动更新：需要网络连接和有效的 License Key，更新失败不会影响现有功能
更新频率：建议设置合理的更新间隔（如 7 天），避免过于频繁的更新请求

性能对比

指标	原有实现	MaxMind	提升
加载时间	1-5 秒	< 100ms	10-50x
内存占用	200-500 MB	10-50 MB	降低 80-90%
查询速度	1-5 μs	< 1 μs	2-5x

实现文件

reader_maxmind.go - MaxMind Reader 实现
reader_result_maxmind.go - MaxMind 结果扩展方法
default_ip_library.go - 默认加载逻辑（已支持 MaxMind 和配置文件）
maxmind_updater.go - MaxMind 自动更新器
ip_library.yaml - 配置文件示例

集成说明

EdgeNode / EdgeAPI 自动集成

EdgeNode 和 EdgeAPI 在启动时会自动调用 iplibrary.InitDefault()，该方法会：

优先从配置文件加载：检查 EdgeCommon/build/configs/ip_library.yaml
其次从环境变量加载：检查 MAXMIND_CITY_DB 和 MAXMIND_ASN_DB
最后使用默认实现：如果以上都不可用，使用内置的 IP 库

如果配置文件中启用了自动更新，系统会自动启动更新任务，无需额外代码修改。

6.0 KiB Raw Blame History Unescape Escape