# @nxgt/janus-webhooks-redis 中文文档

规范地址：https://npmcn.com/package/%40nxgt/janus-webhooks-redis/

版本：0\.6\.7
npm 元数据更新时间：2026-11-02T00:53:59.457Z
中文译文更新时间：2026-11-02T02:20:27.242Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40nxgt/janus-webhooks-redis
原文对照：https://npmcn.com/package/%40nxgt/janus-webhooks-redis/?lang=original
源码仓库：https://github.com/softistx/nxgt-janus

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

- 包体积（解压后）：91.7 kB，17 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：typescript ^6\.0\.3 \|\| ^7\.0\.0，@nxgt/janus ^0\.36\.0，@nxgt/redis \>=0\.3\.1 \<1，@nxgt/janus-webhooks ^0\.8\.7
- 首次发布：2026-09-27T04:29:58.256Z
- 最新版本发布：2026-11-02T00:53:59.217Z
- 已发布版本数：33（近 12 个月 33 个）

## 中文简介

@nxgt/janus-webhooks在@nxgt/ Redis上的Redis队列：超过进程的交付，在租约下自动声明

## 安装

```sh
npm install @nxgt/janus-webhooks-redis
```

也可以使用：`pnpm add @nxgt/janus-webhooks-redis`、`yarn add @nxgt/janus-webhooks-redis`、`bun add @nxgt/janus-webhooks-redis`

## README

# @nxgt / janus-webhooks-redis

Redis队列 [`@nxgt/janus-webhooks`](https://www.npmjs.com/package/@nxgt/janus-webhooks)： **快递在Redis等候**,在 [`@nxgt/redis`](https://www.npmjs.com/package/@nxgt/redis)的连接, 由应用程序的每个进程共享。重试时等待一个进程 崩溃、重启或被重新部署是由下一个发送的，并且请求被切断 一旦租约到期，Short将再次发送。

它实现了 `WebhookQueue` 端口，并通过 `@nxgt/janus-webhooks/conformance` 对着真正的Redis，停电 包含在每次CI运行中。

> **0\. x。** 一个小版本仍然可能改变表面；更新日志告诉我们该怎么做。

## 安装

```sh
bun add @nxgt/janus-webhooks-redis @nxgt/janus-webhooks @nxgt/janus @nxgt/redis
bun add zod                  # @nxgt/redis's peer, zod 4, if your application has none
bun add -d typescript        # 6 or 7
```

每个peer都是必需的：

-   `@nxgt/janus-webhooks`，它实现其端口；
-   `@nxgt/janus`,他的 `UserEvent` 它持有和谁持有 `StoreFailure` 它 投掷- a **同行**，从来没有依赖，所以 `instanceof StoreFailure` 持有 在你的代码中；
-   `@nxgt/redis`， `>=0.3.1 <1`布恩自己也和他有关系 `RedisClient`， 这样就继续下去了 **包子**；
-   `typescript` 6或7。

这个 `@nxgt/redis` 地板是经过测试的，而不是声明的：包的规格和它的 运行类型检查 `@nxgt/redis` 0.3.1以及，在地板作业中，在每个CI上 运行。

它需要 **Redis 7.0或更高版本**，或Valkey - see [Redis必须配置的](https://npmcn.com/package/%40nxgt/janus-webhooks-redis/docs/guide/wiring.md#what-redis-must-be-configured-with). 就像 `@nxgt/janus`，它期望 `"moduleResolution": "bundler"`.

## 使用

```ts
import { webhooks } from '@nxgt/janus-webhooks';
import { createRedisWebhookQueue } from '@nxgt/janus-webhooks-redis';
import { connectRedis } from '@nxgt/redis';

const secret = process.env.CRM_WEBHOOK_SECRET; // whsec_…, from mintWebhookSecret()
if (!secret) throw new Error('CRM_WEBHOOK_SECRET is not set');

const redis = await connectRedis(process.env.REDIS_URL ?? 'redis://localhost:6379', {
    enableOfflineQueue: false, // an outage fails the insert at once, not after 31 s
});

export const listener = webhooks({
    endpoints: [{ id: 'crm', url: 'https://crm.example.com/hooks/janus', secrets: [secret] }],
    queue: createRedisWebhookQueue(redis), // every process passes the same Redis and prefix
});

// janus({ …, events: listener })

process.on('SIGTERM', async () => {
    await listener.close(); // gives nothing up: what waits is sent by the next process
    process.exit(0);
});
```

给每个端点一个 `id` 当你第一次传递一个队列：它是什么队列 知道端点的值。 [布线](https://npmcn.com/package/%40nxgt/janus-webhooks-redis/docs/guide/wiring.md) 覆盖连接， 前缀，以及Redis必须配置的内容。

## API

| 出口 | 它是什么？ |
| --- | --- |
| `createRedisWebhookQueue(redis, options?)` | 返回一个 `WebhookQueue`,因为 `webhooks({ queue })`. `redis` 是什么 `connectRedis` 的回报。它不连接任何东西，也不创建任何东西：键是由第一次插入创建的。 |
| `RedisWebhookQueueOptions` | `{ prefix? }`每把钥匙的开头是什么？ `janus:webhooks:` 默认情况下。每个共享交付的流程都要经过同一条。 |

## Redis拥有什么？

每个交付的事件和端点id - **从来没有URL或秘密** ——与 [每个方法一个Lua脚本](https://npmcn.com/package/%40nxgt/janus-webhooks-redis/docs/guide/wiring.md#one-lua-script-per-method)， 所以没有两个索赔回应一个交付。 [布线](https://npmcn.com/package/%40nxgt/janus-webhooks-redis/docs/guide/wiring.md#what-redis-holds-and-for-how-long) 每个钥匙都有吗？ 它会停留多久。

## 陷阱

-   **保留新事件类型，直到共享队列的每个进程都完成 升级。** 交付 `user.secondFactorEnabled` 或者 `user.secondFactorDisabled`，由0.2.0编写，是 `STORE_FAILED` （`a reply that is not … a user event type`)。声明它的X进程-和 其中之一也是 `user.recoveryCodesRegenerated` 或者 `user.recoveryCodeUsed`， 由0.3.0编写，在0.2中。X进程，其中一个 `user.passwordChanged` 或者 `user.emailChanged`，由0.4.0编写，在0.3。X进程，其中一个 `user.newDeviceSignedIn`，由0.5.0编写，在0.4中。X进程，其中一个 `user.avatarChanged` 或者 `user.avatarRemoved`，由0.6.0编写，在0.5.x版本中 过程——还有 终结点索赔失败 直到每个流程都升级。升级 `@nxgt/janus`， `@nxgt/janus-webhooks` 和 `@nxgt/janus-webhooks-redis` 它们的对等范围作为一个整体移动，每个端点被限制为 这个 `types` 旧的进程知道，并删除限制每一次 进程运行新版本：
    
    ```ts
    webhooks({
      queue,
      endpoints: [{ id: 'crm', url, secrets: [secret], types: ['user.created', 'user.emailVerified', 'user.passwordReset', 'user.deleted'] }],
    });
    ```
    
    这个列表是针对0.1的。x的过程。当最老的跑0.2。X表示 第二个因素的事件，而不是恢复代码，加上这两个：
    
    ```ts
    types: ['user.created', 'user.emailVerified', 'user.passwordReset', 'user.secondFactorEnabled', 'user.secondFactorDisabled', 'user.deleted'],
    ```
    
    当最老的跑0.3。X，它读取恢复代码的事件，但不读取 变化事件，加上这两个
    
    ```ts
    types: ['user.created', 'user.emailVerified', 'user.passwordReset', 'user.secondFactorEnabled', 'user.secondFactorDisabled', 'user.recoveryCodesRegenerated', 'user.recoveryCodeUsed', 'user.deleted'],
    ```
    
    当最老的跑0.4。X，它读取变化事件，但不读取新事件 设备，加上这两个：
    
    ```ts
    types: ['user.created', 'user.emailVerified', 'user.passwordReset', 'user.passwordChanged', 'user.emailChanged', 'user.secondFactorEnabled', 'user.secondFactorDisabled', 'user.recoveryCodesRegenerated', 'user.recoveryCodeUsed', 'user.deleted'],
    ```
    
-   **驱逐是数据丢失。** Redis是谁？ `maxmemory-policy` 就清除键 一声不吭就把货丢了，不能再试，不能 `onGivingUp`． 在 复述,与 `noeviction`;一个满的则拒绝插入 `OOM`， 哪一个 `janus` 报告 `JANUS_EVENT_FAILED`.
    
-   **持久性使它持久。** 没有RDB或AOF，重新启动 Redis丢失了每一个在里面等待的货物。启用AOF (`appendfsync everysec` （在崩溃时最多损失一秒钟的插入）或RDB快照。
    
-   **不支持Redis集群。** 的键 交付及其端点，它们可能位于不同的槽中。使用一个 单个Redis，或者一个带有副本的主节点。
    
-   **默认情况下，中断会使每个流等待31秒。** 侦听器 等待插入，而Bun的客户机在重新连接时对命令进行排队。 与 `enableOfflineQueue: false` 插入立即失败，流停止 On，事件报告为 `JANUS_EVENT_FAILED`.
    
-   **每个应用程序一个前缀。** 两个应用程序共享一个前缀共享 ，并且每个人都放弃对方的端点作为 `endpointRemoved` 后 `orphanGrace`.
    

## 文档

-   [指南](https://npmcn.com/package/%40nxgt/janus-webhooks-redis/docs/README.md)：连接队列，前缀，Redis必须配置什么，Redis持有什么以及每个方法如何保持原子性
-   [故障排除](https://npmcn.com/package/%40nxgt/janus-webhooks-redis/docs/troubleshooting.md)：查看您看到的错误信息
-   [路线图](https://npmcn.com/package/%40nxgt/janus-webhooks-redis/docs/roadmap.md)下一步是什么，以及什么是没有计划的
-   [`@nxgt/janus-webhooks`排队指南](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus-webhooks/docs/guide/queues.md)：索赔，租约，孤儿，以及一个队列必须做什么

## 类型安全，计数

编译器拒绝了四个看似合理的错误，每个错误都带有 `@ts-expect-error` 在 `test/types/queue.ts`：

-   URL而不是连接；
-   Bun的客户端，而不是维系它的连接；
-   承诺 `connectRedis` 没有等待的答案；
-   一个 `prefix` 这不是字符串。

## 执照

麻省理工学院

## 常见问题

### @nxgt/janus-webhooks-redis 是什么？

@nxgt/janus-webhooks在@nxgt/ Redis上的Redis队列：超过进程的交付，在租约下自动声明

### 如何安装 @nxgt/janus-webhooks-redis？

在项目目录运行 npm install @nxgt/janus-webhooks-redis，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：typescript（^6\.0\.3 \|\| ^7\.0\.0）、@nxgt/janus（^0\.36\.0）、@nxgt/redis（\>=0\.3\.1 \<1）、@nxgt/janus-webhooks（^0\.8\.7）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @nxgt/janus-webhooks-redis 支持 TypeScript 吗？

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

### @nxgt/janus-webhooks-redis 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @nxgt/janus-webhooks-redis 可以商用吗？

@nxgt/janus-webhooks-redis 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @nxgt/janus-webhooks-redis 还在维护吗？

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