# @fullerstack/nax-ipware 中文文档 规范地址：https://npmcn.com/package/%40fullerstack/nax-ipware/ 版本：0\.10\.0 npm 元数据更新时间：2022-04-05T12:58:28.020Z 中文译文更新时间：2026-11-15T16:36:32.298Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40fullerstack/nax-ipware 原文对照：https://npmcn.com/package/%40fullerstack/nax-ipware/?lang=original 项目主页：https://github.com/neekware/fullerstack/blob/main/libs/nax-ipware/README.md 源码仓库：https://github.com/neekware/fullerstack ## 关键信息（来自 npm 元数据） - 包体积（解压后）：47.5 kB，20 个文件 - 模块格式：CommonJS - TypeScript 类型：包内自带 - 运行依赖：3 个 - 首次发布：2021-08-16T00:37:39.014Z - 最新版本发布：2022-02-03T00:57:25.716Z - 近 30 天下载量：8677（2026-10-16 至 2026-11-14，npm 官方下载统计） - 已发布版本数：23（近 12 个月 0 个） ## 中文简介 服务器应用程序的节点库, 检索用户真实的 IP 地址 ## 安装 ```sh npm install @fullerstack/nax-ipware ``` 也可以使用：`pnpm add @fullerstack/nax-ipware`、`yarn add @fullerstack/nax-ipware`、`bun add @fullerstack/nax-ipware` ## README # NAX IP软件( 一个节点应用程序不可知库) **服务器应用程序的节点库, 检索用户真实的 IP 地址** [![status-image](https://github.com/neekware/fullerstack/actions/workflows/ci.yml/badge.svg)](https://github.com/neekware/fullerstack/actions/workflows/ci.yml) [![version-image](https://img.shields.io/npm/v/@fullerstack/agx-store.svg)](https://www.npmjs.com/package/@fullerstack/agx-store) [![coverage-image](https://coveralls.io/repos/neekware/fullerstack/badge.svg)](https://coveralls.io/r/neekware/fullerstack) # 概览 **最佳尝试** 在保留客户端IP地址的同时获取该地址 **饮用**。 。 。 . # 通知 没有好东西 `out-of-the-box` 针对假IP地址的解决方案, aka _IP 地址窃取_。 。 。 . 欢迎您阅读 [高级用户](https://npmcn.com/package/%40fullerstack/nax-ipware/README.md#advanced-users) 本页各节 使用情况 `trusted proxy prefixes` 和(或) `proxy count` 符合您需要的特性,特别是 _若为_ 你们是 计划纳入 `ipware` 在任何认证、安全或 `anti-fraud` 相关结构. 同时鼓励您使用 ip 过滤 `ipware` 以取得最佳结果. # 如何安装 `npm install @fullerstack/nax-ipware` 或 `yarn add @fullerstack/nax-ipware` # 如何使用 ```typescript # In a view or a middleware where the `request` object is available // In your js file (e.g. app.js) import {Ipware} from '@fullerstack/nax-ipware'; const ipware = new Ipware(); app.use(function(req, res, next) { req.ipInfo = ipware.getClientIP(req) // { ip: '177.139.100.100', isPublic: true, isRouteTrusted: false } // do something with the ip address (e.g. pass it down through the request) // note: ip address doesn't change often, so better cache it for performance, // you should have distinct session ID for public and anonymous users to cache the ip address next(); }); ``` # 高级用户 : | 旗帜 QQ | 说明 | | --: | :-- | | `count` ⇨ | : 预期代理人总数(模式: `client, proxy1, ..., proxy2`(中文(简体) ) : 如果 `count = 0` 接下来 `client` : 如果 `count = 1` 接下来 `client, proxy1` : 如果 `count = 2` 接下来 `client, proxy1, proxy2` : 如果 `count = 3` 接下来 `client, proxy1, proxy2 proxy3` | | `proxyList` ⇨ | : 信任代理人列表(模式 : `client, proxy1, ..., proxy2`(中文(简体) ) : 如果 `proxyList = ['10.1.']` 接下来 `client, 10.1.1.1` 或 `client, proxy1, 10.1.1.1` : 如果 `proxyList = ['10.1', '10.2.']` 接下来 `client, 10.1.1.1` 或 `client, proxy1, 10.2.2.2` : 如果 `proxyList = ['10.1', '10.2.']` 接下来 `client, 10.1.1.1 10.2.2.2` 或 `client, 10.1.1.1 10.2.2.2` | | `publicOnly` ⇨ | : 仅返回公共和互联网路由IP或无效 | | 输出字段QQ | 说明 | | --: | :-- | | `ip` ⇨ | : 客户端的IP地址 | | `isPublic` ⇨ | : 如果 `ip` 是公共和互联网的路由, `true`,则 `false` | | `isRouteTrusted` ⇨ | : 如果代理服务器 `count` 和(或) `proxyList` 提供和匹配, `true`,则 `false` | ### 优先发言顺序 客户端IP地址可以在一个或多个请求头属性中找到. 查找顺序从上到下,默认属性作为后继. ```typescript // The default meta precedence order export const IPWARE_HEADERS_IP_ATTRIBUTES_ORDER: string[] = [ 'X_FORWARDED_FOR', // Load balancers or proxies such as AWS ELB (default client is `left-most` [`, , `]) 'HTTP_X_FORWARDED_FOR', // Similar to X_FORWARDED_TO 'HTTP_CLIENT_IP', // Standard headers used by providers such as Amazon EC2, Heroku etc. 'HTTP_X_REAL_IP', 'HTTP_X_FORWARDED', 'HTTP_X_CLUSTER_CLIENT_IP', 'HTTP_FORWARDED_FOR', 'HTTP_FORWARDED', 'HTTP_VIA', 'X-REAL-IP', // NGINX 'X-CLUSTER-CLIENT-IP', // Rackspace Cloud Load Balancers 'X_FORWARDED', 'FORWARDED_FOR', 'CF-CONNECTING-IP', // CloudFlare 'TRUE-CLIENT-IP', // CloudFlare Enterprise, 'FASTLY-CLIENT-IP', // Firebase, Fastly 'FORWARDED', ]; ``` 您可以在初始化时提供自己的列表来自定义命令 `new Ipware(options)`。 。 。 . 您可以在每次呼叫时通过您的自定义列表, 以获取 ip . ```typescript ipware.getClientIP(request, { requestHeadersOrder: ['X_FORWARDED_FOR'], }); ipware.getClientIP(request, { requestHeadersOrder: ['X_FORWARDED_FOR', 'HTTP_X_FORWARDED_FOR'], }); // ... etc ``` ### 私人前缀 一个持有私有 IP 前缀的默认列表叫做 `IPWARE_PRIVATE_IP_PREFIX`。 。 。 . 此列表用于确定 IP 地址是否 `public` 或者说 `private`。 。 。 . 建议你给我们发任何 `private` 我们错过的IP地址, 将包含在默认列表中 . ```typescript export const IPWARE_PRIVATE_IP_PREFIX: string[] = [ '0.', // messages to software '10.', // class A private block ...[ // carrier-grade NAT (IPv4) '100.64.', '100.65.', '100.66.', '100.67.', ], // many more prefixes ] ``` 您可以自定义私人 IP 前缀, 在初始化时提供自己的列表 `new Ipware(options)`。 。 。 . 您可以在每次呼叫时通过您的自定义列表, 以获取 ip . ```typescript ipware.getClientIP(request, { privateIpPrefixes: ['0.', '10.'], // your own private IP addresses }); ipware.getClientIP(request, { privateIpPrefixes: ['0.', '10.', '2001:10:'], // your own private IP addresses }); // ... etc ``` ### 信任的代理人 如果您的节点服务器位于一个或多个已知代理服务器后方, 您可以过滤不想要的请求 通过提供 `trusted proxy list`,或已知的代理服务器 `count`。 。 。 . 您可以自定义代理 IP 前缀, 在初始化时提供自己的列表 `new Ipware(options)`。 。 。 . 您可以在每次呼叫中通过您的自定义列表, 当呼叫代理意识 api 来获取 ip 时 . ```typescript // In the above scenario, use your load balancer IP address as a way to filter out unwanted requests. const ipInfo = ipware.getClientIP(request, { proxy: { proxyList: ['177.139.233.132'] }, }); // If you have multiple proxies, simply add them to the list const ipInfo = ipware.getClientIP(request, { proxy: { proxyList: ['177.139.233.100', '177.139.233.132'] }, }); // For proxy servers with fixed sub-domain and dynamic IP, use the following pattern. const ipInfo = ipware.getClientIP(request, { proxy: { proxyList: ['177.139.', '177.140'] }, }); const ipInfo = ipware.getClientIP(request, { proxy: { proxyList: ['177.139.233.', '177.139.240'] }, }); // For proxy by ip address and count const ipInfo = ipware.getClientIP(request, { proxy: { proxyList: ['177.139.', '177.140'], count: 2 }, }); // For strict mode, we either return the ip that matches the proxy info, or none const ipInfo = ipware.getClientIP(request, { proxy: { strict: true, proxyList: ['177.139.233.', '177.139.240'] }, }); ``` 如下所述: `example`,您的公共负载平衡器(LB)可被视为一个 `trusted` 代理服务器. ``` `Real` Client <-> LB (Server) <-----> Node Server ^ | `Fake` Client <-> LB (Server) -+ ``` ### 代理计算 如果您的节点服务器位于后面 `known` 代理服务器的数量,但您在多个供应商上的部署,并且不想跟踪代理IP,您仍然可以通过提供代理来过滤不想要的请求 `count`。 。 。 . 您可以自定义代理数 `count` 在初始化时打电话 `new Ipware(options)`。 。 。 . 你可以通过你的习惯 `count` 当调用代理意识的 api 来获取 ip. ```typescript // In the above scenario, the total number of proxies can be used as a way to filter out unwanted requests. const ipInfo = ipware.getClientIP(request, { proxy: { count: 1 }, }); // For proxy by count, and proxy list const ipInfo = ipware.getClientIP(request, { proxy: { count: 1 proxyList: ['177.139.233.'] }, }); // For strict mode, we either return the ip that matches the proxy info, or none const ipInfo = ipware.getClientIP(request, { proxy: { strict: true, count: 1 }, }); ``` 如下所述: `example`,您的公共负载平衡器(LB)可被视为 `only` 代理服务器. ``` `Real` Client <-> LB (Server) <---> Node Server ^ | `Fake` Client ---+ ``` ### 只有公开的IP地址(互联网上的程序表) ```typescript // For publicOnly mode, we either return the first public IP address based on order or none const ipInfo = ipware.getClientIP(request, { publicOnly: true }); ``` ### 创建请求 如果您的代理服务器有 `custom` 配置 `right-most` IP 地址是源客户端的地址, 您 可以显示 `right-most` 作为 `order` 当唤作任何一物时. 请注意: [事实](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For) 标准 对于源客户端 IP 地址是 `left-most` 总计 `client, proxy1, proxy2`,则 `right-most` 代理最多 信任的代理服务器 . # 运行测试 对照当前环境进行测试: ``` yarn nx test nax-ipware ``` # 许可证 A) 释放[麻省理工学院](https://raw.githubusercontent.com/neekware/fullerstack/main/LICENSE)许可证. # 版本 X.Y.Z 版本 ``` `MAJOR` version -- making incompatible API changes `MINOR` version -- adding functionality in a backwards-compatible manner `PATCH` version -- making backwards-compatible bug fixes ``` # 发起人 [Neekware Inc. (英语).](http://neekware.com/) ## 常见问题 ### @fullerstack/nax-ipware 是什么？ 服务器应用程序的节点库, 检索用户真实的 IP 地址 ### 如何安装 @fullerstack/nax-ipware？ 在项目目录运行 npm install @fullerstack/nax-ipware，或使用 pnpm add / yarn add / bun add。 ### @fullerstack/nax-ipware 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @fullerstack/nax-ipware 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @fullerstack/nax-ipware 可以商用吗？ @fullerstack/nax-ipware 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @fullerstack/nax-ipware 的下载量有多少？ 根据 npm 官方下载统计，@fullerstack/nax-ipware 在 2026/10/16 – 2026/11/14 这 30 天内被下载 8,677 次，日均约 289 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @fullerstack/nax-ipware 还在维护吗？ 最新版本 0\.10\.0 发布于 2022/02/03（4 年前）；至今共发布 23 个版本，其中过去 12 个月发布了 0 个；首次发布于 2021/08/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。