do1e/ip-api repository overview

Github⁠

⁠IP-API

支持跨域的 IP 查询服务，返回访问者的 IP 及其地理位置信息。

IP地址位置数据由 纯真 CZ88⁠ 提供支持

⁠环境变量

⁠接口

• GET / 返回查询页面（HTML）
• GET /get-ip 返回当前请求者的 IP 信息（JSON）
  • 可选查询参数 ?ip=<目标IP>，查询指定 IP

⁠返回示例

配置了 KEY 时（IPv4）：

{
  "ip": "114.xxx.xxx.xxx",
  "region": "中国 江苏 南京 教育网/南京大学",
  "db_update_time": "2026-07-03",
  "error": null
}

未配置 KEY 时，仅返回 IP，region 与 db_update_time 为 null：

{
  "ip": "114.xxx.xxx.xxx",
  "region": null,
  "db_update_time": null,
  "error": null
}

⁠部署

⁠Docker

⁠无 CZDB 启动，仅返回 IP

docker run -d --restart=always --name ipapi \
    -e PORT=8000 \
    --network host \
    do1e/ip-api:latest

⁠使用 CZDB 解析地理位置信息

docker run -d --restart=always --name ipapi \
    -e PORT=8000 \
    -e DOWNLOAD_KEY=abcdefgh-0312-2001-3012-666666666666 \
    -e KEY=ABCDEFGhijklmnopqrsTUV== \
    -v ./data:/app/data \
    --network host \
    do1e/ip-api:latest

⁠nginx 反代参考

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name ipapi.example.com;
    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Real-PORT $remote_port;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

⁠双栈部署（IPv4 + IPv6）

通过两个域名解析到同一台服务器，分别只走 IPv4 / IPv6 链路，从而在前端分别获取访问者的 IPv4 和 IPv6 地址。

1. 准备两个域名，DNS 只各配一种记录：

   域名	记录类型	指向
   ip4.example.com	A	服务器 IPv4 地址
   ip6.example.com	AAAA	服务器 IPv6 地址

   客户端访问 ip4.example.com 时只会拿到 IPv4 地址，自然走 IPv4 链路；ip6.example.com 同理只走 IPv6 链路。

2. nginx 为两个域名各建一个 server，都反代到本机同一个服务：

   server {
       listen 443 ssl;
       listen [::]:443 ssl;
       server_name ip4.example.com ip6.example.com;
       location / {
           proxy_pass http://127.0.0.1:8000;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection "upgrade";
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
           proxy_set_header X-Real-PORT $remote_port;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       }
   }
   

   Copy

3. 设置环境变量，让首页按协议请求对应域名：

   IPV4_BASEURL=https://ip4.example.com
   IPV6_BASEURL=https://ip6.example.com
   

   Copy

   前端点击「IPv4」会请求 ip4.example.com/get-ip，点击「IPv6」会请求 ip6.example.com/get-ip，分别拿到访问者在两条链路上的真实地址。

⁠本地运行

需 Python ≥ 3.14，推荐使用 uv⁠：

uv sync
uv run python -m src.main