ip-query-web 是一个基于纯真 IP 数据库（qqwry.ipdb）的 IP 地理位置在线查询系统，支持 IPv4/IPv6 双栈双库查询。全程由 AI 辅助开发，提供 RESTful API 接口，方便集成到各类应用中。

核心功能

• IP 归属地查询：输入任意 IPv4/IPv6 地址，获取国家、省份、城市、区县、运营商等信息
• 域名解析：自动解析域名的 A/AAAA 记录并查询每个 IP 的地理位置
• 获取客户端 IP：通过 /api/myip 或 /api/mylocation 获取访问者真实的来源 IP
• 批量查询：通过 POST /api/batch 单次最多查询 50 个 IP 地址
• 双格式 API：支持 JSON 和纯文本（.txt）输出，适应不同场景
• 网站统计：内置 PV 和 API 调用统计面板，基于 Chart.js 图表展示日/周/月/年数据
• 自动更新：每周一凌晨 3:00 自动从纯真 IP 库 GitHub 仓库拉取最新数据
• 中英文双语：支持中文 / English 界面切换，自动检测浏览器语言
• 命令行工具：node cli.js 直接查询

部署指南

项目提供三种部署方式：

方式一：裸机安装（推荐）

需要 Node.js 18+：

git clone https://github.com/zeruns/ip-query-web.git
cd ip-query-web
npm install --production
cp .env.example .env
node server.js

方式二：Docker 部署

# Docker Compose V2（Docker Desktop / Docker Engine 20.10+）
docker compose up -d --build

# Docker Compose V1（旧版，命令带横线）
docker-compose up -d --build

方式三：宝塔面板

在宝塔「Node 项目管理」中添加项目，启动命令 node server.js，端口 6688。

访问地址

在线演示：https://ip-query.zeruns.com/

API 接口

所有接口支持 JSON 和纯文本（后缀 .txt 或 ?format=txt）双格式。

调用示例

# JSON 格式 — 综合查询（支持 IP 和域名）
curl http://localhost:6688/api/query?q=8.8.8.8

# 纯文本格式
curl http://localhost:6688/api/query.txt?q=8.8.8.8

# 获取客户端 IP
curl http://localhost:6688/api/myip

# 批量查询
curl -X POST http://localhost:6688/api/batch \
  -H "Content-Type: application/json" \
  -d '{"ips":["8.8.8.8","1.1.1.1","2001:4860:4860::8888"]}'

命令行查询

node cli.js 114.114.114.114     # 查 IP 归属地
node cli.js blog.zeruns.com     # 查域名（解析 + 归属地）
node cli.js -6 ipv6.google.com  # 强制 IPv6

配置说明

所有配置通过环境变量或 .env 文件管理：

cp .env.example .env   # 复制默认配置
vim .env               # 按需修改

服务配置

限流配置

CC 防护配置

安全防护

系统内置三层防护链，公网部署无需额外配置：

Nginx 反向代理

建议前面加 Nginx 做 SSL 终端：

server {
    listen 443 ssl http2;
    server_name ip.example.com;

    ssl_certificate /etc/ssl/certs/example.crt;
    ssl_certificate_key /etc/ssl/private/example.key;

    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Host $host;

    location / {
        proxy_pass http://127.0.0.1:6688;
        proxy_http_version 1.1;
        proxy_read_timeout 60s;
    }
}

CDN 兼容

系统通过 getClientIP() 智能识别客户端真实 IP，支持 Cloudflare、阿里云 ESA、阿里云 CDN 等 CDN 请求头自动识别。

项目结构

├── server.js              # Express 服务器入口
├── cli.js                 # 命令行查询工具
├── package.json           # 项目配置与依赖
├── .env.example           # 环境变量模板
├── LICENSE                # GPL-3.0 许可证
├── src/
│   ├── config.js          # 统一配置层
│   ├── ipdb.js            # IP 库查询引擎
│   ├── updater.js         # 数据库自动更新
│   ├── ccProtection.js    # CC 防护中间件
│   ├── stats.js           # 网站统计模块
│   └── classifier.js      # 智能字段分类器
├── public/
│   ├── index.html         # 主查询页面（暗色主题）
│   ├── api-docs.html      # API 文档
│   ├── stats.html         # 统计面板
│   ├── i18n.js            # 中英文双语切换
│   └── components/        # 页头/页尾组件
└── data/                  # IP 数据库 & 统计数据

运行条件

• Node.js 18+
• 内存 256MB+
• 存储 ~150MB（含 IP 库 ~40MB）
• 系统 Linux / macOS / Windows (WSL)

开源地址

GitHub：zeruns/ip-query-web

数据来源：纯真 IP 库 (CZ88.NET)，通过 npm 包 qqwry.ipdb 分发，每周一凌晨 3:00 自动更新。