AI摘要

开源纯真IP库在线查询系统，支持IP地理位置、本机IP、域名解析及批量查询，提供RESTful API、中英文界面与自动更新。内置CC防护与限流，支持Nginx反代及CDN，适合集成或自建IP查询服务。

此内容根据文章生成，仅用于文章内容的解释与总结

开源一个纯真IP库在线查询系统，支持IP地理位置查询、本机IP查询、域名解析等，支持API接口调用。

本项目全程由AI辅助开发！

Hermes Agent 部署全指南，手把手教你搭建你的第一个AI助手：https://blog.zeruns.com/archives/939.html

项目简介

ip-query-web 是一个基于纯真 IP 数据库（qqwry.ipdb）的 IP 地理位置在线查询系统。你可以用它：

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

适用场景

• 获取网站访客来源信息（配合 Nginx 反代可识别真实 IP，支持 Cloudflare / 阿里云 CDN 等）
• 为其他应用提供 IP 地理位置查询 API
• 用作自定义查询工具或集成到自动化脚本中
• 学习 Node.js/Express Web 开发与项目架构

安装部署

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

# 需要 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/

功能特性

• IPv4 / IPv6 双栈双库 — IPv4 查询使用纯真 Dat 格式（qqwry.dat），IPv6 查询使用 IPIP.net 格式（qqwry.ipdb），数据更精准
• 域名解析 — 自动解析 A / AAAA 记录并查询每个 IP
• 双格式 API — JSON 和纯文本（.txt）输出，适应不同场景
• 暗色 Web 界面 — 自带查询页面、API 文档、统计面板
• 中英文双语 — 支持中文和 English 界面切换，自动检测浏览器语言偏好
• 命令行工具 — node cli.js <IP/域名> 直接查询
• IP 库自动更新 — 每周一凌晨 3:00 自动拉取最新纯真 IP 库（支持 GitHub 镜像加速）
• 网站统计 — PV 和 API 调用统计，基于 Chart.js 图表展示
• 三层安全防护 — CC 防护 + 全页面分级限流（普通API 120次/分钟、DNS 30次/分钟、页面 120次/分钟）+ 安全头

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 文件管理。源码中配置位于 src/config.js，.env.example 包含完整模板。

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

服务配置

限流配置

CC 防护配置

DNS 和网络配置

IP 库更新配置

HTTPS 配置

如使用 Nginx/Caddy 反向代理做 SSL 终端，这两个变量保持注释即可。

网站信息配置（静态文件）

以下配置项通过修改 HTML 静态文件完成，详见各文件内的标签：

示例 .env

# 服务端口
PORT=6688

# 国内服务器推荐配置
GITHUB_MIRROR=https://gh-proxy.com/

# 限流调大（高并发场景）
RATE_LIMIT_MAX=300
RATE_LIMIT_DNS=60

# CC 防护调宽松
CC_MAX_CONCURRENT=50
CC_BLOCK_DURATION=30000

安全防护

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

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，优先级从高到低：

使用 CDN 时需要配置两处：

1. CDN 侧 — 开启真实 IP 传递：

• 阿里云 ESA（方法一，推荐）：ESA 控制台 → 站点 → 规则设置 → 转换规则 → 托管转换 → 开启「添加真实客户端 IP 标头」，默认标头名 ali-real-client-ip。
• 阿里云 ESA（方法二）：规则设置 → 转换规则 → 新增请求头规则，将真实客户端 IP 通过 X-Forwarded-For 传递。
• Cloudflare：默认已开启，无需额外配置。

2. Nginx 侧 — 信任代理 IP：

server {
    set_real_ip_from 0.0.0.0/0;
    real_ip_header X-Forwarded-For;
    real_ip_recursive on;

    location / {
        proxy_pass http://127.0.0.1:6688;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        ...
    }
}

Cloudflare 用户将 real_ip_header 改为 CF-Connecting-IP。

第三方API推荐

除了自建服务，也可以用以下第三方 IP 查询 API：第三方API推荐

项目结构

├── 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 文档（在线测试）
│   ├── api-recommend.html # 第三方 API 对比
│   ├── stats.html         # 统计面板（Chart.js 图表）
│   ├── i18n.js            # 中英文双语切换
│   ├── favicon.ico        # 网站图标
│   ├── favicon.png        # 网站图标
│   └── components/        # 页头/页尾组件
└── data/                  # IP 数据库 & 统计数据

运行条件

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

数据来源

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

推荐阅读

• 高性价比和便宜的VPS/云服务器推荐： https://blog.zeruns.com/archives/383.html
• 我的世界开服教程：https://blog.zeruns.com/tag/mc/
• 跨境电商独立站搭建教程，WordPress外贸建站指南：https://blog.zeruns.com/archives/889.html
• Hermes Agent 部署全指南，手把手教你搭建你的第一个AI助手：https://blog.zeruns.com/archives/939.html
• 阿里云ESA（CDN）测评，免费不限流量，全球节点（含境内）：https://blog.zeruns.com/archives/920.html
• Discourse论坛搭建教程，零基础部署Discourse开源社区论坛网站：https://blog.zeruns.com/archives/919.html