techblog/freegeoip

freegeoip Docker镜像文档

镜像概述

freegeoip是一个轻量级Docker镜像，提供公共HTTP API服务，用于查询IP地址的地理位置信息。该镜像基于freegeoip项目构建，能够快速返回IP对应的国家、地区、城市、经纬度等地理数据，适用于需要IP地理定位功能的各类应用场景。

核心功能和特性

• HTTP API支持：提供简单易用的RESTful API接口，支持IP地址地理信息查询
• 丰富的地理数据：返回IP对应的国家名称、地区代码、城市名称、邮政编码、经纬度等详细信息
• 轻量级部署：镜像体积小，资源占用低，可快速启动和部署
• 无需额外配置：默认配置即可运行，支持通过环境变量自定义服务参数
• 支持IPv4和IPv6：兼容主流IP协议版本的地理信息查询

使用场景和适用范围

• 应用日志分析：结合日志中的IP地址分析用户分布区域
• 用户定位服务：为Web应用提供用户地理位置信息，优化内容展示
• 安全审计：监控异常IP访问，分析潜在安全威胁来源
• 网络流量分析：统计不同地区的访问流量，优化服务器部署
• 移动应用开发：为移动应用提供IP定位功能，实现基于位置的服务

使用方法和配置说明

基本部署（docker run）

使用以下命令快速启动freegeoip服务：

bash
docker run -d -p 8080:8080 --name freegeoip fgrehm/freegeoip

参数说明：

• -d：后台运行容器
• -p 8080:8080：将容器内8080端口映射到主机8080端口
• --name freegeoip：指定容器名称为freegeoip
• fgrehm/freegeoip：freegeoip官方Docker镜像（注：实际镜像名称可能因版本而异，此处为常见示例）

自定义配置（环境变量）

可通过环境变量自定义服务配置，常用环境变量如下：

示例：指定服务端口为80，日志级别为debug

bash
docker run -d -p 80:80 --name freegeoip -e PORT=80 -e LOG_LEVEL=debug fgrehm/freegeoip

API使用示例

服务启动后，可通过HTTP请求查询IP地理信息：

查询指定IP

bash
curl http://localhost:8080/json/8.8.8.8

返回示例：

json
{
  "ip": "8.8.8.8",
  "country_code": "US",
  "country_name": "United States",
  "region_code": "CA",
  "region_name": "California",
  "city": "Mountain View",
  "zip_code": "94043",
  "time_zone": "America/Los_Angeles",
  "latitude": 37.386,
  "longitude": -122.084,
  "metro_code": 807
}

查询当前请求IP

bash
curl http://localhost:8080/json/

docker-compose配置示例

创建docker-compose.yml文件：

yaml
version: '3'
services:
  freegeoip:
    image: fgrehm/freegeoip
    ports:
      - "8080:8080"
    environment:
      - PORT=8080
      - LOG_LEVEL=info
    restart: always

启动服务：

bash
docker-compose up -d

注意事项

• 地理数据库可能需要定期更新以保证数据准确性，可通过挂载外部数据库文件或定时重启容器更新
• 高并发场景下建议适当调整容器资源限制（如--memory、--cpus参数）
• 生产环境中建议配合反向代理（如Nginx）使用，增加安全性和性能