Skip to content

About

ip2region docker 部署

Topics

dockerdocker-composeip2region

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository
BranchesTags

Repository files navigation

ip2region Docker

基于 ip2region 的 Docker 化部署，提供高性能 IP 地址定位 HTTP API 服务，支持 IPv4 + IPv6 双栈查询。

特性

  • Go 实现 — 编译为单一二进制，镜像体积仅 ~15MB，毫秒级启动
  • 双栈支持 — 自动识别 IPv4/IPv6，使用对应 xdb 数据文件查询
  • 内存加载 — xdb 文件全量加载到内存，查询零 IO 开销
  • RESTful API — 单 IP 查询、批量查询、健康检查
  • 生产就绪 — 多阶段构建、非 root 运行、健康检查、资源限制

快速开始

方式一：拉取预构建镜像（推荐）

镜像已内置 xdb 数据文件，开箱即用：

# 从 GHCR 拉取
docker pull ghcr.io/<your-username>/ip2region:latest

# 从 Docker Hub 拉取
docker pull <your-username>/ip2region:latest

# 运行
docker run -d -p 8888:8888 ghcr.io/<your-username>/ip2region:latest

方式二：本地构建

1. 下载数据文件

# Linux / macOS
bash download_xdb.sh

# Windows (PowerShell)
mkdir -p data
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/lionsoul2014/ip2region/master/data/ip2region_v4.xdb" -OutFile "data/ip2region_v4.xdb"
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/lionsoul2014/ip2region/master/data/ip2region_v6.xdb" -OutFile "data/ip2region_v6.xdb"

至少需要一个数据文件。IPv6 文件缺失不影响 IPv4 查询，反之亦然。

2. 构建并启动

docker-compose up -d --build

实际部署

使用 Docker Compose 拉取 GHCR / Docker Hub 预构建镜像部署，无需本地构建。

# GHCR 部署（替换 <your-username>/<your-repo>）
IMAGE=ghcr.io/<your-username>/<your-repo>:latest \
  docker-compose -f docker-compose.prod.yml up -d

# Docker Hub 部署（替换 <your-username>）
IMAGE=<your-username>/ip2region:latest \
  docker-compose -f docker-compose.prod.yml up -d

也可直接修改 docker-compose.prod.yml 中 image: 的默认值（默认 GHCR 镜像）。

预构建镜像已内置 xdb 数据文件，开箱即用。如需覆盖为最新数据，可将 xdb 文件放到 ./data/ 并取消 docker-compose.prod.yml 中 volumes 的注释。

查看状态与日志

docker-compose -f docker-compose.prod.yml ps      # 查看运行状态
docker-compose -f docker-compose.prod.yml logs -f # 查看日志
docker-compose -f docker-compose.prod.yml down    # 停止并移除

验证

# 健康检查
curl http://localhost:8888/health

# 查询 IPv4
curl "http://localhost:8888/search?ip=8.8.8.8"

# 查询 IPv6
curl "http://localhost:8888/search?ip=2001:4860:4860::8888"

# 查询并返回拆解字段
curl "http://localhost:8888/query?ip=114.114.114.114"

# 批量查询
curl -X POST http://localhost:8888/search \
  -H "Content-Type: application/json" \
  -d '{"ips":["8.8.8.8", "2001:db8::1", "114.114.114.114"]}'

API 文档

GET / — 服务信息

返回服务版本和可用接口列表。

{
  "service": "ip2region HTTP API (Go)",
  "version": "2.0.0",
  "stack": { "ipv4": true, "ipv6": true },
  "endpoints": { ... }
}

GET /health — 健康检查

返回各数据文件的加载状态。

{
  "status": "ok",
  "service": "ip2region",
  "searchers": {
    "ipv4": { "loaded": true, "file": "ip2region_v4.xdb", "path": "/data/ip2region_v4.xdb" },
    "ipv6": { "loaded": true, "file": "ip2region_v6.xdb", "path": "/data/ip2region_v6.xdb" }
  }
}

GET /search?ip=<ip> — 单 IP 查询

自动识别 IPv4/IPv6，使用对应数据文件查询。未提供 ip 参数时，自动使用当前请求的客户端 IP。

请求：

GET /search?ip=8.8.8.8

响应：

{
  "ip": "8.8.8.8",
  "region": "美国|0|0|0|Level3",
  "type": "ipv4"
}

不传 ip 参数（查询客户端自身 IP）：

GET /search

