# @forestadmin/workflow-executor 中文文档

规范地址：https://npmcn.com/package/%40forestadmin/workflow-executor/

版本：1\.37\.0
npm 元数据更新时间：2026-11-13T15:47:25.863Z
中文译文更新时间：2026-11-15T07:16:19.738Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40forestadmin/workflow-executor
原文对照：https://npmcn.com/package/%40forestadmin/workflow-executor/?lang=original
项目主页：https://github.com/ForestAdmin/agent-nodejs#readme
源码仓库：https://github.com/ForestAdmin/agent-nodejs

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

- 包体积（解压后）：1.3 MB，187 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12\.0
- 运行依赖：15 个
- 首次发布：2026-06-09T12:26:40.858Z
- 最新版本发布：2026-11-13T15:47:25.465Z
- 近 30 天下载量：140946（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：99（近 12 个月 99 个）

## 中文简介

在自己的基础设施上运行森林管理流程步骤.

## 安装

```sh
npm install @forestadmin/workflow-executor
```

也可以使用：`pnpm add @forestadmin/workflow-executor`、`yarn add @forestadmin/workflow-executor`、`bun add @forestadmin/workflow-executor`

## README

# @ forestadmin/ workflow- executor

在自己的基础设施上运行森林管理流程步骤.

执行人投票 森林管弦乐手 等待步骤,管理地方 (通过森林特工获取你的数据),报告结果。 没有 客户端数据永远离开你的基础设施.

## 先决条件

请确定您在最新版本的森林管理代理(Node.js/JS或Ruby)上,然后将您的代理指向执行者 `workflowExecutorUrl`数字 :

```js
createAgent({
  // ...
  workflowExecutorUrl: process.env.WORKFLOW_EXECUTOR_URL, // e.g. http://localhost:3400
})
```

这是 **所需经费** 执行者工作的时间: `workflowExecutorUrl` 设置,代理将转发工作流程请求的路由挂载到执行器(并将 JWT 转发给 auth) 。 如果未设定, 代理返回 `404` 在那些路线上,执行者从未收到任何工作.

从一个环境变量驱动它(`WORKFLOW_EXECUTOR_URL` 因此,每次部署都可以针对自己的执行者。 URL 是代理到达执行器—— 其 HTTP 服务器( 默认端口) 的地方 `3400`) (中文(简体) ). 当代理和执行器运行在私有网络(如内部负载平衡器)后的独立主机上时,使用执行器的内部地址,并确保代理能够到达执行器的HTTP端口.

* * *

## 多克( 建议)

图像发布为 `ghcr.io/forestadmin/runtime`。它以前的名称 `ghcr.io/forestadmin/workflow-executor`,它仍然从准确的 同一建筑物——现有部署继续运作,但新部署应使用 `runtime`。 。 。 .

### 快开始

```bash
cp .env.example .env   # fill in your secrets
docker compose up
```

这个 `docker-compose.yml` 在此软件包根部开始一个单一的执行实例。 见 `.env.example` 用于完整环境变量清单及其描述.

### 直接运行

```bash
docker run -d \
  -e FOREST_ENV_SECRET="your-env-secret" \
  -e FOREST_AUTH_SECRET="your-auth-secret" \
  -e AGENT_URL="http://host.docker.internal:3351" \
  -e DATABASE_URL="postgres://user:pass@host.docker.internal:5432/mydb" \
  -p 3400:3400 \
  ghcr.io/forestadmin/runtime:latest
```

> **说明:** 当执行器在 Docker 运行时, 您的代理机在主机运行时, 请使用 `host.docker.internal` 改为 `localhost` 内 `AGENT_URL` 财务报告和审定财务报表 `DATABASE_URL`。 。 。 .

### 观测( 开放的遥测)

