# ip2region4python

**Repository Path**: xyxu421/ip2region4python

## Basic Information

- **Project Name**: ip2region4python
- **Description**: 基于ip2region的离线 IP 归属地 HTTP 查询服务。把 IP 库放在自己服务器上，毫秒级响应、无限流、不依赖任何在线第三方接口。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-02
- **Last Updated**: 2026-08-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ip2region-api

基于 [ip2region](https://github.com/lionsoul2014/ip2region) 的**离线 IP 归属地 HTTP 查询服务**。把 IP 库放在自己服务器上，毫秒级响应、无限流、不依赖任何在线第三方接口。

![Python](https://img.shields.io/badge/Python-3.11-blue) ![FastAPI](https://img.shields.io/badge/FastAPI-0.141-009688) ![Docker](https://img.shields.io/badge/Docker-Compose-2496ED)

## 特性

- 🚀 **完全离线**：IP 数据（`xdb` 文件）打包进镜像，本地查询，不出网、不依赖第三方 API
- ⚡ **微秒级查询**：启动时把整个 xdb 载入内存，查询无磁盘 IO，可安全并发
- 🌏 **IPv4 / IPv6 自动判别**：同一接口查询两种地址
- 🎯 **精度高**：国内精确到区县/运营商（中文），国外到国家+州（英文）
- 🐳 **Docker Compose 一键部署**：含健康检查、非 root 运行
- 🔒 **CORS 白名单**：只放行你指定的站点，防止被任意站点跨域调用
- 📄 **自带可视化查询页**：浏览器打开根路径即可使用

## 快速开始

### Docker Compose（推荐）

```bash
git clone <你的仓库地址>
cd ip2region-api

# 构建并启动（-d 后台运行）
docker compose up -d --build

# 查看状态
docker compose ps          # 应显示 healthy

# 测试
curl http://127.0.0.1:8764/healthz
```

### 本地开发（不使用 Docker）

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python3 -m uvicorn app:app --host 0.0.0.0 --port 8080
```

## API 文档

### 查询指定 IP

```
GET /api/search?ip={ip}
```

```bash
curl "http://127.0.0.1:8764/api/search?ip=110.110.110.110"
```

```json
{
  "ip": "110.110.110.110",
  "region": "中国|黑龙江省|哈尔滨市|铁通|CN",
  "country": "中国",
  "province": "黑龙江省",
  "city": "哈尔滨市",
  "isp": "铁通",
  "iso_code": "CN"
}
```

### 查询访问者 IP（不带参数）

自动优先读取反代头 `X-Forwarded-For` / `X-Real-IP`，否则取连接来源：

```
GET /api/search
```

```bash
curl "http://127.0.0.1:8764/api/search"
```

### 健康检查

```
GET /healthz
```

```bash
curl "http://127.0.0.1:8764/healthz"    # 返回 ok
```

### 版本信息

```
GET /api/version
```

### 可视化查询页

浏览器打开根路径 `/`，有简易查询页面（纯内联样式，无外部资源，可安全反代到任意子路径）。

### 响应字段说明

| 字段 | 说明 |
|------|------|
| `ip` | 查询的 IP |
| `region` | 原始归属地串，格式 `国家\|省份\|城市\|运营商\|ISO码` |
| `country` / `province` / `city` / `isp` / `iso_code` | 拆分后的各字段 |

## 配置

| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `PORT` | `8080` | 服务监听端口 |
| `IP2REGION_DATA_DIR` | `.` | xdb 文件所在目录 |
| `IP2REGION_V4_XDB` | `ip2region_v4.xdb` | IPv4 数据文件名 |
| `IP2REGION_V6_XDB` | `ip2region_v6.xdb` | IPv6 数据文件名（可选） |
| `IP2REGION_ALLOW_ORIGINS` | `https://blog.luxas.top,...` | CORS 白名单，逗号分隔 |

> CORS 示例：`IP2REGION_ALLOW_ORIGINS=https://your.site,https://www.your.site`
> 若需要放行所有来源（不推荐），设为 `*`。

## 数据文件

- **IPv4 数据** `ip2region_v4.xdb`（约 11MB）：默认已包含在仓库中
- **IPv6 数据** `ip2region_v6.xdb`（约 37MB）：可选，按需下载后放入项目根目录并设置 `IP2REGION_V6_XDB`

数据源：<https://github.com/lionsoul2014/ip2region> 官方 `data/` 目录（不定期更新）。若需更高更新频率，可关注 [ip2region 官方社区](https://ip2region.net) 的商业数据。

## 目录结构

```
ip2region-api/
├── app.py               # FastAPI 服务主程序
├── Dockerfile           # 镜像构建
├── docker-compose.yml   # Compose 编排（含健康检查）
├── requirements.txt     # Python 依赖
├── ip2region_v4.xdb     # IPv4 IP 数据
└── .dockerignore        # 构建排除项
```

## 反代到子路径

服务页面与接口均使用相对路径设计，可安全反代到任意子路径（如 `https://your.domain/ip2region/`）。Nginx 示例：

```nginx
location ^~ /ip2region/ {
    proxy_pass http://127.0.0.1:8764/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
```

## 常见问题

**Q: 浏览器从我的博客跨域请求接口被拦截？**
A: 检查 CORS 配置。需要把博客域名加入 `IP2REGION_ALLOW_ORIGINS` 并重建容器。

**Q: 部署后查询 IP 不准确？**
A: 确认反代是否正确传递了 `X-Forwarded-For` / `X-Real-IP` 头（见上方 Nginx 示例），否则服务只能看到反代/网关的 IP。

**Q: 如何更新 IP 数据？**
A: 从 ip2region 官方仓库下载最新的 `ip2region_v4.xdb` 替换本地文件，重新 `docker compose up -d --build`。

## License

本项目基于 [ip2region](https://github.com/lionsoul2014/ip2region) 构建，遵循其开源许可（Apache-2.0 / MIT）。