IP查询系统 API 搭建与使用指南

一、Docker 快速部署
1. 拉取并运行容器
更多参照：http://blog.hx99.net/Tech/2702.html
docker run -d --name go-geoip \
  -p 7099:7099 \
  -v /data/go-geoip:/app/go-geoip/data \
  -e API_SECRET="123456" \   #[可选，建议删除本行]api调用时，请求头校验的秘钥（如使用，要保证前后端统一）
  -e TZ=Asia/Shanghai \
  ad80a1/go-geoip
2. 环境变量说明（可选）
  • PORT：服务端口，默认 7099
  • API_SECRET：API密钥（如不使用可省略）
  • CITY_DB_REMOTE_URL：自定义 GeoIP2-City.mmdb 地址
3. 验证服务
# 测试服务是否正常
curl http://localhost:7099/ip
二、API 接口详解
基础信息
  • 生产环境：https://ipapi.hx99.net/ip
  • 本地测试：http://localhost:7099/ip
  • 请求方式：GET
  • IP查询网站：http://www.xxx.cn
1. 查询本机 IP 信息
# 基础查询
curl https://ipapi.hx99.net/ip  //已反代，双栈IP解析，优先显示IPv6信息

# 简洁格式（直接访问网站）
curl hxsec.cn
# 输出示例：101.35.**.** 上海市上海市 腾讯云 (数据中心)

# 带密钥查询
curl -H "Authorization: Bearer 123456" "https://ipapi.hx99.net/ip"

2. 查询指定 IP 信息
# 查询 IPv4
curl "https://ipapi.hx99.net/ip/8.8.8.8"

# 查询 IPv6  
curl "https://ipapi.hx99.net/ip/2409:8a20:2000:578::1"

# 带密钥查询
curl -H "Authorization: Bearer 123456" "https://ipapi.hx99.net/ip/1.1.1.1"
三、系统功能特性
1. 查询类型支持
  • ✅ 本机 IPv4：自动识别客户端 IPv4 地址
  • ✅ 本机 IPv6：前端直连 API 获取，无 IPv6 时自动回退
  • ✅ 指定 IP：支持 IPv4/IPv6 地址查询
  • ✅ 域名解析：前端使用阿里 DNS 公共 API 解析
  • ✅ 代理检测：检测 IP 地理位置及访问权限
2. 输出格式
  • JSON 格式：完整的 IP 地理位置信息
  • 简洁文本：CLI 模式下的精简输出
  • 网页展示：响应式界面，支持 PC 和移动端
四、API 响应格式
成功响应示例：
{
  "code": 0,
  "data": {
    "ip": "115.2.xx.xx",
    "country": "中国",
    "province": "浙江省", 
    "city": "杭州市",
    "district": "",
    "isp": "中国电信",
    "as": "中国电信",
    "addr": "115.2.xx.0/24",
    "latitude": "3x.xx32",
    "longitude": "1xx.722"
  }
}
特殊响应代码：
代码 说明 前端处理
0 查询成功 直接显示结果
1 查询失败 显示错误信息
2 需要前端处理 IPv6 前端调用 IPv6 专用接口
3 需要前端 DNS 解析 前端使用公共 DNS 解析域名
五、前端功能说明
1. 域名解析流程
// 使用阿里 DNS 公共 API 解析
const url = `https://dns.alidns.com/resolve?name=${domain}&type=A&format=json`;
// 解析成功后查询 IP 地理位置信息
2. IPv6 处理逻辑
  • 本机 IPv6 查询通过前端直连 API
  • 无 IPv6 时自动返回 IPv4 并显示提示信息
  • 支持指定 IPv6 地址查询
3. 代理检测功能
  • 检测当前 IP 的地理位置
  • 判断是否为大陆 IP 及访问权限
  • 独立结果显示，不影响 IP 查询
六、错误代码说明
代码 说明 处理建议
0 查询成功 –
1 查询失败 检查 IP 格式或网络连接
2 需要前端处理 IPv6 前端调用 IPv6 专用接口
3 需要前端 DNS 解析 前端使用公共 DNS 解析域名
七、使用建议
  • ✅ 免费使用：无调用次数限制
  • ✅ 自动更新：GeoIP 数据库每周自动更新
  • ✅ 多格式输出：支持 JSON、简洁文本、网页展示
  • ⚠️ 响应时间：建议设置 5 秒超时
  • ⚠️ 频率限制：避免高频请求（> 10次/秒）
八、验证部署成功
# 1. 检查容器状态
docker ps | grep go-geoip

# 2. 测试 API 接口
curl "http://localhost:7099/ip/8.8.8.8"

# 3. 测试网页功能
curl -s xxx.cn

# 4. 测试域名解析（通过网页界面）
# 访问 http://www.xxx.cn 输入 baidu.com 测试
九、系统架构特点
  1. 前后端分离：前端处理 DNS 解析和 IPv6 查询
  2. 多模式支持：Web、CLI、API 三种使用方式
  3. 智能识别：自动识别 curl/CLI 访问模式
  4. 错误处理：完善的错误代码和用户提示
  5. 响应式设计：适配 PC 和移动设备
标签