baby-ip-loacation

离线 IP 归属地相关资源与查询服务：包含 WordPress 插件侧 PHP 逻辑（show-useragent），以及独立的 Python HTTP 查询服务（ip_lookup_service），数据源与 ip2c-text.php 中的配置一致。

目录说明

路径	说明
`show-useragent/`	PHP / Composer 依赖与 IP 查询插件代码（含 `ip2c-text.php`）
`ip_db/`	Python 服务使用的离线库目录（需自行放入数据文件，见下表）
`ip_lookup_service/`	FastAPI 查询服务与 `ip_lookup` 包
`ip_lookup_service/static/flags_svg/`	国旗 SVG 资源（已从 PHP 插件目录迁移）
`venv/`	本地虚拟环境（可选，见下文创建方式）

`ip_db` 中应放置的文件

将现有库从 show-useragent 下复制或软链接到下列路径（文件名需一致）：

子目录	文件
`ip_db/ip2location/`	`IP2LOCATION-LITE-DB11.BIN`、`IP2LOCATION-LITE-DB11.IPV6.BIN`
`ip_db/czdb/`	`cz88_public_v4.czdb`、`cz88_public_v6.czdb`
`ip_db/ip2region/`	`ip2region_v4.xdb`、`ip2region_v6.xdb`
`ip_db/qqwry/`	`qqwry.dat`、`ipv6wry.db`

Python 环境

在项目根目录创建虚拟环境（示例使用本机 Python 3.11）：


G:\python311\python.exe -m venv venv
.\venv\Scripts\Activate.ps1

使用清华大学 PyPI 镜像安装依赖：


.\venv\Scripts\pip.exe install -i https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn -r ip_lookup_service\requirements.txt

也可直接运行脚本（同样使用清华源）：

ip_lookup_service\install_deps.ps1
ip_lookup_service\install_deps.bat

配置（可选）

通过环境变量覆盖默认路径与 CZDB 密钥（前缀 IP_LOOKUP_）：

变量	含义	默认
`IP_LOOKUP_DB_ROOT`	数据库根目录	项目根目录下的 `ip_db`
`IP_LOOKUP_CZDB_KEY`	纯真 CZDB 解密密钥	与 PHP 示例一致
`IP_LOOKUP_DEFAULT_METHOD`	默认查询方式	`ip2location`

查询方式取值：ip2location、czdb、ip2region、qqwry。其中 ip2location 在库缺失或查询失败时会尝试回退到 CZDB（与 PHP 侧行为一致）。

启动服务

在 ip_lookup_service 目录下执行：


cd ip_lookup_service
..\venv\Scripts\python.exe -m uvicorn app:app --host 0.0.0.0 --port 8765

根路径：http://127.0.0.1:8765/（返回文档入口）
交互式文档：http://127.0.0.1:8765/docs
介绍页面：http://127.0.0.1:8765/
测试页面：http://127.0.0.1:8765/test/ip（或 http://127.0.0.1:8765/static/ip_test.html）

API 说明

健康检查

GET /health：返回 status，以及 backends：

字段	含义
`database_files`	各数据文件路径是否存在（不加载第三方库，仅 `Path.is_file()`）
`libraries_loaded`	是否已在某次查询中成功初始化对应 SDK（按需加载；未用过的库为 `false`）

进程启动时不会一次性打开所有数据库；只有实际请求用到某种 method 时，才会 import 该方式对应的 Python 库并打开相应文件（与「按查询方式选用不同查询库」一致）。

国家码提取兼容中英文：Python 服务内置了从 PHP getCountryCode()（countryMap + englishCountryMap）导出的映射文件 ip_lookup_service/ip_lookup/data/country_code_map.json，并保留 removeWhitespace 风格的空白规整。

查询接口

GET /api/lookup

查询参数	必填	说明
`ip`	是	IPv4 或 IPv6 地址
`method`	否	指定使用哪套数据库；默认 `ip2location`（也可用环境变量 `IP_LOOKUP_DEFAULT_METHOD` 改默认值）

返回字段（新增国旗信息）：

字段	说明
`ip`	查询 IP
`method`	查询方式
`location`	归属地文本
`country_code`	国家代码（小写，例 `cn` / `us`）
`flag_emoji`	国旗 emoji（例 `🇨🇳`）
`flag_icon`	国旗 SVG 路径（例 `/static/flags_svg/cn.svg`）

method 取值与离线库对应关系（与 ip2c-text.php 中查询方式一致）：

`method`	使用的数据
`ip2location`	IP2Location BIN（IPv4 / IPv6 各用对应文件）；查询失败或未加载时会回退 CZDB
`czdb`	纯真 CZDB（`cz88_public_v4.czdb` / `cz88_public_v6.czdb`）
`ip2region`	ip2region xdb（`ip2region_v4.xdb` / `ip2region_v6.xdb`）
`qqwry`	纯真 QQ 格式（IPv4 用 `qqwry.dat`，IPv6 用 `ipv6wry.db`）

示例：


GET /api/lookup?ip=114.114.114.114&method=czdb
GET /api/lookup?ip=240e::1&method=ip2region
GET /api/lookup?ip=8.8.8.8&method=qqwry
GET /api/lookup?ip=8.8.8.8

最后一行省略 method 时等价于 method=ip2location。

排查：`location` 为 `Unknown` 或空

先看 GET /health 里 database_files.czdb_v4（或对应项）是否为 true（文件已就位）。
再发一次 method=czdb 的查询后，看 libraries_loaded.czdb_v4 是否变为 true（表示 czdb-searcher 已成功初始化）；若文件为 true 而加载始终为 false，多为 IP_LOOKUP_CZDB_KEY 与库不匹配或文件损坏。
若曾经初始化失败，对应后端会记录为失败状态；新放入数据文件后建议重启进程，或在此之前保证首次打开即成功。