maxmind-geoip Docker镜像文档

镜像概述

maxmind-geoip是一个用于自动获取、更新和提供MaxMind GeoIP2/GeoLite2数据库的Docker化服务。该镜像解决了应用在依赖IP地理位置信息时的数据库管理难题，通过自动化流程处理数据库的下载、更新和访问，降低应用集成IP地理定位功能的复杂度。

核心功能与特性

1. 自动下载与更新

• 支持定期从MaxMind官方服务器同步最新数据库，更新频率可配置（默认24小时）
• 支持增量更新，仅下载变更部分，减少带宽消耗
• 启动时自动执行首次下载，确保服务启动即有可用数据库

2. 多数据库类型支持

• 兼容GeoIP2（商业版）和GeoLite2（免费版）系列数据库
• 支持数据库类型：City（城市级定位）、Country（国家/地区级定位）、ASN（自治系统编号）

3. 多访问方式

• HTTP服务：通过HTTP API提供数据库文件下载（默认端口8080）
• DNS服务：支持通过DNS查询直接返回IP对应的地理位置信息（需手动启用）
• 文件访问：数据库文件存储于容器内固定路径，支持通过卷挂载直接供其他容器/应用读取

4. 配置灵活性

• 全环境变量驱动配置，无需编写复杂配置文件
• 支持自定义数据库存储路径、日志级别及HTTP服务根目录
• 可配置代理服务器，适配受限网络环境

5. 轻量级设计

• 基于Alpine Linux构建，镜像体积小（约50MB）
• 低资源占用，适合边缘设备及轻量级部署场景

使用场景

适用场景

• 需IP地理位置解析的Web应用（如访问日志分析、基于地区的内容分发）
• 网络监控工具（识别异常IP来源地、流量地域分布统计）
• 安全审计系统（基于IP地理位置的访问控制、异常登录检测）
• 无法直接访问MaxMind API的离线环境（如内网应用）

不适用场景

• 需要实时地理位置查询API的场景（需搭配应用层解析逻辑）
• 对数据库更新延迟敏感的业务（建议结合应用层缓存机制）

使用方法

前提条件

• 需获取MaxMind账户及许可证密钥（注册地址）
• Docker Engine 19.03+或Docker Compose 2.0+环境

基本部署（docker run）

docker run -d \
  --name maxmind-geoip \
  -e MAXMIND_LICENSE_KEY="your_maxmind_license_key" \  # 从MaxMind账户获取
  -e DATABASE_EDITIONS="GeoLite2-City GeoLite2-Country" \  # 指定需下载的数据库类型
  -e UPDATE_INTERVAL="12h" \  # 设置更新间隔（12小时）
  -p 8080:8080 \  # 映射HTTP服务端口
  -v /host/path/to/db:/app/db \  # 可选：挂载数据库目录到宿主机持久化存储
  rpardini/maxmind-geoip

Docker Compose配置

version: "3.8"
services:
  maxmind-geoip:
    image: rpardini/maxmind-geoip
    container_name: maxmind-geoip
    restart: unless-stopped
    environment:
      - MAXMIND_LICENSE_KEY=your_maxmind_license_key
      - DATABASE_EDITIONS=GeoLite2-City GeoLite2-Country GeoLite2-ASN
      - UPDATE_INTERVAL=24h
      - HTTP_SERVER_ENABLED=true
      - LOG_LEVEL=info
    ports:
      - "8080:8080"
    volumes:
      - geoip_data:/app/db  # 持久化数据库文件

volumes:
  geoip_data:  # 命名卷用于数据持久化

核心环境变量配置

数据库访问方式

1. HTTP访问

通过HTTP请求直接下载数据库文件，URL格式：
http://<容器IP或域名>:<HTTP_SERVER_PORT>/<数据库文件名>.mmdb
示例：
curl http://localhost:8080/GeoLite2-City.mmdb -o GeoLite2-City.mmdb

2. 文件挂载访问

将容器内/app/db目录挂载到其他应用容器，直接读取MMDB文件：

# 示例：将数据库挂载到Nginx容器供ngx_http_geoip2_module使用
docker run -d \
  --name nginx-with-geoip \
  -v geoip_data:/etc/geoip:ro \  # 只读挂载geoip数据库卷
  nginx:alpine

3. DNS访问（需启用）

启用DNS服务后，可通过DNS查询获取IP地理位置信息，查询格式：
<IP反序>.geo.<域名>
示例（假设DNS服务运行在10.0.0.100）：
dig +short 1.1.1.1.geo.10.0.0.100
返回格式：Country:US,City:Mountain View

注意事项

1. 许可证密钥安全：MAXMIND_LICENSE_KEY包含账户权限，避免明文暴露，建议通过Docker Secrets或环境变量文件注入
2. 更新频率限制：MaxMind对免费版数据库有更新频率限制（建议不低于6小时），过度频繁更新可能导致API访问受限
3. 数据有效期：GeoLite2免费数据库有效期为30天，需确保更新机制正常运行
4. 商业授权：使用GeoIP2商业版数据库需确保已获取MaxMind商业授权

参考链接

• MaxMind账户注册
• MaxMind数据库类型说明
• GitHub项目主页