freegeoip

这是freegeoip软件的源代码镜像，包含Web服务器和Go编程语言包，使任何Web服务器都能通过简单清晰的API支持IP地理位置定位。有关地理位置定位的详细信息，请参见***。

核心功能和特性

• 提供JSON、XML、CSV多种格式的IP地理位置信息响应
• 支持JSONP回调参数
• 自动下载和更新IP数据库（默认使用MaxMind GeoLite2 City免费数据库）
• 可配置HTTPS（TLS），支持Let's Encrypt自动证书 provisioning
• 内置指标收集和性能分析功能（通过内部服务器）
• 支持反向代理环境下的X-Forwarded-For头解析
• 可配置CORS、HSTS、请求配额限制等生产级特性
• 数据库自动重载机制（文件更新或定期URL检查）

使用场景和适用范围

• 需要快速集成IP地理位置查询功能的Web应用
• 开发和测试环境中的IP定位功能验证
• 生产环境中需要高可用性和可配置性的IP地理信息服务
• 基于IP地理位置的访问控制、内容定制或统计分析

使用方法和配置说明

Docker部署

安装Docker

Docker为多种平台提供了安装指南，包括：

• Ubuntu
• CentOS
• Mac

在容器中运行API

bash
docker run --restart=always -p 8080:8080 -d cryptlex/freegeoip

测试

bash
curl localhost:8080/json/1.2.3.4
# => {"ip":"1.2.3.4","country_code":"US","country_name":"United States", # ...（省略部分响应内容）

生产环境配置

对于生产工作负载，您可能需要不同的配置，例如：

• 启用"内部服务器"以收集指标和按需分析/跟踪freegeoip Web服务器
• 使用Prometheus监控内部服务器，或将指标导出到New Relic
• 通过自有证书或LetsEncrypt.org自动配置的证书提供HTTPS（TLS）服务
• 配置HSTS以限制浏览器客户端始终使用HTTPS
• 配置读写超时以避免 stale 客户端消耗服务器资源
• 在反向代理后运行时，配置从X-Forwarded-For头读取客户端IP（用于日志等）
• 配置CORS以限制特定域访问API
• 配置默认"/"以外的端点路径前缀（如/json、/xml、/csv），以便在同一主机上与其他API共存
• 在操作系统和freegeoip Web服务器上启用TCP Fast Open优化往返时间
• 基于客户端IP设置请求配额限制（支持内存映射（单实例）、redis或memcache（分布式部署）等后端）
• 提供默认的GeoLite2 City免费数据库（后台自动下载和更新），或
• 提供MaxMind的商业GeoIP2 City数据库（本地文件定期更新或使用API密钥定期下载）

有关服务器配置的更多信息，请参见下面的服务器选项部分。

自动化部署可参考freegeoip chef cookbook或适用于Ubuntu 14.04 LTS的（旧版）Ansible Playbook。

服务器选项

要查看所有可用选项，请使用-help选项：

bash
docker run --rm -it cryptlex/freegeoip -help

如果使用LetsEncrypt.org provision TLS证书，必须在443端口监听HTTPS。以下示例展示服务器监听3个不同端口：指标+性能分析（8888）、HTTP（80）和HTTPS（443）：

bash
docker run -p 8888:8888 -p 80:8080 -p 443:8443 -d cryptlex/freegeoip \
	-internal-server=:8888 \
	-http=:8080 \
	-https=:8443 \
	-hsts=max-age=31536000 \
	-letsencrypt \
	-letsencrypt-hosts=myfancydomain.io

您可以通过命令行标志或环境变量配置freegeoip Web服务器。环境变量名称与命令行标志相同，但前缀为FREEGEOIP，全大写，用下划线分隔。例如，使用环境变量配置：

bash
$ cat prod.env
FREEGEOIP_INTERNAL_SERVER=:8888
FREEGEOIP_HTTP=:8080
FREEGEOIP_HTTPS=:8443
FREEGEOIP_HSTS=max-age=31536000
FREEGEOIP_LETSENCRYPT=true
FREEGEOIP_LETSENCRYPT_HOSTS=myfancydomain.io

$ docker run --env-file=prod.env -p 8888:8888 -p 80:8080 -p 443:8443 -d cryptlex/freegeoip

默认情况下，HTTPS上启用HTTP/2，可通过-http2=false标志禁用。

此外，freegeoip Docker镜像不提供freegeoip.net的网页，仅提供API。如需提供网页，可在命令行中传递-public=/var/www参数，并使用Docker的-v参数将该目录挂载为主机卷以提供自定义页面。

如果freegeoip Web服务器在反向代理或负载均衡器后运行，需传递-use-x-forwarded-for参数，并在所有请求中提供X-Forwarded-For HTTP头，以便服务器记录客户端IP并在未提供IP时（如/json/）执行地理位置查询。

数据库

当前实现使用MaxMind的免费GeoLite2 City数据库。

过去曾使用其他提供商的数据库，甚至自建数据库（整合不同来源数据），未来可能会变更。

如果已购买MaxMind商业数据库，可将freegeoip Web服务器（或Go API开发）指向数据库文件URL或本地文件，服务器将自动使用该数据库。

对于磁盘文件，替换为新版本后，freegeoip Web服务器将在后台自动重新加载。若使用URL（默认），服务器会在后台定期检查URL是否有新版本，如有则自动下载并重新加载。

freegeoip API的所有响应均在X-Database-Date HTTP头中包含数据库下载日期。

API

freegeoip API通过不同端点提供多种格式的响应。

示例：

bash
curl freegeoip.net/json/

返回您自己IP地址（连接的源IP地址）的地理位置信息。

可传递不同IP或主机名。例如，查询github.com的地理位置，服务器会先解析域名，然后使用第一个可用IP地址（可能是IPv4或IPv6）：

bash
curl freegeoip.net/json/github.com

/xml/{ip}和/csv/{ip}端点具有相同语义。

JSON响应可通过添加callback参数编码为JSONP：

bash
curl freegeoip.net/json/?callback=foobar

其他端点忽略callback参数。

指标和性能分析

freegeoip Web服务器可提供使用指标，并支持运行时性能分析和跟踪。

默认情况下两者均禁用，可通过命令行传递-internal-server参数启用。指标为Prometheus生成，可通过/metrics端点查询（即使使用curl）。

HTTP pprof可在/debug/pprof访问，pprof包文档中的示例适用于freegeoip Web服务器。

Go语言包

Go编程语言的freegeoip包提供两个API：

• 数据库API：无需维护IP数据库
• 地理位置http.Handler：可用于任何http服务器

如需快速查看代码，请参见example_test.go文件。否则，请查看godoc参考。

![GoDoc]([] ![Build Status]([] ![GoReportCard]([***]

特性

• 零维护：DB对象可从互联网下载IP数据库文件并立即提供查询服务，后台自动更新，无需人工干预。
• 运维友好：如关注数据库，可定期更新数据库文件（程序运行中），DB对象将在后台自动加载。
• 可扩展：除数据库部分外，包提供http.Handler对象，可添加到任何HTTP服务器以提供与freegeoip.net相同的简化API，还支持自定义HTTP响应格式的接口。

安装

下载包：

bash
go get -d github.com/cryptlex/freegeoip/...

安装Web服务器：

bash
go install github.com/cryptlex/freegeoip/cmd/freegeoip

测试覆盖率良好，测试代码可能有助于找到所需功能。