离线 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/	本地虚拟环境（可选，见下文创建方式）

将现有库从 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 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）

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。

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

离线 IP 数据库文件需遵守各数据源（IP2Location LITE、纯真 CZ88、ip2region 等）的许可与使用条款；本仓库通常不包含大型 .BIN / .czdb / .xdb / .dat 二进制文件。