# bpmn-server 中文文档

规范地址：https://npmcn.com/package/bpmn-server/

版本：3\.5\.1
npm 元数据更新时间：2026-11-03T03:03:55.171Z
中文译文更新时间：2026-11-03T06:55:54.109Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.8 MB，358 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：11 个
- 首次发布：2020-06-03T21:31:15.655Z
- 最新版本发布：2026-11-03T03:03:55.013Z
- 已发布版本数：114（近 12 个月 9 个）

## 中文简介

BPMN 2.0服务器，包括建模、执行和持久化，一个开源的Node.js

## 安装

```sh
npm install bpmn-server
```

也可以使用：`pnpm add bpmn-server`、`yarn add bpmn-server`、`bun add bpmn-server`

## README

# 概述回家

`bpmn-server` 是一个基于bpmn的工作流引擎，可以很容易地集成到你的Node.js应用程序中。它支持内置的状态持久性、变量管理和跨集群的并发性——非常适合长时间运行的流程、持久服务和计划任务。

## 体系结构概述

的核心组件 `bpmn-server` 以及它们如何相互作用：

![Architecture Diagram](https://bpmnserver.github.io/docs/images/architecture-diagram.png)

-   **Modeler**：使用BPMN .io设计BPMN模型的前端UI。
-   **bpmn-server核心**：执行BPMN工作流、管理状态以及与外部服务的接口。
-   **数据存储**：保存工作流状态、变量和历史记录（默认为MongoDB）。
-   **应用程序层**你的Node.js应用程序与服务器集成，处理用户身份验证，并调用工作流。

## 快速入门

### 使用演示项目

```sh
# 1. Clone the demo app
$ git clone https://github.com/bpmnServer/bpmn-web.git
$ cd bpmn-web

# 2. Install dependencies
$ npm install

# 3. Run setup to create default install files
$ npm run setup

# 4. Edit `.env` file.

# 5. Run setup to create database and models
$ npm run setup

# 6. Start the server
$ npm run start
```

打开浏览器至 [http://localhost:3000](http://localhost:3000/) 启动演示。

### 编程使用示例

```js
const { BPMNServer, DefaultAppDelegate } = require('bpmn-server');
const { configuration } = require('./configuration');

const server = new BPMNServer(configuration, new DefaultAppDelegate());

const processName = 'invoice';
const inputData = { amount: 1200 };

(async () => {
    const result = await server.engine.start(processName, inputData);
    console.log('Process started with instance id:', result.instance.id);
})();
```

有关更高级的示例，请参阅 [API文档](https://bpmnserver.github.io/docs/api).

* * *

## 建模

`bpmn-server` 提供基于的建模工具 `bpmn.io` 使用自定义属性面板，消除了手动编辑BPMN文件的需要。

![](https://bpmnserver.github.io/docs/images/Modeler.png)

你也可以从其他工具导入BPMN模型。

每个模型都在BPMN XML文件中定义，并由各种元素组成。一个 `element` 可以是 `node` （如事件、任务或网关）或 `flow`.

模型由以下人员管理 `bpmn-server` ，可以查询 [模型API](https://bpmnserver.github.io/docs/api/interfaces/IAPIModel).

支持所有BPMN 2.0元素。 [参见建模支持](https://bpmnserver.github.io/docs/examples)

## 执行

`bpmn-server` 主要是BPMN模型的执行引擎。

每次启动一个模型时 `instance` 被创建。对于每一个 `element` 这被执行了 `item` 是生成的。

执行遵循BPMN模型逻辑，并支持脚本和应用程序上下文访问等扩展。

在执行期间，模型侦听器和应用程序侦听器都将被调用。

控件访问执行引擎 [引擎API](https://bpmnserver.github.io/docs/api/interfaces/IAPIEngine).

-   [调用执行引擎](https://bpmnserver.github.io/docs/invokation)
-   [执行行为](https://bpmnserver.github.io/docs/execution)

## 数据存储

执行数据，包括实例及其元素，被持久化到数据存储（默认情况下是MongoDB）。

您可以通过 [Data API](https://bpmnserver.github.io/docs/api/interfaces/IAPIData).

-   [数据管理文档](https://bpmnserver.github.io/docs/data)

## 用户管理与安全

`bpmn-server` 将身份验证委托给前端应用程序，前端应用程序必须通过API传递用户信息。

1.  模型设计者可以定义 `assignee`， `candidateUsers`, `candidateUserGroups` 使用静态字符串或JavaScript表达式。
2.  前端必须提供 `userService` 实现。
3.  `bpmn-server` 基于当前用户强制执行安全规则。

这个 `bpmn-web` 演示应用程序演示了使用Passport和MongoDB的完整用户管理。

-   [安全文档](https://bpmnserver.github.io/docs/security)

## 演示Web应用程序

探索“bpmn-web”演示应用程序。

功能包括:

-   持久建模工具(基于 `bpmn.io`）
-   支持所有属性面板 `bpmn-server` 特性
-   使用已定义字段的输入表单执行

![](https://bpmnserver.github.io/docs/images/inputFields.png)

-   任务和工作流列表
-   实例详细信息视图

![](https://bpmnserver.github.io/docs//images/instance-details1.png)

-   模型规格查看器

![](https://bpmnserver.github.io/docs//images/instance-details2.png)

## 现场演示

现场演示可在以下网址下载： [https://bpmn.omniworkflow.com](https://bpmn.omniworkflow.com/)

## 安装

这个包需要Node.js和MongoDB。

如果未安装MongoDB，则可以 [创建一个免费的云帐户](http://bit.ly/cyd-atlas) 或者 [在本地安装](https://www.mongodb.com/docs/manual/installation/).

### 1\. 克隆存储库

```sh
git clone https://github.com/bpmnServer/bpmn-web.git
```

### 2\. 安装依赖关系

```sh
npm install
```

### 3\. 设置应用程序

```sh
npm run setup
```

编辑 `.env` 配置MongoDB：

```env
MONGO_DB_URL=mongodb://0.0.0.0:27017/bpmn
```

再次运行setup创建DB对象：

```sh
npm run setup
```

### 4\. 启动服务器

```sh
npm run start
```

控制台输出:

```text
bpmn-server WebApp.ts version 1.4.0
MongoDB URL mongodb://0.0.0.0:27017/bpmn
db connection open
App is running at http://localhost:3000 in development mode
Press CTRL-C to stop
```

## 码头工人安装

用Docker安装‘ bpmn-server ’和依赖项。

### 1\. 创建一个项目文件夹

### 2\. 添加一个 `docker-compose.yml` 文件:

```yaml
version: "3.7"
name: bpmn-server
services:
  bpmn-web:
    image: ralphhanna/bpmn-web
    command: sh -c "
        npm run setup &&
        npm run start"
    ports:
      - 3000:3000
    volumes:
      - 'app:/app'
    depends_on:
      - mongo

  mongo:
    image: mongo
    ports:
      - 27017:27017
    volumes:
      - mongodb:/data/db

volumes:
  mongodb:
    driver: local
    driver_opts:
      type: 'none'
      o: 'bind'
      device: './mongodb_volume'

  app:
    driver: local
    driver_opts:
      type: 'none'
      o: 'bind'
      device: './bpmn_server_volume'
```

### 3\. 启动容器

```sh
docker compose up -d
```

## 命令行接口

通过CLI使用‘ bpmn-server ’进行常见操作。

```sh
npm run cli

server started..
Commands:
  q     quit
  s     start process
  lo    list outstanding items
  li    list items
  l     list instances for a process
  di    display instance information
  i     invoke task
  sgl   signal task
  msg   message task
  d     delete instances
  lm    list models
  lme   list model elements
  ck    check locked instances
  re    recover hung processes
  lu    list users
  spw   set user password
  ?     show this help menu
```

## 更新到最新版本

```sh
npm update bpmn-server
```

## 应用程序集成

`bpmn-server` 被设计为嵌入到应用程序中。 [参见定制指南](https://bpmnserver.github.io/docs/customization)

## 文档

-   [调用工作流](https://bpmnserver.github.io/docs/invokation)
-   [执行](https://bpmnserver.github.io/docs/execution)
-   [脚本](https://bpmnserver.github.io/docs/scripting)
-   [安全](https://bpmnserver.github.io/docs/security)
-   [数据](https://bpmnserver.github.io/docs/data)
    -   [输入/输出](https://bpmnserver.github.io/docs/data#input-output-data)
    -   [数据查询](https://bpmnserver.github.io/docs/data#dataQuery)
-   [示例](https://bpmnserver.github.io/docs/examples)
-   [API的总结](https://bpmnserver.github.io/docs/api-summary)
-   [API参考](https://bpmnserver.github.io/docs/api)
-   [设置](https://bpmnserver.github.io/docs/setup)
-   [应用程序集成](https://bpmnserver.github.io/docs/customization)

## 许可证

在麻省理工学院许可下许可。

## 致谢

`bpmn-server` 构建在 [bpmn-io / bpmn-moddle](https://github.com/bpmn-io/bpmn-moddle) 由 [bpmn.io](http://bpmn.io/)，并受到……的启发 [bpmn-engine](https://github.com/paed01/bpmn-engine).

## 常见问题

### bpmn-server 是什么？

BPMN 2\.0服务器，包括建模、执行和持久化，一个开源的Node\.js

### 如何安装 bpmn-server？

在项目目录运行 npm install bpmn-server，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 bpmn-server，可以用 npx bpmn-server 直接运行。

### bpmn-server 支持 TypeScript 吗？

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

### bpmn-server 支持 ESM 还是 CommonJS？

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

### bpmn-server 需要什么版本的 Node\.js？

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

### bpmn-server 可以商用吗？

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

### bpmn-server 还在维护吗？

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