# IP归属地查询系统 **Repository Path**: zeruns/ip-query-web ## Basic Information - **Project Name**: IP归属地查询系统 - **Description**: 纯真IP库在线查询系统 — 支持IPv4/IPv6/域名解析,自带暗色Web界面和RESTful API。 IP geolocation query service powered by QQWry database. - **Primary Language**: NodeJS - **License**: GPL-3.0 - **Default Branch**: master - **Homepage**: https://blog.zeruns.com/ - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-05-24 - **Last Updated**: 2026-06-16 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # IP Query Web — Online IP Geolocation & Client IP Query

Precise IP geolocation service powered by CZ88.NET IP database
Supports IPv4 / IPv6 / Domain Resolution · Dual-format API (JSON + TXT) · Dark Web UI · Bilingual (Chinese/English)
AI-assisted project — design and code generated with AI

Overview · Quick Start · API Docs · Configuration · Security

--- ## Overview **ip-query-web** is an online IP geolocation query system based on the CZ88.NET IP database (qqwry.ipdb). Use it to: - **Query IP geolocation** — Look up any IPv4/IPv6 address to get country, province, city, district, and ISP information - **Domain resolution** — Automatically resolve A/AAAA records and query geolocation for each resolved IP - **Get client IP** — Retrieve the visitor's real source IP via `/api/myip` or `/api/mylocation` - **Batch query** — Query up to 50 IP addresses in a single POST `/api/batch` request - **API service** — RESTful API with JSON and plaintext dual-format support, easy integration into applications - **SEO friendly** — `?q=IP` URL parameter for direct query, dynamic titles, each result page independently indexable - **Website statistics** — Built-in PV and API call statistics dashboard with Chart.js charts (daily/weekly/monthly/yearly) - **Auto-update** — Automatically fetches the latest IP database from GitHub every Monday at 3:00 AM - **Bilingual UI** — Supports Chinese / English interface switching with automatic browser language detection - **CLI tool** — `node cli.js ` for direct terminal queries ### Use Cases - Identifying website visitor locations (Nginx reverse proxy supports real IP identification with Cloudflare/Aliyun CDN) - Providing IP geolocation API for other applications - Custom query tools or automation scripts - Learning Node.js/Express web development and project architecture ## Quick Start ### Method 1: Bare Metal (Recommended) ```bash # Requires 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 ``` ### Method 2: Docker ```bash docker compose up -d --build ``` ### Method 3: aaPanel (BT Panel) Add a Node.js project in aaPanel, with start command `node server.js` and port 6688. ## Access | URL | Description | |------|------| | `http://localhost:6688` | Main query interface | | `http://localhost:6688/?q=114.114.114.114` | Direct query by IP (shareable link / SEO indexing) | | `http://localhost:6688/api-docs.html` | API documentation (online testing) | | `http://localhost:6688/stats.html` | Website statistics (Chart.js charts) | ## Live Demo 🔗 [https://ip-query.zeruns.com/](https://ip-query.zeruns.com/) ## Features - **IPv4 / IPv6 dual-stack dual-DB** — IPv4 uses CZ88 Dat format (qqwry.dat), IPv6 uses IPIP.net format (qqwry.ipdb) for better accuracy - **Domain resolution** — Auto-resolve A/AAAA records and query each resolved IP - **Dual-format API** — JSON and plaintext (`.txt`) output for different scenarios - **Dark web UI** — Built-in query page, API docs, and statistics dashboard - **Bilingual (Chinese/English)** — Interface language switching with automatic browser language detection - **CLI tool** — `node cli.js ` for terminal queries - **Auto-updating IP database** — Auto-fetches latest CZ88.NET IP database every Monday at 3:00 AM (supports GitHub mirror acceleration) - **Website statistics** — PV and API call tracking with Chart.js visualization - **Three-layer security** — CC protection + tiered rate limiting (API 120/min, DNS 30/min, pages 120/min) + security headers - **Multi-layer caching** — Server-side LRU cache + browser/CDN HTTP cache headers + 500-entry client result cache ## API Endpoints All endpoints support JSON and plaintext (`.txt` suffix or `?format=txt`) dual format. | Endpoint | Description | Rate Limit (req/min) | |------|------|:---:| | `GET /api/query?q=` | Comprehensive query (recommended, supports IP and domain) | 30 | | `GET /api/myip` | Get client IP address (from request headers) | 120 | | `GET /api/location?q=` | Query IP geolocation (IP only) | 120 | | `GET /api/mylocation` | Get visitor source IP and geolocation | 120 | | `GET /api/resolve4?q=` | Resolve domain IPv4 addresses | 30 | | `GET /api/resolve6?q=` | Resolve domain IPv6 addresses | 30 | | `GET /api/info` | Database version info | 120 | | `GET /api/status` | Database status (availability check) | 120 | | `GET /api/stats?range=daily\|weekly\|monthly\|yearly` | Website statistics | 120 | | `POST /api/batch` | Batch IP query (max 50) | 120 | | `GET /health` | Health check (unlimited) | ∞ | ### Usage Examples ```bash # JSON format — comprehensive query (supports IP and domain) curl http://localhost:6688/api/query?q=8.8.8.8 # Plaintext format curl http://localhost:6688/api/query.txt?q=8.8.8.8 # Get client IP curl http://localhost:6688/api/myip # Batch query 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"]}' ``` ## CLI Tool ```bash node cli.js 114.114.114.114 # Query IP geolocation node cli.js blog.zeruns.com # Query domain (resolve + geolocation) node cli.js -6 ipv6.google.com # Force IPv6 ``` ## Configuration All configuration is managed via environment variables or `.env` file. Source code configuration is in `src/config.js`. See `.env.example` for the complete template. ```bash cp .env.example .env # Copy default config vim .env # Edit as needed ``` ### Server Configuration | Variable | Default | Description | |------|--------|------| | `PORT` | `6688` | Server port | | `HOST` | `::` | Listen address: `::` = dual-stack (recommended), `0.0.0.0` = IPv4 only, `127.0.0.1` = local only | | `LOG_LEVEL` | `info` | Log level: `debug`, `info`, `warn`, `error` | ### Rate Limit Configuration | Variable | Default | Description | |------|--------|------| | `RATE_LIMIT_MAX` | `120` | Standard API rate limit (req/min/IP) | | `RATE_LIMIT_DNS` | `30` | Domain query rate limit (involves DNS resolution, stricter) | | `RATE_LIMIT_PAGE` | `120` | Page/static resource rate limit (req/min/IP) | ### CC Protection Configuration | Variable | Default | Description | |------|--------|------| | `CC_MAX_CONCURRENT` | `20` | Max concurrent connections per IP, exceeded triggers auto-ban | | `CC_BURST_WINDOW` | `2000` | Burst detection window (milliseconds) | | `CC_BURST_MAX` | `40` | Max new connections within burst window | | `CC_SLOW_TIMEOUT` | `30000` | Slow attack timeout (ms), DNS resolution can take up to 20s | | `CC_BLOCK_DURATION` | `60000` | Auto-ban duration (ms), default 60 seconds | | `CC_WHITELIST` | empty | IP whitelist (comma-separated), whitelisted IPs are unrestricted | | `CC_BLACKLIST` | empty | IP blacklist (comma-separated), permanently blocked | ### DNS and Network Configuration | Variable | Default | Description | |------|--------|------| | `PUBLIC_DNS` | `8.8.8.8,8.8.4.4` | Public DNS servers for domain resolution (comma-separated, tried in order) | | `PUBLIC_IP_SOURCES` | `https://ipinfo.io/ip,https://api.ipify.org,https://checkip.amazonaws.com` | Public IP detection sources (comma-separated, fastest response wins) | ### IP Database Update Configuration | Variable | Default | Description | |------|--------|------| | `GITHUB_MIRROR` | `https://gh-proxy.com/` | GitHub mirror acceleration URL. Required for mainland China servers, leave empty for direct connection | | `DATA_DIR` | `./data` | IP database and statistics file directory | ### HTTPS Configuration | Variable | Default | Description | |------|--------|------| | `SSL_KEY` | empty | SSL private key file path, enables HTTPS when set | | `SSL_CERT` | empty | SSL certificate file path | > Leave these commented out if using Nginx/Caddy reverse proxy for SSL termination. ### Site Info Configuration (Static Files) > The following items are configured by modifying static HTML files: | Setting | File | Description | |------|--------|------| | Site URL | HTML pages `` | SEO canonical URL | | ICP filing number | `public/components/footer.html` | Footer filing link | | SEO title/description/keywords | HTML pages ``, `<meta name="description">`, `<meta name="keywords">` | Search engine optimization | ### Example `.env` ```bash # Server port PORT=6688 # Recommended for mainland China servers GITHUB_MIRROR=https://gh-proxy.com/ # Relaxed rate limits (high concurrency) RATE_LIMIT_MAX=300 RATE_LIMIT_DNS=60 # Relaxed CC protection CC_MAX_CONCURRENT=50 CC_BLOCK_DURATION=30000 ``` ## Security The system has built-in three-layer protection, ready for public deployment: | Layer | Implementation | Function | |:---:|------|------| | 1 | CC Protection (pure Node) | Connection limiting + burst detection + slow attack defense + auto-ban + IP whitelist/blacklist | | 2 | express-rate-limit | Tiered rate limiting by endpoint type (standard / DNS resolution) | | 3 | Security Headers + CSP | X-Frame-Options, CSP (script/img/connect-src), HSTS, Referrer-Policy, CORS | ### CSP Custom Domains By default, Baidu Analytics, Google Analytics, Cloudflare, and jsDelivr CDN are allowed to load scripts and tracking pixels. To add other third-party services, set in `.env`: ```bash # Allow JS loading from additional domains (comma-separated) CSP_EXTRA_SCRIPT=https://sdk.example.com # Allow images/tracking pixels from additional domains CSP_EXTRA_IMG=https://analytics.example.com # Allow fetch/XHR connections from additional domains CSP_EXTRA_CONNECT=https://api.example.com ``` ## Nginx Reverse Proxy It is recommended to put Nginx in front for SSL termination: ```nginx 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 Compatibility The system intelligently identifies the real client IP via `getClientIP()`, prioritized from highest to lowest: | CDN / Proxy | Header | Auto-detected | |-----------|-------|:---:| | Cloudflare | `CF-Connecting-IP` | ✓ | | Cloudflare / Aliyun / Google Cloud | `True-Client-IP` | ✓ | | Aliyun CDN | `Ali-CDN-Real-IP` | ✓ | | Nginx reverse proxy | `X-Real-IP` | ✓ | | Generic | `X-Forwarded-For` (first value) | ✓ | > **Two-step configuration required when using CDN:** > **1. CDN side — Enable real IP passthrough:** > > * **Aliyun ESA** (Method 1, recommended): ESA Console → Site → **Rules → Transform Rules → Managed Transforms** → Enable "Add real client IP header", default header name `ali-real-client-ip`. > * **Aliyun ESA** (Method 2): **Rules → Transform Rules** → Add a request header rule to pass the real client IP via `X-Forwarded-For`. > * **Cloudflare**: Enabled by default, no extra configuration needed. > > **2. Nginx side — Trust proxy IPs:** > > ```nginx > 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; > ... > } > } > ``` > > Change `real_ip_header` to `CF-Connecting-IP` for Cloudflare users. ## Third-Party API Recommendations In addition to self-hosted services, you can also use these third-party IP query APIs: [Third-Party API Recommendations](https://ip-query.zeruns.com/api-recommend.html) ## Project Structure ``` ├── server.js # Express server entry point ├── cli.js # CLI query tool ├── package.json # Project config & dependencies ├── .env.example # Environment variable template ├── LICENSE # GPL-3.0 license ├── src/ │ ├── config.js # Unified configuration layer │ ├── ipdb.js # IP database query engine │ ├── updater.js # Auto-update (supports mirror acceleration) │ ├── ccProtection.js # CC protection middleware │ ├── stats.js # Website statistics module │ └── classifier.js # Smart field classifier ├── public/ │ ├── index.html # Main query page (dark theme) │ ├── api-docs.html # API documentation (online testing) │ ├── api-recommend.html # Third-party API comparison │ ├── stats.html # Statistics dashboard (Chart.js) │ ├── i18n.js # Bilingual (Chinese/English) switching │ ├── favicon.ico # Favicon │ ├── favicon.png # Favicon │ └── components/ # Header/footer components └── data/ # IP database & statistics data ``` ## Requirements - **Node.js** 18+ - **RAM** 256MB+ - **Storage** ~150MB (including ~40MB IP database) - **OS** Linux / macOS / Windows (WSL) ## Data Source IP geolocation data comes from [CZ88.NET IP Database](https://github.com/nmgliangwei/qqwry.ipdb), distributed via the npm package `qqwry.ipdb`. Auto-updates every Monday at 3:00 AM. ## Author [Zeruns's Blog](https://blog.zeruns.com/) ## Community **QQ Group for Webmasters: [767557452](https://jq.qq.com/?_wv=1027&k=wgSx4AYc)** ## VPS/Cloud Server Recommendations Need a server to deploy this project? Check out these recommendations: - 👉 [VPS/Cloud Server Recommendations](https://blog.vpszj.cn/archives/41.html) - 👉 [Alibaba Cloud Server (Offers)](https://www.aliyun.com/minisite/goods?userCode=jdjc69nf) ## Recommended Reading - **Affordable VPS/Cloud Server Recommendations:** [https://blog.zeruns.com/archives/383.html](https://blog.zeruns.com/archives/383.html) - Minecraft Server Tutorial: [https://blog.zeruns.com/tag/mc/](https://blog.zeruns.com/tag/mc/) - Cross-Border E-Commerce WordPress Guide: [https://blog.zeruns.com/archives/889.html](https://blog.zeruns.com/archives/889.html) - Hermes Agent Deployment Guide: [https://blog.zeruns.com/archives/939.html](https://blog.zeruns.com/archives/939.html) - Aliyun ESA (CDN) Review: [https://blog.zeruns.com/archives/920.html](https://blog.zeruns.com/archives/920.html) - Discourse Forum Setup Tutorial: [https://blog.zeruns.com/archives/919.html](https://blog.zeruns.com/archives/919.html) ## License [GNU General Public License v3.0](LICENSE)