基于纯真IP库的精确地理定位服务
支持 IPv4 / IPv6 / 域名解析 · 双格式 API（JSON + TXT）· 自带暗色 Web 界面 · 中英文双语切换
_{本项目的设计与代码由 AI 辅助生成}

项目简介 · 快速开始 · API 文档 · 配置说明 · 安全防护

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 和纯文本双格式，方便集成到各类应用中
• SEO 友好 — 支持 ?q=IP URL 参数直接查询，动态标题，每个查询结果页独立可收录
• 网站统计 — 内置 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 Engine 20.10+ 和 Docker Compose V2。

# 1. 创建环境配置（必需！否则容器启动失败）
cp .env.example .env

# 2. 境内部署建议编辑 .env，改用国内 DNS 避免解析超时：
#     PUBLIC_DNS=223.5.5.5,119.29.29.29

# 3. 构建并启动
docker compose up -d --build

# 查看日志
docker compose logs -f

# 等待看到 "纯真IP库在线查询系统" 启动信息后访问 http://localhost:6688

注意： 首次启动时 IP 数据库可能为空，需手动触发更新或等待周一凌晨 3:00 自动更新。 ARM64 支持： node:18-alpine 多架构镜像原生支持 AMD64 / ARM64 / ARMv7。

在宝塔「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次/分钟）+ 安全头
• 多层缓存加速 — 服务端 LRU 缓存 + 浏览器/ CDN HTTP 缓存头 + 客户端 500 条结果缓存

所有接口支持 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               # 按需修改

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

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

# 服务端口
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

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

系统默认已允许百度统计、Google Analytics、Cloudflare、jsDelivr CDN 加载脚本和追踪像���。如需添加其他第三方服务域名，在 .env 中设置：

# 允许加载 JS 的域名（逗号分隔）
CSP_EXTRA_SCRIPT=https://sdk.example.com
# 允许加载图片/追踪像素的域名
CSP_EXTRA_IMG=https://analytics.example.com
# 允许 fetch/XHR 连接的域名
CSP_EXTRA_CONNECT=https://api.example.com

建议前面加 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;
    }
}

系统通过 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。

除了自建服务，也可以用以下第三方 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 自动更新。

Zeruns's Blog

站长交流群：767557452

需要服务器部署本项目？可参考以下推荐：

• 👉 VPS/云服务器推荐列表
• 👉 阿里云服务器（优惠）

• 高性价比和便宜的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

GNU General Public License v3.0