与 Docker 图像船 [打开几何](https://opentelemetry.io/) APM建入并使用任何OTLP相容后端(Datadog, Grafana Tempo, Jaeger, Honeycomb等). 没错 **默认关闭** 并自动打开,当您将其指向OTLP接收器时——不需要更改代码或额外安装。 在应用程序启动前就设置了追踪(HTTP,Postgres等的自动仪器),而缓冲跨度被冲出优雅的关闭.

完全通过标准OTel环境变量配置 :

| 变量 | 说明 |
| --- | --- |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP接收器URL(例如:. `http://collector:4318`) (中文(简体) ). **追踪被禁用, 直至设定 .** |
| `OTEL_SERVICE_NAME` | 服务名有痕迹 默认 : `forestadmin-workflow-executor`。 。 。 . |
| `OTEL_RESOURCE_ATTRIBUTES` | 额外的资源属性,例如:. `deployment.environment=production,version=1.7.0`。 。 。 . |
| `OTEL_SDK_DISABLED` | 设定为 `true` 以强制无法追踪,即使配置了终点. |

```bash
docker run -d \
  -e FOREST_ENV_SECRET="your-env-secret" \
  -e FOREST_AUTH_SECRET="your-auth-secret" \
  -e AGENT_URL="http://host.docker.internal:3351" \
  -e DATABASE_URL="postgres://user:pass@host.docker.internal:5432/mydb" \
  -e OTEL_EXPORTER_OTLP_ENDPOINT="http://collector:4318" \
  -p 3400:3400 \
  ghcr.io/forestadmin/runtime:latest
```

> **说明:** OpenTeleometry只在多克图像中捆绑. 它不是用 npm 套件运出(`npx @forestadmin/workflow-executor`) (中文(简体) ).

* * *

## 没有多克

### 有数据库

需要22.12.0节点和Postgres数据库:

```bash
FOREST_ENV_SECRET="your-env-secret" \
FOREST_AUTH_SECRET="your-auth-secret" \
AGENT_URL="https://your-agent-url" \
DATABASE_URL="postgres://user:pass@localhost:5432/mydb" \
npx @forestadmin/workflow-executor
```

**在哪里找到您的全权证书:**

这两个值已经存在于您的代理环境变量中 . `FOREST_ENV_SECRET` 也可以在 [app.forestadmin.com (原始内容存档于2018-10-21)](https://app.forestadmin.com/) → **设置** → **环境** – 点击您的环境 . `FOREST_AUTH_SECRET` 定义在您一边, 森林管理UI中没有.

`AGENT_URL` 是您森林管理员代理运行的 URL( 例如) . `http://localhost:3351`) (中文(简体) ).

### 数据库连接

Postgres连接可以有两种方式提供. 若为 `DATABASE_URL` 已经设定,它 用于当前。 否则执行器会从个人中构建连接字符串 部件 – 当您的平台将证书作为单独的变量曝光时, 方便:

| 变量 | 需求 | 说明 |
| --- | --- | --- |
| `DATABASE_HOST` | 对 | 数据库主机 |
| `DATABASE_NAME` | 对 | 数据库名称 |
| `DATABASE_USER` | 对 | 数据库用户 |
| `DATABASE_PASSWORD` | 没有 | 数据库密码 |
| `DATABASE_PORT` | 没有 | 数据库端口( 默认值 : `5432`(中文(简体) ) |
| `DATABASE_SCHEMA` | 没有 | 执行者表格的 Postgres 计划( 默认 ): `forest`(中文(简体) ) |

```bash
FOREST_ENV_SECRET="your-env-secret" \
FOREST_AUTH_SECRET="your-auth-secret" \
AGENT_URL="https://your-agent-url" \
DATABASE_HOST="localhost" \
DATABASE_NAME="mydb" \
DATABASE_USER="user" \
DATABASE_PASSWORD="pass" \
DATABASE_SSL="false" \
npx @forestadmin/workflow-executor
```

`DATABASE_SSL` 默认为 `true` (管理 Postgres 需要 TLS); 设置为 `false` 用于没有 TLS 的本地数据库.

`DATABASE_URL` 优先排序 : 当设定时, 单个部分被忽略.

`DATABASE_SCHEMA` 设置执行者表格所运行的 Postgres 方案( 默认 ): `forest`) (中文(简体) ). 设定为将执行者指向另一个计划——例如. `public` 当它拥有数据库时,或者与你的代理人一起共享一个计划。 该值必须是有效的 Postgres 标识符 .

启动时, 执行器会创建计划, 如果它缺失的话, 这需要 `CREATE` 特权 **数据库**数字 :

```sql
GRANT CREATE ON DATABASE "<db>" TO "<user>";
```

如果无法授予数据库级别 `CREATE`,预先创建具有管理员作用的 schema ,并只授予 schema 级别的权利——先创建 schema 级别的执行器探测器,并在已经存在时跳过创建,所以没有数据库级别 `CREATE` 需要:

```sql
CREATE SCHEMA analytics;
GRANT USAGE, CREATE ON SCHEMA analytics TO "<user>";
```

(注:Postgres检查数据库级别) `CREATE` 特权 `CREATE SCHEMA IF NOT EXISTS` 即使计划存在,执行者也会在存在探测器上打开声明,而不是依赖 `IF NOT EXISTS`. ) (中文(简体) )

