# @bossbench/core 中文文档

规范地址：https://npmcn.com/package/%40bossbench/core/

版本：1\.1\.1
npm 元数据更新时间：2026-08-12T09:57:39.454Z
中文译文更新时间：2026-11-08T11:57:31.455Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40bossbench/core
原文对照：https://npmcn.com/package/%40bossbench/core/?lang=original
项目主页：https://github.com/nip10/bossbench/tree/main/packages/core#readme
源码仓库：https://github.com/nip10/bossbench

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

- 包体积（解压后）：1.2 MB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：6 个
- peer 依赖：pg \>=8\.0\.0，pg-boss \>=12\.0\.0
- 首次发布：2026-08-10T17:13:48.900Z
- 最新版本发布：2026-08-12T09:57:39.136Z
- 近 30 天下载量：2341（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

核心API,寄存器,动作,并捆绑了Bossbench的UI.

## 安装

```sh
npm install @bossbench/core
```

也可以使用：`pnpm add @bossbench/core`、`yarn add @bossbench/core`、`bun add @bossbench/core`

## README

# @ bossbench/ core (中文(简体) )

Bossbench的核心软件包. 它包含pg-boss/Postgres寄存器,动作服务,API路由,并捆绑了仪表盘UI.

## 适应器矩阵

| 软件包 | 框架 | 挂载样式 |
| --- | --- | --- |
| `@bossbench/hono` | 浩诺 | `app.route()` |
| `@bossbench/h3` | h3 / 硝基 | 处理器包装器 |
| `@bossbench/nuxt` | 纳克特/ 硝基 | 路由模块 |
| `@bossbench/adonis` | 阿多尼斯·贾克 | 路由器挂载 |
| `@bossbench/tanstack-start` | TanStack 启动 | 路由处理器 |
| `@bossbench/express` | 快递 | `app.use()` |
| `@bossbench/fastify` | 快捷化 | 插件 |
| `@bossbench/elysia` | 爱莉西亚 | 插件 |
| `@bossbench/nestjs` | 网点JS | 控制器/模块 |
| `@bossbench/next` | 下一个.js | 路由处理器 |

## CLI 设置

```bash
npx @bossbench/cli init
```

CLI探测到Hono,h3,Nuxt/Nitro,AdonisJS,TanStack Start,Express,Fastify,Elysia,NestJS,和Next.js等项目.

## 核心 API

```ts
import PgBoss from "pg-boss";
import { Hono } from "hono";
import { bossbench } from "@bossbench/hono";

const boss = new PgBoss({ connectionString: process.env.DATABASE_URL!, schema: "pgboss" });
await boss.start();

const app = new Hono();
app.route(
  "/jobs",
  bossbench({
    boss,
    db: process.env.DATABASE_URL!,
    basePath: "/jobs",
    auth: {
      username: process.env.BOSSBENCH_USER!,
      password: process.env.BOSSBENCH_PASS!,
    },
  }),
);
```

## 选项

| 选项 | 说明 |
| --- | --- |
| `boss` | 可选 `PgBoss` 举个例子 突变需要. |
| `db` | Postgres 连接字符串, `Pool`,或 `Client`。需要读取,除非适配器通过兼容的连接. |
| `schema` | pg-boss schema. (原始内容存档于2018-09-30). 默认为 `pgboss`。 。 。 . |
| `auth` | 基本认证证书。 要求,除非 `allowUnauthenticated: true`。 。 。 . |
| `allowUnauthenticated` | 明确允许无防护浏览. 默认为 `false`。 。 。 . |
| `readonly` | 禁用所有突变 。 默认为 `true` 没有认证, `false` 与授权. |
| `allowManualEnqueue` | 启用手动排队和排队复制动作 。 默认为 `false`。 。 。 . |
| `allowQueueClean` | 只启用队列干净预览 。 要求数 `boss`,可写模式,和路由保护。 默认为 `false`。 。 。 . |
| `allowQueueCleanDelete` | 启用不可逆的队列清洁删除 。 需要精确确认,直接SQL安全,以及线路保护. 默认为 `false`。 。 。 . |
| `alerts` | 可选配置驱动的警戒规则和联络点. 评价是只读的;交付选手是选入的. |
| `tags` | 字段从 `job.data` 可用作过滤器. |

## 警报

警告配置在 `BossbenchOptions`,从 pg-boss / Postgres 数据进行评估,然后通过捆绑的提醒页面再浮出水面 `/api/alerts`。 。 。 .

```ts
bossbench({
  db: process.env.DATABASE_URL!,
  auth: {
    username: process.env.BOSSBENCH_USER!,
    password: process.env.BOSSBENCH_PASS!,
  },
  alerts: {
    enabled: true,
    rules: [
      {
        id: "critical-failures",
        name: "Critical failures",
        type: "failed_count",
        windowMinutes: 10,
        threshold: 5,
        severity: "critical",
        cooldownMinutes: 30,
        contactPointIds: ["ops"],
      },
    ],
    contactPoints: [
      { id: "ops", name: "Ops", type: "discord", urlEnv: "OPS_DISCORD_WEBHOOK" },
    ],
  },
});
```

规则支助 `failed_count`, (中文(简体) ), `dead_letter_count`, (中文(简体) ), `retry_backlog_count`, (中文(简体) ), `oldest_created_age`, (中文(简体) ), `avg_wait_ms`, (中文(简体) ), `avg_duration_ms`,以及 `warning_count`。 。 。 . `oldest_created_age` 阈值为秒;等和持续阈值为毫秒. 联络点可以是: `webhook`, (中文(简体) ), `slack`,或 `discord`. 偏爱 `urlEnv` 或仅用于 Webhook URL 的服务器配置;仪表板只接收蒙面的联络点摘要.

`AlertRunner` 用于服务器侧发送。 它不自动启动定时器; 调用 `runOnce()` 从一个进程或你自己的调度器。 在复制部署中,操作一个单一的警报员,或在交付前增加部署级别的锁定.

## 警卫

Bossbench 需要非空闲 `auth` 默认。 使用 `allowUnauthenticated: true` 仅用于本地开发或当另一个中间软件保护路径时。 无 `auth`,Bossbench默认只读模式.

队列清空被分割为预览并删除 . `allowQueueClean` 启用预览,以及 `allowQueueCleanDelete` 只有当预览也被允许时,才允许不可逆转地删除。 删除运行前需要精确确认文本 。 排队清除目标 pg-boss 直接存储,所以失败的删除可以去除基本的死信/重写证据. 批量限制; 重复同时 `hasMore` 排出大排队时是真实的.

## 常见问题

### @bossbench/core 是什么？

核心API,寄存器,动作,并捆绑了Bossbench的UI\.

### 如何安装 @bossbench/core？

在项目目录运行 npm install @bossbench/core，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：pg（\>=8\.0\.0）、pg-boss（\>=12\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @bossbench/core 支持 TypeScript 吗？

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

### @bossbench/core 支持 ESM 还是 CommonJS？

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

### @bossbench/core 可以商用吗？

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

### @bossbench/core 的下载量有多少？

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

### @bossbench/core 还在维护吗？

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