# @agendajs/mongo-backend 中文文档

规范地址：https://npmcn.com/package/%40agendajs/mongo-backend/

版本：4\.0\.4
npm 元数据更新时间：2026-10-31T12:57:43.767Z
中文译文更新时间：2026-11-05T18:11:46.184Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：119 kB，27 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：1 个
- peer 依赖：agenda 6\.2\.7，mongodb ^6\.0\.0 \|\| ^7\.0\.0
- 首次发布：2026-01-26T15:53:55.856Z
- 最新版本发布：2026-10-31T12:57:43.450Z
- 近 30 天下载量：99535（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

议程任务调度器 MongoDB 后端

## 安装

```sh
npm install @agendajs/mongo-backend
```

也可以使用：`pnpm add @agendajs/mongo-backend`、`yarn add @agendajs/mongo-backend`、`bun add @agendajs/mongo-backend`

## README

# @ agendajs/mongo-后端

MongoDB 的后端 [议程项目](https://www.npmjs.com/package/agenda) 工作调度员.

## 安装

```bash
npm install agenda @agendajs/mongo-backend
# or
pnpm add agenda @agendajs/mongo-backend
# or
yarn add agenda @agendajs/mongo-backend
```

**所需经费:**

-   节点.js 18+
-   蒙戈DB 4+ 导弹

## 使用量

```typescript
import { Agenda } from 'agenda';
import { MongoBackend } from '@agendajs/mongo-backend';

// Via connection string
const agenda = new Agenda({
  backend: new MongoBackend({
    address: 'mongodb://localhost/agenda'
  })
});

// Or via existing MongoDB connection
import { MongoClient } from 'mongodb';

const client = await MongoClient.connect('mongodb://localhost');
const db = client.db('agenda');

const agenda = new Agenda({
  backend: new MongoBackend({ mongo: db })
});

// Define jobs
agenda.define('send-email', async (job) => {
  const { to, subject } = job.attrs.data;
  await sendEmail(to, subject);
});

// Start processing
await agenda.start();

// Schedule jobs
await agenda.every('1 hour', 'send-email', { to: 'user@example.com', subject: 'Hello' });
```

## 配置选项

```typescript
interface IMongoBackendConfig {
  /** MongoDB connection string */
  address?: string;

  /** Existing MongoDB database instance */
  mongo?: Db;

  /** Collection name for jobs (default: 'agendaJobs') */
  collection?: string;

  /** MongoDB client options */
  options?: MongoClientOptions;

  /** Name to identify this Agenda instance (stored as lastModifiedBy) */
  name?: string;

  /** Whether to create indexes on connect (default: true) */
  ensureIndex?: boolean;

  /** Sort order for job queries */
  sort?: { [key: string]: SortDirection };
}
```

### 带选项的完整示例

```typescript
const agenda = new Agenda({
  backend: new MongoBackend({
    address: 'mongodb://localhost/agenda',
    collection: 'jobs',           // Custom collection name
    sort: { nextRunAt: 'asc', priority: 'desc' }
  }),
  processEvery: '30 seconds',     // Job polling interval
  maxConcurrency: 20,             // Max concurrent jobs
  defaultConcurrency: 5           // Default per job type
});
```

## 实时通知

MongoBackend只提供存储,并使用投票来检查新的工作. 对于跨分布式系统的实时工作处理,您有几种选择:

### 备选案文1:MongoDB变化流(国内)

如果您的 MongoDB 部署是复制件集( 甚至单节点复制件集) , 您可以使用 `MongoChangeStreamNotificationChannel` 本地实时通知中没有任何外部依赖性:

```typescript
import { Agenda } from 'agenda';
import { MongoBackend, MongoChangeStreamNotificationChannel } from '@agendajs/mongo-backend';

const agenda = new Agenda({
  backend: new MongoBackend({ mongo: db }),
  notificationChannel: new MongoChangeStreamNotificationChannel({ db })
});

// Jobs are processed immediately when created (no polling delay)
await agenda.start();
await agenda.now('myJob'); // Triggers instant processing
```

**所需经费:**

-   MongoDB 复制套件(单节点复制套件工作精细)
-   有线老虎存储引擎(自MongoDB 3.2起默认)

**配置选项 :**

```typescript
const channel = new MongoChangeStreamNotificationChannel({
  db: mongoDb,                    // Required: MongoDB database instance
  collection: 'agendaJobs',       // Optional: collection name (default: 'agendaJobs')
  resumeToken: savedToken,        // Optional: resume from specific point
  fullDocument: true              // Optional: include full document on updates (default: true)
});
```

### 备选案文2:记忆(单一进程)

```typescript
import { Agenda, InMemoryNotificationChannel } from 'agenda';
import { MongoBackend } from '@agendajs/mongo-backend';

// For single-process apps (testing/development)
const agenda = new Agenda({
  backend: new MongoBackend({ mongo: db }),
  notificationChannel: new InMemoryNotificationChannel()
});
```

### 备选案文3:Redis Pub/Sub(多程序)

```typescript
import { Agenda } from 'agenda';
import { MongoBackend } from '@agendajs/mongo-backend';
import { RedisBackend } from '@agendajs/redis-backend';

// For production: use Redis for notifications
const redisBackend = new RedisBackend({ connectionString: 'redis://localhost:6379' });
const agenda = new Agenda({
  backend: new MongoBackend({ mongo: db }),
  notificationChannel: redisBackend.notificationChannel
});
```

## 数据库索引

默认情况下, MongoBackend 自动创建 `findAndLockNextJobIndex` 用于优化任务查询性能的连接索引。 该指数包括:

```javascript
{
  "name": 1,
  "nextRunAt": 1,
  "priority": -1,
  "lockedAt": 1,
  "disabled": 1
}
```

要禁用自动索引创建( 例如, 如果您单独管理索引 ) :

```typescript
const backend = new MongoBackend({
  mongo: db,
  ensureIndex: false  // Skip automatic index creation
});
```

### 附加索引

如果您使用 **议程项目sh**中,添加此索引,用于更好的仪表板性能:

```javascript
db.agendaJobs.createIndex({
  "nextRunAt": -1,
  "lastRunAt": -1,
  "lastFinishedAt": -1
}, { name: "agendash" })
```

如果您有上千个实例的工作定义, 此索引可以改进锁定查询 :

```javascript
db.agendaJobs.createIndex({
  "name": 1,
  "disabled": 1,
  "lockedAt": 1
}, { name: "findAndLockDeadJobs" })
```

## 任务日志

MongoBackend 包含内置 `MongoJobLogger` 将结构化的工作生命周期活动储存在专门的MongoDB收藏中(`agenda_logs` (默认情况下). 伐木机是轻量级的,并且只在第一次使用时创建它的收藏.

### 自动使用

当您在议事日程中启用日志时, 后端的内置登录器会被自动使用 :

```typescript
const agenda = new Agenda({
  backend: new MongoBackend({ mongo: db }),
  logging: true  // Uses MongoJobLogger automatically
});
```

### 独立使用

您还可以使用 `MongoJobLogger` 独立 – 例如, 在使用不同的后端存储时登录到 MongoDB :

```typescript
import { MongoJobLogger } from '@agendajs/mongo-backend';

const logger = new MongoJobLogger({
  mongo: db,                        // Required: MongoDB database instance
  logCollection: 'agenda_logs'      // Optional: collection name (default: 'agenda_logs')
});

// Use with any backend
import { RedisBackend } from '@agendajs/redis-backend';
const agenda = new Agenda({
  backend: new RedisBackend({ connectionString: 'redis://...' }),
  logging: logger
});
```

### 查询日志

```typescript
const { entries, total } = await agenda.getLogs({
  jobName: 'send-email',
  level: 'error',
  limit: 50,
  sort: 'desc'
});

// Clear old logs
await agenda.clearLogs({ to: new Date(Date.now() - 30 * 86400000) });
```

见 [议程项目研究](https://github.com/agenda/agenda#persistent-job-logging) 用于完整记录文件.

## 相关软件包

-   [议程](https://www.npmjs.com/package/agenda) - 核心排程器
-   [@ agendajs/postgres-后端](https://www.npmjs.com/package/@agendajs/postgres-backend) - PostgreSQL 后端,配有Listen/NOTIFY
-   [@ agendajs/ redis-后端](https://www.npmjs.com/package/@agendajs/redis-backend) - 与 Pub/ Sub 重接后端

## 许可证

麻省理工学院

## 常见问题

### @agendajs/mongo-backend 是什么？

议程任务调度器 MongoDB 后端

### 如何安装 @agendajs/mongo-backend？

在项目目录运行 npm install @agendajs/mongo-backend，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：agenda（6\.2\.7）、mongodb（^6\.0\.0 \|\| ^7\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @agendajs/mongo-backend 支持 TypeScript 吗？

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

### @agendajs/mongo-backend 支持 ESM 还是 CommonJS？

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

### @agendajs/mongo-backend 需要什么版本的 Node\.js？

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

### @agendajs/mongo-backend 可以商用吗？

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

### @agendajs/mongo-backend 的下载量有多少？

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

### @agendajs/mongo-backend 还在维护吗？

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