使用 `DATABASE_SCHEMA=public` 在专用数据库上是最简单的设置—— `public` 永远存在,所以没有 `CREATE` 需要数据库。 在邮购15+,虽然, `public` 不再发放补助金 `CREATE` 因此执行者仍然需要它在那里创建自己的表格:

```sql
GRANT USAGE, CREATE ON SCHEMA public TO "<user>";
```

* * *

## OAuth 保护的 MCP 连接器

当您的工作流程使用 OAuth 保护的 MCP 连接器时,执行器会将每个用户的 OAuth 证书存储在其数据库中,休息时加密. 以与其他秘密相同的方式提供加密密钥( in) `.env`,或与 `-e` 打开 `docker run`:

| 变量 | 说明 |
| --- | --- |
| `FOREST_EXECUTOR_ENCRYPTION_KEY` | OAuth 证书的A-rest加密密钥(AES-256-GCM) 执行器商店. 生成方式 `openssl rand -hex 32`使用一个 **单独** 秘密从 `FOREST_AUTH_SECRET`.该值没有被验证,所以使用一个真正随机的秘密. |

-   **只要求 OAuth 保护的 MCP 连接器**,并读作懒惰——一个没有这种证书靴子的执行者,没有这种靴子就运行良好.
-   **对共享数据库的每个实例使用相同的值.** 否则,一个实例无法解密另一个实例所储存的证书.
-   **把它视为永久的:没有有管理的轮换.** 更改它迫使每个受影响的用户重新连接他们受OAuth保护的MCP连接器.

* * *

## 当 MCP 步骤无法装入工具时

执行者在 `Error`,因此在您的日志中默认值为:

```json
{
  "level": "Error",
  "message": "MCP servers failed to load tools",
  "requestedMcpServerId": "39",
  "mcpServerName": "acme-crm",
  "failures": [
    { "server": "acme-crm", "kind": "connection", "error": "connect ECONNREFUSED 10.0.4.12:8080" }
  ]
}
```

`kind` 告诉你在哪里看:

-   `auth` ——服务器拒绝了证书(HTTP 401). 在 OAuth2 连接器上, 执行器会自动刷新令牌并重试一次, 因此此行涉及静态证书; 一个恢复日志的 OAuth2 连接器 `MCP tools loaded after refreshing the credential` 时间 `Info`,不能暂停运行以进行再校正.
-   `connection` ——不可接通,拒绝,或慢于每服务器15s的负载超时.
-   `unknown` ——服务器答覆了,但负载无论如何都失败了,包括HTTP 403(证书有效但缺乏权限,无法刷新修复),这个构建的集成不支持 `error` 文本带有原因.

回答但曝光无工具的服务器不是失败: 您得到一个空工具列表, 没有出错 .

设定 `LOG_LEVEL=Debug` 每个服务器增加一行,其中包含其工具计数和加载时间,这就是您如何找到正在减速的连接器.

* * *

## 仅测试

下列模式跳过数据库要求,但 **不适合生产** ——状态在重启时丢失.

### 夹克

```bash
docker run --rm \
  -e FOREST_ENV_SECRET="your-env-secret" \
  -e FOREST_AUTH_SECRET="your-auth-secret" \
  -e AGENT_URL="http://host.docker.internal:3351" \
  -p 3400:3400 \
  ghcr.io/forestadmin/runtime:latest \
  node packages/workflow-executor/dist/cli.js --in-memory --json
```

### 没有多克

```bash
FOREST_ENV_SECRET="your-env-secret" \
FOREST_AUTH_SECRET="your-auth-secret" \
AGENT_URL="https://your-agent-url" \
npx @forestadmin/workflow-executor --in-memory
```

### OAuth2-被保护的 MCP

要锻炼执行者的 OAuth2- 受保护的 MCP 路径端到端,请将其指向 [mcp-oauth- test-server 服务器](https://github.com/hercemer42/mcp-oauth-test-server) ——一个独立的OAuth2+MCP服务器,可以模拟刷新-token吊销/旋转,拒绝同意,以及上游403s.

## 常见问题

### @forestadmin/workflow-executor 是什么？

在自己的基础设施上运行森林管理流程步骤\.

### 如何安装 @forestadmin/workflow-executor？

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

### @forestadmin/workflow-executor 支持 TypeScript 吗？

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

### @forestadmin/workflow-executor 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @forestadmin/workflow-executor 需要什么版本的 Node\.js？

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

### @forestadmin/workflow-executor 可以商用吗？

@forestadmin/workflow-executor 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @forestadmin/workflow-executor 的下载量有多少？

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

### @forestadmin/workflow-executor 还在维护吗？

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