离线 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 插件目录迁移） |
ip_lookup_service/static/ua_icons/24/net、.../os | 浏览器 /操作系统图标（24px PNG，命名与 wp-useragent 的 code 一致） |
ip_lookup_service/static/index.html 等 | 介绍页与测试页（由服务根路径与 /test/* 提供） |
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.ps1ip_lookup_service\install_deps.bat
依赖中包含 ua-parser，用于 /api/lookup-ua 的 User-Agent 解析；浏览器与系统的 *_code 及图标路径与 WordPress wp-useragent 插件的规则对齐，以便使用现有 PNG 资源。
可选启用 Redis 缓存（见下方环境变量）。启用后，/api/lookup 与 /api/lookup-ua 会对 同一路径 +（排序后的）请求参数 缓存结果，默认缓存 1 小时；其中 /api/lookup-ua 在未传 ua 参数时会把实际使用的请求头 User-Agent 也纳入缓存 key（避免不同 UA 串互相污染缓存）。
通过环境变量覆盖默认路径与 CZDB 密钥（前缀 IP_LOOKUP_）：
| 变量 | 含义 | 默认 |
|---|---|---|
IP_LOOKUP_DB_ROOT | 数据库根目录 | 项目根目录下的 ip_db |
IP_LOOKUP_CZDB_KEY | 纯真 CZDB 解密密钥 | 与 PHP 示例一致 |
IP_LOOKUP_DEFAULT_METHOD | 默认查询方式 | ip2location |
IP_LOOKUP_REDIS_URL | Redis 连接串（启用缓存） | 空（不启用） |
IP_LOOKUP_CACHE_TTL_SECONDS | 缓存 TTL（秒） | 3600 |
IP_LOOKUP_CACHE_PREFIX | 缓存 key 前缀 | ip_lookup: |
查询方式取值：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
端口可改为任意可用端口（例如 --port 8899），下面 URL 中的 8765 请按实际端口替换。
- 根路径：
http://127.0.0.1:8765/（静态介绍页index.html，含轮播与接口说明摘要） - 交互式文档：
http://127.0.0.1:8765/docs - IP 查询测试：
http://127.0.0.1:8765/test/ip（亦可打开/static/ip_test.html） - IP + UA 联合测试：
http://127.0.0.1:8765/test/lookup-ua（亦可打开/static/lookup_ua_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 |
ip_version | IP 版本：ipv4 / ipv6 |
ip_icon_png | IP 版本图标（IPv4：/static/ua_icons/ipv4.png；IPv6：/static/ua_icons/ipv6.png） |
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 /api/lookup-ua
在 /api/lookup 返回的全部字段基础上，增加 UA 解析结果。归属地查询参数与 method 含义与上文相同。
| 查询参数 | 必填 | 说明 |
|---|---|---|
ip | 是 | IPv4 或 IPv6 |
method | 否 | 同 /api/lookup，默认 ip2location |
ua | 否 | 自定义 User-Agent 字符串；省略时使用当前请求的 User-Agent 请求头 |
| 字段 | 说明 |
|---|---|
ua_raw | 实际用于解析的 UA 字符串（来自 ua 参数或请求头） |
browser_name、browser_version_full、browser_version_major、browser_full | 浏览器名称与版本（ua-parser + 与插件一致的 code 推导） |
browser_code | 与图标文件名对应的代码（如 chrome） |
browser_icon_png | 浏览器图标 URL，如 /static/ua_icons/24/net/{browser_code}.png |
os_name、os_version_full、os_version_major、os_full | 操作系统名称与版本 |
os_code | 与图标文件名对应的代码（如 win-6） |
os_icon_png | 系统图标 URL，如 /static/ua_icons/24/os/{os_code}.png |
browser_icon_emoji、os_icon_emoji | 预留字段，当前为空字符串 |
示例：
GET /api/lookup-ua?ip=8.8.8.8&method=ip2location GET /api/lookup-ua?ip=114.114.114.114&method=czdb&ua=Mozilla/5.0%20...
第一条由浏览器直接访问时会自动带上浏览器的 User-Agent；第二条可在查询串中显式传入待分析的 UA。
- 先看
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 二进制文件。
