# @balena/proxy-protocol-parser 中文文档

规范地址：https://npmcn.com/package/%40balena/proxy-protocol-parser/

版本：1\.0\.3
npm 元数据更新时间：2026-03-02T15:05:27.399Z
中文译文更新时间：2026-11-07T18:18:35.257Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40balena/proxy-protocol-parser
原文对照：https://npmcn.com/package/%40balena/proxy-protocol-parser/?lang=original
项目主页：https://github.com/balena-io-modules/proxy-protocol-parser#readme
源码仓库：https://github.com/balena-io-modules/proxy-protocol-parser

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：22.1 kB，17 个文件
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2019-03-08T11:07:20.426Z
- 最新版本发布：2026-03-02T15:05:27.097Z
- 近 30 天下载量：3190（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 5 个）

## 中文简介

代理协议 v1 文本和 v2 二进制格式的编码器和解码器

## 安装

```sh
npm install @balena/proxy-protocol-parser
```

也可以使用：`pnpm add @balena/proxy-protocol-parser`、`yarn add @balena/proxy-protocol-parser`、`bun add @balena/proxy-protocol-parser`

## README

# 代理 protocol- parser 服务器

[![npm version](https://badge.fury.io/js/%40balena%2Fproxy-protocol-parser.svg)](http://badge.fury.io/js/%40balena%2Fproxy-protocol-parser) [![dependencies](https://david-dm.org/balena-io-modules/proxy-protocol-parser.png)](https://david-dm.org/balena-io-modules/proxy-protocol-parser.png)

## 概览

使用 v1 文本和 v2 二进制格式的代理协议头的简单编码和解码器.

见 [http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt](http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt) 详细情况.

支持IPv4和IPv6,UDP和TCP,但不支持UNIX套接字.

## 安装

```
npm install @balena/proxy-protocol-parser
```

## 编码

提供了单独的v1和v2编码器.

```
var buf = require('@balena/proxy-protocol-parser').v2_encode(socket);
```

或者说

```
var buf = require('proxy-protocol-parser').v2_encode({
  remoteFamily: 'IPv4',
  remoteAddress: '12.34.56.78',
  remotePort: 1234,
  localAddress: '172.16.0.1,
  localPort: 8080,
  protocol: 'udp'
});
```

`protocol` 默认为 `'tcp'` 如果没有说明的话.

这个 `v1_encode` 函数具有相同的 API ,但受 v1 格式限制,因此只有 `tcp` 协议得到支持.

## 解码

提供了检测任何信头格式的通用解码器。 如果没有发现有效的 v1 或 v2 签名, `null` 已返回.

```
var details = require('@balena/proxy-protocol-parser').decode(buf);
if(details === null) {
    console.log('No proxy protocol header detected');
}

var remoteFamily = details.remoteFamily,
    remoteAddress = details.remoteAddress,
    remotePort = details.remotePort,
    localAddress = details.localAddress,
    localPort = details.localPort,
    protocol = details.prototol;
```

如果知道预期版本,则为每个版本提供单独的解码器.

```
var v1_details = require('@balena/proxy-protocol-parser').v1_decode(buf);
var v2_details = require('@balena/proxy-protocol-parser').v2_decode(buf);
```

格式特定函数将承担一个信头的存在,如果一个信头不存在,可能会丢出错误或返回无效的细节.

每个解码操作都有一个选项 `validate` 第二个参数,它使信头被验证(如果无效,则出错),而检查签名有效性的次要费用是对字段值的其他有效性检查.

## 测试

```
nodeunit test
```

## 常见问题

### @balena/proxy-protocol-parser 是什么？

代理协议 v1 文本和 v2 二进制格式的编码器和解码器

### 如何安装 @balena/proxy-protocol-parser？

在项目目录运行 npm install @balena/proxy-protocol-parser，或使用 pnpm add / yarn add / bun add。

### @balena/proxy-protocol-parser 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @balena/proxy-protocol-parser 可以商用吗？

@balena/proxy-protocol-parser 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @balena/proxy-protocol-parser 的下载量有多少？

根据 npm 官方下载统计，@balena/proxy-protocol-parser 在 2026/10/08 – 2026/11/06 这 30 天内被下载 3,190 次，日均约 106 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @balena/proxy-protocol-parser 还在维护吗？

最新版本 1\.0\.3 发布于 2026/03/02（8 个月前）；至今共发布 19 个版本，其中过去 12 个月发布了 5 个；首次发布于 2019/03/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。