# @fluent-org/logger 中文文档

规范地址：https://npmcn.com/package/%40fluent-org/logger/

版本：1\.0\.10
npm 元数据更新时间：2022-09-17T10:36:47.178Z
中文译文更新时间：2026-11-15T01:00:32.479Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40fluent-org/logger
原文对照：https://npmcn.com/package/%40fluent-org/logger/?lang=original
项目主页：https://fluent.github.io/fluent-logger-forward-node/
源码仓库：https://github.com/fluent/fluent-logger-forward-node

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

- 包体积（解压后）：333 kB，69 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=12\.9\.0
- 运行依赖：1 个
- 首次发布：2021-08-06T10:13:54.586Z
- 最新版本发布：2022-09-17T10:36:47.089Z
- 近 30 天下载量：524778（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 0 个）

## 中文简介

一个节点流畅的协议兼容日志

## 安装

```sh
npm install @fluent-org/logger
```

也可以使用：`pnpm add @fluent-org/logger`、`yarn add @fluent-org/logger`、`bun add @fluent-org/logger`

## README

# @fluent-org/logger (英语)

[![Build Status](https://github.com/fluent/fluent-logger-forward-node/actions/workflows/main.yml/badge.svg)](https://github.com/fluent/fluent-logger-forward-node/actions) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Docs](https://img.shields.io/badge/Docs-latest-informational)](https://fluent.github.io/fluent-logger-forward-node/)

[流利前进协议](https://github.com/fluent/fluentd/wiki/Forward-Protocol-Specification-v1) 执行Node.js. 建造在 [流利- 浏览器- 节点](https://github.com/fluent/fluent-logger-node)。 。 。 .

[![NPM](https://nodeico.herokuapp.com/@fluent-org/logger.svg)](https://npmjs.com/package/@fluent-org/logger)

## 安装

```
$ npm install @fluent-org/logger
```

## 客户端

`@fluent-org/logger` 提供一个完全功能化的客户端来实施"前进协议". 它支持重联,确认,超时,事件重试等功能,并通过简单的打入的"承诺"接口来暴露其功能.

关于客户选择和方法的完整清单,请参见: [流利的文档](https://fluent.github.io/fluent-logger-forward-node/classes/FluentClient.html)

### 先决条件

流畅的守护进程应该以前向模式监听 .

Fluentd 简单的启动配置如下:

```aconf
<source>
  @type forward
  port 24224
</source>

<match **.*>
  @type stdout
</match>
```

见 [流利文件](https://docs.fluentd.org/input/forward) 需要更多信息.

Fluent Bit 类似的起始配置如下:

```ini
[INPUT]
    Name              forward
    Listen            0.0.0.0
    Port              24224
    Buffer_Chunk_Size 1M
    Buffer_Max_Size   6M

[OUTPUT]
    Name   stdout
    Match  *
```

见 [流利的比特文件](https://docs.fluentbit.io/manual/pipeline/inputs/forward) 需要更多信息.

### 向上游流利服务器发送事件记录

```js
const FluentClient = require("@fluent-org/logger").FluentClient;
const logger = new FluentClient("tag_prefix", {
  socket: {
    host: "localhost",
    port: 24224,
    timeout: 3000, // 3 seconds
  }
});
```

发射方法跟随签名

```typescript
emit(data: Record<string, any>): Promise<void>;
emit(data: Record<string, any>, timestamp: number | Date | EventTime): Promise<void>;
emit(label: string, data: Record<string, any>): Promise<void>;
emit(label: string, data: Record<string, any>, timestamp: number | Date | EventTime): Promise<void>;
```

返回的许诺在事件写入套接字后解决, 如果出错则被拒绝 .

### 鸣谢

这个 [流利的前进协议](https://github.com/fluent/fluentd/wiki/Forward-Protocol-Specification-v1) 为确认提供明确支持,使客户能够确定事件到达目的地.

促成承认意味着承诺通过下列方式得到回报: `emit` 将在客户端收到服务器明确确认后解决.

```js
const FluentClient = require("@fluent-org/logger").FluentClient;
const logger = new FluentClient("tag_prefix", {
  ack: {}
});
```

### 事件模式

这个 [流利的前进协议](https://github.com/fluent/fluentd/wiki/Forward-Protocol-Specification-v1) 提供多个消息模式, `Message`, (中文(简体) ), `Forward`, (中文(简体) ), `PackedForward`(违约), `CompressedPackedForward`。流利客户端支持所有它们.

```js
const FluentClient = require("@fluent-org/logger").FluentClient;
const logger = new FluentClient("tag_prefix", {
  eventMode: "Message" | "Forward" | "PackedForward" | "CompressedPackedForward"
});
```

### 禁用自动重接

```js
const logger = new FluentClient("tag_prefix", {
  socket: {
    host: "localhost",
    port: 24224,
    timeout: 3000, // 3 seconds
    disableReconnect: true
  }
});
// If you disable reconnections, the socket has to be manually connected, 
// connect() returns a promise, which rejects on connection errors.
logger.connect();
```

### 共享密钥认证

锁定配置 :

```js
const logger = new FluentClient("tag_prefix", {
  socket: {
    host: "localhost",
    port: 24224,
    timeout: 3000, // 3 seconds
  }
  security: {
    clientHostname: "client.localdomain",
    sharedKey: "secure_communication_is_awesome"
  }
});
```

流利配置 :

```aconf
<source>
  @type forward
  port 24224
  <security>
    self_hostname input.testing.local
    shared_key secure_communication_is_awesome
  </security>
</source>

<match dummy.*>
  @type stdout
</match>
```

另见 [流利](https://github.com/fluent/fluentd) 实例.

### TLS/ SSL 加密

锁定配置 :

```js
const logger = new FluentClient("tag_prefix", {
  socket: {
    host: "localhost",
    port: 24224,
    timeout: 3000, // 3 seconds
  }
  security: {
    clientHostname: "client.localdomain",
    sharedKey: "secure_communication_is_awesome"
  }
  tls: {
    ca: fs.readFileSync("/path/to/ca_cert.pem")
  }
});
```

流利配置 :

```aconf
<source>
  @type forward
  port 24224
  <transport tls>
    ca_cert_path /path/to/ca_cert.pem
    ca_private_key_path /path/to/ca_key.pem
    ca_private_key_passphrase very_secret_passphrase
  </transport>
  <security>
    self_hostname input.testing.local
    shared_key secure_communication_is_awesome
  </security>
</source>

<match dummy.*>
  @type stdout
</match>
```

FYI: 您可以使用 `fluent-ca-generate` 命令自流利 1.1.0起.

另见 [如何启用 TLS/ SSL 加密](https://docs.fluentd.org/input/forward#how-to-enable-tls-encryption)。 。 。 .

### 相互 TLS 认证

锁定配置 :

```js
const logger = new FluentClient("tag_prefix", {
  socket: {
    host: "localhost",
    port: 24224,
    timeout: 3000, // 3 seconds
  }
  security: {
    clientHostname: "client.localdomain",
    sharedKey: "secure_communication_is_awesome"
  }
  tls: {
    ca: fs.readFileSync("/path/to/ca_cert.pem"),
    cert: fs.readFileSync("/path/to/client-cert.pem"),
    key: fs.readFileSync("/path/to/client-key.pem"),
    passphrase: "very-secret"
  }
});
```

流利配置 :

```aconf
<source>
  @type forward
  port 24224
  <transport tls>
    ca_path /path/to/ca-cert.pem
    cert_path /path/to/server-cert.pem
    private_key_path /path/to/server-key.pem
    private_key_passphrase very_secret_passphrase
    client_cert_auth true
  </transport>
  <security>
    self_hostname input.testing.local
    shared_key secure_communication_is_awesome
  </security>
</source>

<match dummy.*>
  @type stdout
</match>
```

### 事件时间支持

我们还可以说明 [事件时间](https://github.com/fluent/fluentd/wiki/Forward-Protocol-Specification-v1#eventtime-ext-format) 作为时间戳。 见 [事件时间文件](https://fluent.github.io/fluent-logger-forward-node/classes/eventtime.html)

```js
const FluentClient = require("@fluent-org/logger").FluentClient;
const EventTime = require("@fluent-org/logger").EventTime;
const eventTime = new EventTime(1489547207, 745003500); // 2017-03-15 12:06:47 +0900
const logger = new FluentClient("tag_prefix", {
  socket: {
    host: "localhost",
    port: 24224,
    timeout: 3000, // 3 seconds
  }
});
logger.emit("tag", { message: "This is a message" }, eventTime);
```

### 处理错误

流利客户端将内部管理出错,拒绝对出错的承诺. 如果你想访问 面对内部错误的非用户, 你可以这样做,通过 `errorHandler`

```js
const FluentClient = require("@fluent-org/logger").FluentClient;
const logger = new FluentClient("tag_prefix", {
  onSocketError: (err: Error) => {
    console.error("error!", err)
  }
});
```

### 重试事件

有时如果初次提交失败,重新提交事件是有意义的。 您可以指定 `eventRetry`。 。 。 .

```js
const FluentClient = require("@fluent-org/logger").FluentClient;
const logger = new FluentClient("tag_prefix", {
  eventRetry: {}
});
```

## 服务器

`@fluent-org/logger` 包括可以用作下游流水槽的功能完备的前置服务器.

```js
const FluentServer = require("@fluent-org/logger").FluentServer;

const server = new FluentServer({ listenOptions: { port: 24224 }});

await server.listen();
```

流利配置 :

```aconf
<match pattern>
  @type forward
  send_timeout 60s
  recover_wait 10s
  hard_timeout 60s

  <server>
    name fluent_node 
    host 127.0.0.1
    port 24224
    weight 60
  </server>

  <secondary>
    @type file
    path /var/log/fluent/forward-failed
  </secondary>
</match>
```

见 [流利文件](https://docs.fluentd.org/output/forward) 需要更多信息.

或者,见 [流利的比特文件](https://docs.fluentbit.io/manual/pipeline/outputs/forward) 用于设置流利比特的信息.

服务器选项和方法的完整列表,请参见 [流利服务器文件](https://fluent.github.io/fluent-logger-forward-node/classes/fluentserver.html)

## 许可证

阿帕奇许可证2.0版.

## 关于节点JS版本

此软件包与NodeJS版本相容 QQ 12.

## 常见问题

### @fluent-org/logger 是什么？

一个节点流畅的协议兼容日志

### 如何安装 @fluent-org/logger？

在项目目录运行 npm install @fluent-org/logger，或使用 pnpm add / yarn add / bun add。

### @fluent-org/logger 支持 TypeScript 吗？

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

### @fluent-org/logger 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @fluent-org/logger 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=12\.9\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @fluent-org/logger 可以商用吗？

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

### @fluent-org/logger 的下载量有多少？

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

### @fluent-org/logger 还在维护吗？

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