IPGeolocation/node-red-contrib-ipgeolocation
GitHub: IPGeolocation/node-red-contrib-ipgeolocation
为 Node-RED 提供 IPGeolocation.io API 的全套集成节点，涵盖 IP 地理定位、威胁情报、ASN 查询、时区、天文学及 User-Agent 解析。
Stars: 1 | Forks: 0
# node-red-contrib-ipgeolocation
用于 [IPGeolocation.io](https://ipgeolocation.io) v3 API 的 Node-RED 节点：IP 地理定位、安全和威胁情报、VPN 和代理检测、滥用联系人、ASN 查询、批量 IP 处理、时区和天文学，以及 user-agent 解析。
[](https://www.npmjs.com/package/node-red-contrib-ipgeolocation)
[](https://www.npmjs.com/package/node-red-contrib-ipgeolocation)
[](https://nodered.org)
[](https://nodejs.org)
[](./LICENSE)
一套完整且可用于生产环境的 **Node-RED IP 地理定位节点**。在低代码 Node-RED 流程中查询任何 IP 地址或域名的国家、城市、纬度和经度，对 IP 的代理、VPN、TOR 和机器人风险进行评分，解析 ASN 和滥用联系人数据，解析 user-agent 字符串，以及获取时区和天文学数据。
## 目录
- [功能](#features)
- [快速开始](#quick-start)
- [环境要求](#requirements)
- [安装](#installation)
- [配置：API key](#configuration-api-key)
- [节点工作原理](#how-the-nodes-work)
- [节点参考](#node-reference)
- [消息属性](#message-properties)
- [错误处理和重试](#error-handling-and-retries)
- [示例流程](#example-flows)
- [实践方案](#recipes)
- [API 额度](#api-credits)
- [开发和测试](#development-and-testing)
- [常见问题](#faq)
- [许可证](#license)
- [链接](#links)
## 功能
- **单一 IP 地理定位：**解析任何 IPv4、IPv6 或域名的国家、地区、城市、纬度、经度、货币和时区。
- **批量 IP 地理定位：**在一个请求中处理多达 50,000 个 IP 地址。
- **IP 安全和威胁情报：**检测代理、VPN、TOR、机器人和威胁评分，用于欺诈预防和访问控制。
- **批量安全查询：**在单次调用中对大型 IP 列表进行评分。
- **滥用联系人查询：**检索 IP 的滥用电子邮件、电话和所属组织。
- **ASN 查询：**通过 IP 或 AS 编号解析自治系统（Autonomous System）详细信息。
- **时区 API：**通过名称、IP、坐标、城市、IATA 代码、ICAO 代码或 UN/LOCODE 获取时区数据。
- **天文学 API：**通过坐标、地址或 IP 获取日出、日落、月出、月落、晨昏蒙影阶段、月相以及日月位置。
- **User-agent 解析器：**从 user-agent 字符串中识别浏览器、设备、操作系统和引擎。
- **开发者友好：**支持动态输入 `msg`、`flow` 和 `global`，可选的专用错误输出，带指数退避的自动重试，安全的凭证存储以及按请求的额度报告。
## 快速开始
```
# 在你的 Node-RED 用户目录中（通常是 ~/.node-red）
npm install node-red-contrib-ipgeolocation
```
1. 重启 Node-RED。
2. 将 **ipgeo lookup** 节点拖到画布上（在 **IPGeolocation** 面板类别下找到它）。
3. 打开节点，点击 **API Config** 旁边的铅笔图标，并粘贴你的[免费 IPGeolocation.io API key](https://app.ipgeolocation.io/signup)。
4. 连入一个 **inject** 节点，连出一个 **debug** 节点，然后部署。
5. 将任意 IP 字符串注入到 `msg.payload` 中，例如 `8.8.8.8`，然后从 debug 面板读取地理定位结果。
这就是完整的循环：注入一个 IP，获取返回的结构化位置数据。
## 环境要求
| 要求 | 版本 |
|-------------|---------|
| Node-RED | >= 2.0 |
| Node.js | >= 14.0 |
| IPGeolocation.io API key | 免费层即可使用（[注册](https://app.ipgeolocation.io/signup)） |
## 安装
### 调色板管理器（推荐）
1. 打开 Node-RED。
2. 转到 **菜单 > 管理调色板 > 安装**。
3. 搜索 `node-red-contrib-ipgeolocation`。
4. 点击 **安装**。
### npm
```
cd ~/.node-red
npm install node-red-contrib-ipgeolocation
```
重启 Node-RED。所有十个节点都将出现在面板的 **IPGeolocation** 类别下。
## 配置：API key
每个功能节点都引用一个共享的 **ipgeo config** 节点，该节点保存着你的 API key。该 key 作为加密的 Node-RED 凭证存储，绝不会写入导出的流程 JSON 中。
1. 将任何 IPGeolocation 节点拖到画布上。
2. 双击它，然后点击 **API Config** 旁边的铅笔图标。
3. 输入 **Name** 并粘贴你的 **API Key**。
4. 点击 **Add**，然后点击 **Done**。
在每个 IPGeolocation 节点中重复使用同一个配置节点，这样你就可以在一个地方管理一个 key。
## 节点工作原理
这些约定适用于所有九个功能节点。
**动态输入。**任何 IP、坐标或值都可以是静态字符串，或者在运行时从 `msg`、`flow` 或 `global` 属性中读取。一个配置好的节点可以服务于许多不同的输入。
**默认双输出。**每个节点都带有两个输出：
- 输出 1（成功）：API 结果，写入配置的属性（默认为 `msg.payload`）。
- 输出 2（错误）：带有结构化 `msg.error` 的原始 `msg`。
取消勾选 **Use second output** 可折叠为单个输出，并使用标准的 **Catch** 节点在整个流程范围内处理故障。
**响应整形。**大多数节点公开了 **Fields**（仅返回列出的点记法路径）和 **Excludes**（丢弃列出的路径），以便你可以裁剪大型响应，例如 `location.city,location.country_name` 或 `security.threat_score`。
**额度报告。**每次成功的响应都会将 `msg.ipgeo_credits` 设置为请求消耗的 API 额度数量。
## 节点参考
| 节点 | Endpoint | 用途 |
|------|----------|---------|
| `ipgeo-config` | n/a | 共享 API key 凭证 |
| `ipgeo-lookup` | `GET /v3/ipgeo` | 单个 IP 或域名地理定位 |
| `ipgeo-bulk` | `POST /v3/ipgeo-bulk` | 批量地理定位，最多 50,000 个 IP |
| `ipgeo-security` | `GET /v3/security` | 单个 IP 的安全和威胁数据 |
| `ipgeo-bulk-security` | `POST /v3/security-bulk` | 批量安全查询，最多 50,000 个 IP |
| `ipgeo-abuse` | `GET /v3/abuse` | 滥用联系人详细信息 |
| `ipgeo-asn` | `GET /v3/asn` | 通过 IP 或 AS 编号查询 ASN 详细信息 |
| `ipgeo-timezone` | `GET /v3/timezone` | 通过名称、IP、坐标、城市、IATA、ICAO、UN/LOCODE 查询时区 |
| `ipgeo-astronomy` | `GET /v3/astronomy` | 日月数据 |
| `ipgeo-useragent` | `GET /v3/user-agent` | User-agent 解析 |
### ipgeo-lookup：单个 IP 地理定位
解析单个 IPv4、IPv6 或域名。将 IP 留空可查询调用者自身的 IP。
| 选项 | 描述 | 默认值 |
|--------|-------------|---------|
| IP / Domain | 静态值或 `msg` / `flow` / `global` 属性 | 空（调用者 IP） |
| Include | 要添加的可选数据模块 | 无 |
| Fields / Excludes | 限制或裁剪响应 | 全部 |
| Language | 响应语言 | `en` |
| User-Agent header | 将 UA 字符串作为请求头转发 | 关闭 |
| Output to | 目标属性 | `msg.payload` |
包含模块：
| 模块 | 额外额度 | 添加内容 |
|--------|:---:|------|
| `security` | +2 | 代理、VPN、TOR、机器人、威胁评分 |
| `abuse` | +1 | 滥用联系人（电子邮件、电话、组织） |
| `user_agent` | 0 | 解析后的 user-agent |
| `geo_accuracy` | 0 | 准确度半径和置信度 |
| `dma_code` | 0 | 美国指定市场区域代码 |
| `hostname` | 0 | 来自本地数据库的 PTR |
| `liveHostname` | 0 | 实时 DNS PTR 查询 |
| `hostnameFallbackLive` | 0 | 先查数据库，再查实时 DNS |
在上游设置 `msg.ipgeo_include` 可按消息覆盖包含列表。
### ipgeo-bulk：批量 IP 地理定位
在一个 POST 中发送多达 50,000 个 IP 或域名。
- **输入：**`msg.payload` 作为字符串数组（`["1.2.3.4", "example.com"]`）或逗号分隔的字符串，将被自动拆分。
- **输出：**按输入顺序排列的结果对象数组。无效或私有条目将返回为 `{ "message": "..." }`。
```
// Keep only successfully resolved results
const resolved = msg.payload.filter(r => r.ip);
```
### ipgeo-security：IP 安全和威胁情报
单个 IP 风险查询：代理、VPN、TOR 和机器人检测，以及威胁评分，适用于欺诈检查、登录保护和访问控制。支持 **Fields** 和 **Excludes**。
### ipgeo-bulk-security：批量 IP 安全
安全查询的批量版本，最多 50,000 个 IP。输入处理与 `ipgeo-bulk` 匹配。当某些条目无法评分时，节点会对其进行汇总：
| 属性 | 设置时机 | 含义 |
|----------|----------|---------|
| `msg.ipgeo_invalid_count` | 条目没有 `security` 对象 | 无效条目的计数 |
| `msg.ipgeo_invalid_messages` | 同上 | 无效条目的消息 |
当每个条目都有效时，这两者都会从 `msg` 中删除。
### ipgeo-abuse：滥用联系人查询
返回 IP 的滥用联系人记录，例如 `abuse.emails`、`abuse.phone_numbers` 和所属组织。支持 **Fields** 和 **Excludes**。
### ipgeo-asn：ASN 查询
查询自治系统详细信息。**Query type** 选择发送的内容：
| 查询类型 | 发送内容 | 说明 |
|------------|-------|-------|
| `auto` | ip 和 asn 都不发送 | API 根据上下文推断 |
| `ip` | `ip=` | 解析 IP 背后的 ASN |
| `asn` | `asn=` | `AS` 前缀会自动去除（`AS15169` 变为 `15169`） |
支持 **Include** 列表（`peers`、`downstreams`、`upstreams` 等），可通过 `msg.ipgeo_include` 按消息覆盖，还支持 **Fields** 和 **Excludes**。
### ipgeo-timezone：时区 API
七种查询模式：
| 模式 | 发送的参数 | 示例 |
|------|----------------|---------|
| 时区名称 | `tz` | `America/New_York` |
| IP 地址 | `ip` | `8.8.8.8` |
| 地址 / 城市 | `location` | `Paris, France` |
| 坐标 | `lat` + `long` | `48.8566`, `2.3522` |
| IATA 机场 | `iata_code` | `CDG` |
| ICAO 机场 | `icao_code` | `LFPG` |
| UN/LOCODE | `lo_code` | `FRPAR` |
当所选模式所需的值缺失时，返回 `INVALID_INPUT`。
### ipgeo-astronomy：日月数据
返回日出、日落、月出、月落、晨昏蒙影阶段（民用、航海、天文，以及蓝调和黄金时刻）、正午、日照长度、月相、亮度以及实时日月位置。
可以通过四种方式获取位置，通过 **Look up by** 模式进行选择：
| 模式 | 发送内容 | 说明 |
|------|-------|-------|
| `coords` | `lat` + `long` | 十进制度数；两者均为必填 |
| `location` | `location` | 地址，最好是城市，例如 `New York, USA` |
| `ip` | `ip` | 任何 IPv4 或 IPv6 地址；在响应中增加一个 `ip` 字段| `auto` | 无 | API 使用调用者的 IP |
当提供多个参数时，API 的首选顺序是坐标，其次是位置，然后是 IP。坐标和位置模式在其值缺失时会返回 `INVALID_INPUT`。
可选参数（适用于所有模式）：
| 选项 | 参数 | 描述 |
|--------|-----------|-------------|
| Date | `date` | `YYYY-MM-DD`；默认为该地点的今天 |
| Time zone | `time_zone` | IANA 名称；将所有事件时间转换为此时区 |
| Elevation | `elevation` | 海拔高度（米），0 到 10000；默认为 0 |
| Language | `lang` | `location` 对象的语言（付费计划） |
响应将结果嵌套在 `astronomy` 对象下，与 `location` 对象并排，因此请读取诸如 `payload.astronomy.sunrise` 和 `payload.location.city` 之类的值。
### ipgeo-useragent：user-agent 解析器
将 user-agent 字符串解析为浏览器、设备、操作系统和引擎。UA 作为请求头而不是查询参数发送到 API。
在 HTTP-in 流程中非常理想：将 UA 源指向 `msg.req.headers.user-agent`（默认值），以自动解析每个访问者的浏览器。空的 UA 将返回 `INVALID_INPUT`。
## 消息属性
| 属性 | 方向 | 类型 | 描述 |
|----------|-----------|------|-------------|
| `ipgeo_credits` | 输出 | number | 请求消耗的额度 |
| `ipgeo_include` | 输入 | string | 在受支持的情况下，按消息覆盖包含列表 |
| `ipgeo_invalid_count` | 输出 | number | 批量安全：没有安全结果的条目数 |
| `ipgeo_invalid_messages` | 输出 | array | 批量安全：无效条目的消息 |
| `error` | 输出 | object | 在错误输出上：`{ code, message, status, body }` |
## 错误处理和重试
失败时，节点会设置 `msg.error`，包含类型化的 `code`、可读的 `message`、适用情况下的 HTTP `status` 以及原始响应 `body`。
| 代码 | 原因 |
|------|-------|
| `NO_API_KEY` | 缺少配置节点或 key 为空 |
| `BAD_REQUEST` | 参数无效（HTTP 400） |
| `AUTH_FAILED` | API key 无效或缺失（HTTP 401） |
| `FORBIDDEN` | 计划限制或来源未加入白名单（HTTP 403） |
| `NOT_FOUND` | 未找到 Endpoint 或资源（HTTP 404） |
| `VALIDATION` | 验证错误（HTTP 422） |
| `LOCKED` | Key 被锁定、超出配额或账户被暂停（HTTP 423） |
| `RATE_LIMITED` | 请求过多（HTTP 429） |
| `SERVER_ERROR` | API 内部错误（HTTP 500） |
| `HTTP_ERROR` | 任何其他非 2xx 状态 |
| `TIMEOUT` | 请求超时 |
| `NETWORK_ERROR` | DNS 或连接失败 |
| `NO_RESPONSE` | 请求已发送但未收到响应 |
| `INVALID_INPUT` / `INVALID_MODE` | 节点输入缺失或格式错误 |
| `TOO_MANY_IPS` | 批量请求超过 50,000 个 IP 的限制 |
**自动重试。** 瞬时故障（HTTP 429、500、502、503、504、超时和网络错误）最多重试 3 次，采用指数退避机制（500 毫秒、1 秒、2 秒）。对于 HTTP 429，如果存在 `Retry-After` 标头，则会予以遵循。默认请求超时为 10 秒，批量 Endpoint 为 30 秒。
## 示例流程
该包捆绑了随时可导入的示例，每个功能节点一个：
| 示例 | 演示 |
|---------|--------------|
| 01 - Single IP Lookup | `ipgeo-lookup` |
| 02 - Bulk IP Lookup | `ipgeo-bulk` |
| 03 - IP Security Lookup | `ipgeo-security` |
| 04 - Bulk IP Security | `ipgeo-bulk-security` |
| 05 - Abuse Contact Lookup | `ipgeo-abuse` |
| 06 - ASN Lookup | `ipgeo-asn` |
| 07 - Timezone Lookup | `ipgeo-timezone` |
| 08 - Astronomy (Sun & Moon) | `ipgeo-astronomy` |
| 09 - User-Agent Parser | `ipgeo-useragent` |
导入方法：**菜单 > 导入 > 示例**，然后选择 **node-red-contrib-ipgeolocation** 并挑选一个流程。每个示例都包含一个 inject 触发器、连接到结果和错误 debug 节点的节点，以及一个占位符配置节点。在部署之前，请将该配置节点指向你自己的 API key。
## 实践方案
### 按消息覆盖包含列表
```
// In a Function node upstream of ipgeo-lookup or ipgeo-asn
msg.ipgeo_include = "security,abuse";
return msg;
```
### 在 HTTP 流程中对访问者进行地理定位
配置 `ipgeo-lookup`，将 **IP / Domain** 设置为指向 `req.headers['x-forwarded-for']`（在代理后面）或 `req.connection.remoteAddress`（直连）的 `msg` 属性。
### 在边缘阻挡代理和 VPN
通过 `ipgeo-security` 处理传入的 IP，然后在 `payload.security.is_proxy` 或威胁评分上使用 **Switch** 节点，以便在流量到达你的应用程序之前丢弃或标记有风险的流量。
### 返回精简的批量响应
在 `ipgeo-bulk` 上，将 **Fields** 设置为 `location.city,location.country_name,asn.organization`，可选择添加 **Include** `security`，并使用 **Excludes** `security.threat_score` 以仅返回每个 IP 所需的数据。
## API 额度
| Endpoint 或模块 | 额度 |
|--------------------|:---:|
| 单个 IP 查询（基础） | 1 |
| + security 模块 | +2 |
| + abuse 模块 | +1 |
| 批量查询 | 每个有效 IP 1-4 |
| Security / bulk-security | 每个有效 IP 2 |
| ASN、Abuse、Timezone、User-Agent、Astronomy | 1 |
每个节点都会在 `msg.ipgeo_credits` 中报告实际费用。有关当前定价，请参阅[额度使用指南](https://ipgeolocation.io/documentation/credits-usage.html)。
## 开发和测试
```
npm install # install dependencies
npm test # run the mocha test suite
npm run coverage # run tests with an HTML and text coverage report
```
测试使用 `mocha`、`node-red-node-test-helper`、`should` 和 `nock`，所有 HTTP 均被完全模拟，因此测试套件可以离线运行，无需实时的 API 调用。规范位于 `test/**/*_spec.js` 中，涵盖共享的 API client、辅助程序、每个节点以及捆绑的示例流程。
## 常见问题
## 许可证
[MIT](https://github.com/IPGeolocation/node-red-contrib-ipgeolocation/blob/main/LICENSE) (c) IPGeolocation.io
## 链接
- [IPGeolocation.io 官网](https://ipgeolocation.io)
- [API 文档](https://ipgeolocation.io/documentation.html)
- [获取免费 API key](https://app.ipgeolocation.io/signup)
- [Node-RED](https://nodered.org)
- [npm 包](https://www.npmjs.com/package/node-red-contrib-ipgeolocation)
- [问题追踪器](https://github.com/IPGeolocation/node-red-contrib-ipgeolocation/issues)
如何获取 IPGeolocation.io API key？
在app.ipgeolocation.io/signup 注册一个免费账户。免费层提供足够的使用量来评估此包中包含的每个节点。
导出的流程中 API key 安全吗？
是的。API key 作为加密的 Node-RED 凭证存储在ipgeo-config 节点上，绝不会包含在导出的流程 JSON 中。
我可以一次查询多个 IP 地址吗？
是的。使用ipgeo-bulk 节点进行地理定位查询，或使用 ipgeo-bulk-security 节点进行安全和威胁分析。两者都支持在单个请求中处理多达 50,000 个 IP 地址。
如何检测 VPN、代理或 TOR 出口节点？
使用ipgeo-security 节点，或者在使用 ipgeo-lookup 时启用 security 包含模块。响应包含指示代理使用情况、VPN 检测、TOR 出口节点状态和其他相关威胁信息的字段。
它在反向代理后面工作吗？
是的。从req.headers['x-forwarded-for'] 读取客户端 IP 地址，并将其作为动态 msg 输入传递给 ipgeo-lookup，以对原始客户端进行地理定位。
当达到速率限制时会发生什么？
节点会使用指数退避自动重试请求，并在提供时遵循Retry-After 响应头。如果速率限制仍然存在，则操作将失败，并在错误输出上出现 RATE_LIMITED 错误。
标签：API集成, IP地理定位, MITM代理, Node-RED, 低代码, 可观测性, 威胁情报, 开发者工具, 数据可视化, 暗色界面, 自定义脚本