{
  "ip": "1.2.3.4",
  "region": "中国|0|广东省|深圳市|电信",
  "type": "ipv4"
}

客户端 IP 的获取顺序：X-Forwarded-For（取第一个）→ X-Real-IP → TCP 直连地址（RemoteAddr）。若部署在反向代理之后，请确保上游代理正确覆盖这些头；如不希望信任代理头，可设置 TRUST_PROXY=false。

GET /query?ip=<ip> — 单 IP 查询（返回拆解字段）

与 /search 相同，但额外返回拆解后的 region 各字段。未提供 ip 参数时，自动使用当前请求的客户端 IP。

请求：

GET /query?ip=114.114.114.114

响应（中国地区，中文）：

{
  "ip": "114.114.114.114",
  "region": "中国|江苏省|南京市|电信|CN",
  "country": "中国",
  "province": "江苏省",
  "city": "南京市",
  "isp": "电信",
  "iso_code": "CN",
  "type": "ipv4"
}

响应（非中国地区，英文）：

{
  "ip": "8.8.8.8",
  "region": "United States|California|Los Angeles|Comcast|US",
  "country": "United States",
  "province": "California",
  "city": "Los Angeles",
  "isp": "Comcast",
  "iso_code": "US",
  "type": "ipv4"
}

region 字段格式（官方定义）：国家|省份|城市|ISP|iso-alpha2-code。中国的定位信息全部为中文，非中国地区的地域信息全部为英文。字段缺失或为 0 占位时，对应拆解字段省略不返回。

POST /search — 批量查询

单次最多 100 个 IP，支持 IPv4/IPv6 混合。

请求：

{
  "ips": ["8.8.8.8", "2001:4860:4860::8888", "114.114.114.114"]
}

响应：

{
  "results": [
    { "ip": "8.8.8.8", "region": "美国|0|0|0|Level3", "type": "ipv4" },
    { "ip": "2001:4860:4860::8888", "region": "美国|0|0|0|Google", "type": "ipv6" },
    { "ip": "114.114.114.114", "region": "中国|0|江苏省|南京市|0", "type": "ipv4" }
  ],
  "total": 3
}

配置

通过环境变量配置：

变量 默认值 说明
PORT 8888 服务端口
XDB_IPV4_PATH /data/ip2region_v4.xdb IPv4 数据文件（容器内路径）
XDB_IPV6_PATH /data/ip2region_v6.xdb IPv6 数据文件（容器内路径）
TRUST_PROXY true 是否信任反向代理头（X-Forwarded-For / X-Real-IP）获取客户端 IP

项目结构

ip2region-docker/
├── .github/workflows/
│   └── build.yml            # GitHub Actions 自动构建
├── main.go                  # Go HTTP 服务（标准库 net/http）
├── go.mod                   # Go 模块依赖
├── Dockerfile               # 多阶段构建
├── docker-compose.yml       # 本地构建编排配置
├── docker-compose.prod.yml  # 实际部署编排配置（GHCR / Docker Hub 镜像）
├── download_xdb.sh          # 数据文件下载脚本
├── .env.example             # 环境变量模板
└── data/                    # xdb 数据文件目录（挂载到容器）
    ├── ip2region_v4.xdb     # IPv4 数据
    └── ip2region_v6.xdb     # IPv6 数据

CI/CD

GitHub Actions 在 Push 到 main/master 分支或推送 v* 标签时自动：

  1. 下载最新的 IPv4 + IPv6 xdb 数据文件
  2. 构建 linux/amd64 + linux/arm64 多架构镜像
  3. 推送到 GHCR 和 Docker Hub

配置 Secrets

在仓库 Settings → Secrets and variables → Actions 中添加：

Secret 说明
DOCKERHUB_USERNAME Docker Hub 用户名
DOCKERHUB_TOKEN Docker Hub Access Token

GHCR 使用内置 GITHUB_TOKEN，无需额外配置。如果不需要 Docker Hub，不设置对应 Secret 即可自动跳过。

标签策略

事件 标签示例
Push to main latest
Tag v1.2.3 1.2.3, 1.2, 1
Commit abc1234 (short SHA)

资源消耗

项目 数值
镜像大小 ~15MB
内存占用 ~30MB（双 xdb 全量加载）
CPU 极低（纯内存查询）

依赖

  • ip2region — Go binding xdb searcher
  • Go 1.23+（仅构建阶段，运行镜像基于 Alpine）

About

ip2region docker 部署

Topics

dockerdocker-composeip2region

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages