# @camunda/session-heartbeat 中文文档

规范地址：https://npmcn.com/package/%40camunda/session-heartbeat/

版本：0\.0\.1
npm 元数据更新时间：2026-10-30T15:26:10.532Z
中文译文更新时间：2026-11-09T00:52:27.144Z
软件包许可：LicenseRef-Camunda-1\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40camunda/session-heartbeat
原文对照：https://npmcn.com/package/%40camunda/session-heartbeat/?lang=original
项目主页：https://github.com/camunda/camunda#readme
源码仓库：https://github.com/camunda/camunda

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

- 包体积（解压后）：12.7 kB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2026-08-13T21:54:16.623Z
- 最新版本发布：2026-08-13T21:54:17.018Z
- 近 30 天下载量：7525（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 1 个）

## 中文简介

Camunda 安全库支持的 Camunda 网络应用程序的活动驱动会话心跳

## 安装

```sh
npm install @camunda/session-heartbeat
```

也可以使用：`pnpm add @camunda/session-heartbeat`、`yarn add @camunda/session-heartbeat`、`bun add @camunda/session-heartbeat`

## README

# @camunda/session-心脏跳动

活动驱动的 Camunda 网络应用程序的会话心跳,其会话由会议管理 [Camunda 安全图书馆](https://github.com/camunda/camunda-security-library) (中文(简体) ).

软件包跟踪真正的浏览器活动——指针、键盘、轮子、卷轴和标签 重新获得知名度——并称CSL's `POST {basePath}/session/heartbeat` 终止点最多一次 间隔,只有在活动实际发生时。 它的存在如此操作、任务列表、优化和任何 未来采纳者共享一个执行,而不是每个重新实施同一个倾听者 节奏逻辑.

背景情况: [CDR-0042 — 客户端活动驱动的可配置会话闲置超时](https://github.com/camunda/camunda-security-library/blob/main/docs/adr/0042-configurable-activity-driven-session-idle-timeout.md)。 。 。 .

## 为什么需要心跳

与 `camunda.security.session.heartbeat.enabled=true`, CSL 停止处理普通后端流量 作为用户存在的证据 : **仅限** 对心跳终点的呼叫延长了会话。 一个东道主 启用旗子时, 前端不会发送心跳, 之后会记录其用户 `camunda.security.session.max-inactive-interval`然而,它们正在积极地使用该应用程序.

旗帜默认为 `false`,所以采用这个包是安全的和惰性的,直到一个主机打开.

## 安装

```bash
npm install @camunda/session-heartbeat
```

`react` 是一个可选的同伴依赖关系,仅用于 `./react` 进入点.

## 使用量

### 反应

```tsx
import {useSessionHeartbeat} from '@camunda/session-heartbeat/react';

function AuthenticatedLayout() {
    useSessionHeartbeat({
        url: '/session/heartbeat',
        csrfToken: () => sessionStorage.getItem('X-CSRF-TOKEN'),
        onUnauthorized: () => {
            authenticationStore.disableSession();
        },
    });

    return <Outlet />;
}
```

在应用程序的认证部分内调用一次, 所以在登录后心跳开始 当用户离开时停止。 回拨和 `csrfToken` 每一个心跳都有新鲜读取,所以 inline 函数不重新启动计时器; 更改 `url`, (中文(简体) ), `intervalMs`,或 `enabled` 已经.

### 没有反应

```ts
import {createSessionHeartbeat} from '@camunda/session-heartbeat';

const stopSessionHeartbeat = createSessionHeartbeat({url: '/session/heartbeat'});

// on teardown
stopSessionHeartbeat();
```

## 选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `url` | `string` | —— 说 | 心跳终点 一定是当前瞄准镜的 `{basePath}/session/heartbeat`,包含上下文路径. |
| `intervalMs` | `number` | `60000` | 活动被检查的频率,因此是两个心跳间最短的间隔. |
| `csrfToken` | `string | null | undefined | (() => …)` | `undefined` | CSRF的标志,或者一个得到它。 发送为 `X-CSRF-TOKEN`; 缺席或空时省略. |
| `onUnauthorized` | `() => void` | `undefined` | 当心跳回来时打电话 `401` 过期的会话,或缺失/出售的CSRF标志. |
| `onError` | `(failure: SessionHeartbeatFailure) => void` | `undefined` | 调用网络错误和任何其他非OK响应. |
| `enabled` | `boolean` (单位:千美元)`./react` 仅限) | `true` | 设定 `false` 使钩子挂起而不发出心跳. |

### 选择 `intervalMs`

保持它的好在东道主的 `camunda.security.session.max-inactive-interval` 一个心跳是什么 重新设置该时钟, 并且一个失败的请求不能花费用户的会话 。 四分之一的面积 配置间隔或小于是拇指的好规则 `60s` 默认的 CSL 套装 `30m` 默认.

## 值得了解的行为

-   **终点需要CSRF的标志.** 只有 SSL 豁免 `/login` 财务报告和审定财务报表 `/logout` \* 免于保护公司社会责任基金, 故有会相 `POST /session/heartbeat` 无效 `X-CSRF-TOKEN` 被拒绝——与 `401`没有 `403`,因为Webapp链将CSRF的拒绝映射到其认证失败的处理器上. 过 `csrfToken` 从应用程序保存的地方.
-   **A 类 `401` 因此表示"这个心跳未被接受",而不是严格意义上的"会话已去".** 缺少或陈旧的符号产生与过期会话相同的状态,所以 `onUnauthorized` 火灾 在这两种情况下。 这符合Webapp自己的请求层通常如何处理 `401`; 如果为 应用需要将两者区分开来,反应机体携带一个CSRF专用 `detail`。 。 。 .
-   **开始计数为活动**因此,第一个间隔总是发出一个心跳。 这个表面 立即断线, 代价是将废弃的会话延长一个间隔 .
-   **每个间隔最多一个心跳**,而没有任何时间间隔没有活动。 A 类 心跳也跳过 当前一个还在飞行.
-   **A 类 `401` 不停止心跳.** 消费者决定过期会议的含义; 卸载钩子( 或设置) `enabled: false`)是何为止.
-   **每个分页的心跳都是独立的.** 他们共享一个会话,所以费用是额外要求 ;没有交叉协调.
-   **申请须经过认证** (单位:千美元)`credentials: 'include'`),并因被撕毁而中止.

## 发展

```bash
npm run build -w @camunda/session-heartbeat        # bundle + type declarations
npm run typecheck -w @camunda/session-heartbeat
npm run test:unit -w @camunda/session-heartbeat    # Vitest browser mode
```

见 [会话心跳](https://npmcn.com/docs/monorepo-docs/frontend/session-heartbeat.md) 输入 用于采用清单和出版步骤的单列文件.

## 常见问题

### @camunda/session-heartbeat 是什么？

Camunda 安全库支持的 Camunda 网络应用程序的活动驱动会话心跳

### 如何安装 @camunda/session-heartbeat？

在项目目录运行 npm install @camunda/session-heartbeat，或使用 pnpm add / yarn add / bun add。

### @camunda/session-heartbeat 支持 TypeScript 吗？

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

### @camunda/session-heartbeat 支持 ESM 还是 CommonJS？

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

### @camunda/session-heartbeat 可以商用吗？

@camunda/session-heartbeat 使用 LicenseRef-Camunda-1\.0 许可。声明的许可为 LicenseRef-Camunda-1\.0，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @camunda/session-heartbeat 的下载量有多少？

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

### @camunda/session-heartbeat 还在维护吗？

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