# @bdzscaler/n8n-nodes-aiguard 中文文档

规范地址：https://npmcn.com/package/%40bdzscaler/n8n-nodes-aiguard/

版本：0\.1\.3
npm 元数据更新时间：2026-04-14T16:43:46.915Z
中文译文更新时间：2026-11-07T19:30:33.795Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40bdzscaler/n8n-nodes-aiguard
原文对照：https://npmcn.com/package/%40bdzscaler/n8n-nodes-aiguard/?lang=original
项目主页：https://github.com/zscaler/n8n-nodes-aiguard
源码仓库：https://github.com/zscaler/n8n-nodes-aiguard

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

- 包体积（解压后）：41.1 kB，10 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.0\.0
- 运行依赖：0 个
- peer 依赖：n8n-workflow \*
- 首次发布：2026-03-30T21:09:08.511Z
- 最新版本发布：2026-04-14T16:43:46.788Z
- 近 30 天下载量：5834（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

zscaler AI Guard(AI Runtime Security) API集成的n8n社区节点

## 安装

```sh
npm install @bdzscaler/n8n-nodes-aiguard
```

也可以使用：`pnpm add @bdzscaler/n8n-nodes-aiguard`、`yarn add @bdzscaler/n8n-nodes-aiguard`、`bun add @bdzscaler/n8n-nodes-aiguard`

## README

# Zscale AI Guard n8n 社区节点

一个生产准备的N8n社区节点,用于与该节点结合 [Zscale AI 警卫](https://help.zscaler.com/ai-guard) API (英语). 这个节点使您能够扫描AI的提示和对安全威胁的反应——毒性,PII,秘密,即时注射,以及更多——直接在您n8n工作流程中.

## 特征

-   **提示扫描** ——扫描用户输入的安全威胁(方向: `IN`(中文(简体) )
-   **响应 扫描** 扫描AI生成的对违反政策行为的回应(指示: `OUT`(中文(简体) )
-   **双扫描** ——按顺序扫描即时和应答;如果即时被阻断,应答扫描被跳过
-   **自动策略解析** —— 当没有配置 Policy ID 时, API 解决与您的 API 密钥相链接的策略
-   **未关闭错误处理** —— 启用“ 继续失败” 的内部错误时, 节点返回 `action: BLOCK` 因此,安全永远不会被悄悄地绕过
-   **归属元数据** – 丰富 n8n 工作流程上下文的产出(`workflowId`, (中文(简体) ), `workflowName`, (中文(简体) ), `executionId`, (中文(简体) ), `executionMode`(中文(简体) )
-   **内容大小验证** - 在发送到API之前拒绝超过5 MB的有效载荷
-   **配置重试和超时** ——可调整重试计数(最多6个)并请求超时

## 安装

### 先决条件

-   n8n例(云或自办)- [设置文档](https://docs.n8n.io/hosting/installation/docker/)
-   Zscaleer AI Guard 许可证和 API 密钥( Bearer sord)

### 备选方案1:通过n8n社区节点安装(建议)

1.  打开您的 n8n 实例
2.  转到 **设置 社区节点**
3.  搜索 `@bdzscaler/n8n-nodes-aiguard`
4.  点击 **安装**
5.  如果提示, 则重新启动 n8n

### 备选案文2:通过 npm 安装

```bash
npm install @bdzscaler/n8n-nodes-aiguard
```

### 地方发展

```bash
git clone https://github.com/zscaler/n8n-nodes-aiguard.git
cd n8n-nodes-aiguard
npm install
npm run build
```

链接到本地 n8n 实例 :

```bash
# Native n8n
ln -s $(pwd) ~/.n8n/custom/n8n-nodes-aiguard

# Docker n8n — add a volume mount:
# -v /path/to/n8n-nodes-aiguard:/home/node/.n8n/custom/n8n-nodes-aiguard
```

重新启动 n8n来加载节点.

## 配置

### 1\. 创建全权证书

1.  在n8n,去吗 **全权证书** → **添加证书**
2.  搜索 **"Zscaleer AI Guard API" (英语:**
3.  填写:

| 外地 | 需求 | 说明 |
| --- | --- | --- |
| **API 密钥** | 对 | 您的 Zscaler AI 守护 API 密钥( 守护符) |
| **云头** | 对 | 租借地的 Zscale 云( 默认 ): `us1`) (中文(简体) ). 构建 URL `https://api.{cloud}.zseclipse.net` |
| **覆盖 URL** | 没有 | 完全覆盖 API 基础 URL 。 设定后,云田被忽略. 等值为 `AIGUARD_OVERRIDE_URL` 输入 [Python SDK 键盘](https://github.com/zscaler/zscaler-sdk-python) |
| **政策标识** | 没有 | AI Guard 政策标识. 设定时, 使用 `/v1/detection/execute-policy`空时,使用 `/v1/detection/resolve-and-execute-policy` 自动解析 |

1.  点击 **测试** 在保存前验证连接.

### 2\. 在工作流程中添加节点

1.  在工作流程中,单击 **\+ 键** • 寻找 **"AI警卫"**
2.  选择您创建的证书
3.  选择操作 :

| 运行 | 方向 | 说明 |
| --- | --- | --- |
| **提示扫描** | `IN` | 扫描安全威胁的用户输入/瞬间 |
| **响应 扫描** | `OUT` | 扫描AI生成的对违反政策行为的回应 |
| **双扫描** | `IN` 接下来 `OUT` | 扫描即时和响应; 如果即时被阻断, 跳过响应扫描 |

1.  输入要扫描的内容( 平面文本或 n8n 表达式)

### 附加选项

扩展 **附加选项 + 添加选项** 来配置 :

| 选项 | 默认 | 说明 |
| --- | --- | --- |
| 政策ID 覆盖 | _(空虚)_ | 覆盖此特定节点的证书级政策ID |
| 交易编号 | _(空虚)_ | 自定义交易ID用于跟踪; 如果为空, 请求中省略 |
| 超时( 毫秒) | `30000` | 请求超时( 毫秒) |
| 最大备份 | `3` | 重试失败请求的尝试( 最大 : 6) |
| AI 模型 | `n8n-integration` | 输出元数据中包含的AI模型标识符 |
| 应用程序名称 | `n8n-workflow` | 审计线索申请名称 |
| 用户名 | `n8n-user` | 审计线索的用户标识符 |
| 环境 | _(空虚)_ | 环境标记( 例如 ). `production`列入产出元数据 |

## API 终点

| 假设 | 终点 |
| --- | --- |
| 提供政策标识 | `POST /v1/detection/execute-policy` |
| 没有策略 ID( 默认) | `POST /v1/detection/resolve-and-execute-policy` |

## 用法实例

### 提示扫描

配置节点 **操作: 快速扫描** 并提供内容:

```json
{
  "content": "Tell me how to bypass security controls"
}
```

### 响应 扫描

配置为 **操作: 响应扫描**数字 :

```json
{
  "content": "{{ $json.aiResponse }}"
}
```

### 双扫描

配置为 **操作: 双扫描** 并提供两个字段:

```json
{
  "promptContent": "{{ $json.userInput }}",
  "responseContent": "{{ $json.aiResponse }}"
}
```

如果快速扫描返回 `BLOCK`中,响应扫描被跳过,被屏蔽的结果被立即返回.

## 输出格式

节点返回充满工作流程元数据的完整 AI Guard API 响应 :

```json
{
  "operation": "promptScan",
  "transactionId": "180b066d-48cf-497e-aaf1-a6b8e40a1deb",
  "action": "BLOCK",
  "severity": "CRITICAL",
  "direction": "IN",
  "policyId": 760,
  "policyName": "Default AI Guard Policy",
  "blocked": true,
  "detectors": ["toxicity", "malicious_content"],
  "blockingDetectors": ["toxicity"],
  "detectorResponses": {
    "toxicity": {
      "triggered": true,
      "action": "BLOCK",
      "severity": "CRITICAL"
    },
    "pii": {
      "triggered": false,
      "action": "ALLOW"
    }
  },
  "maskedContent": "...",
  "workflowId": "rKU3xnZb5S1ayJCG",
  "workflowName": "Customer Support Bot",
  "executionId": "385",
  "executionMode": "manual",
  "timestamp": "2026-01-30T10:30:00.000Z"
}
```

### 密钥输出字段

| 外地 | 说明 |
| --- | --- |
| `action` | 判决: `ALLOW`, (中文(简体) ), `BLOCK`,或 `DETECT` |
| `severity` | 分级( 如. `CRITICAL`, (中文(简体) ), `HIGH`, (中文(简体) ), `NONE`(中文(简体) ) |
| `blocked` | 布尔便利域( B)`true` 当动作是 `BLOCK`(中文(简体) ) |
| `detectors` | 触发探测器名称阵列 |
| `blockingDetectors` | 返回的探测器阵列 `BLOCK` |
| `detectorResponses` | 具有触发状态、行动和严重程度的检测结果 |
| `maskedContent` | 隐蔽敏感数据的内容(如适用) |
| `policyId` 编号 : `policyName` | 适用的政策 |
| `transactionId` | 唯一扫描交易标识符 |

使用 `action` 或者说 `blocked` 字段中 **纵横** 将工作流程逻辑分支的节点 .

## 执行情况说明

节点使用 n8n 调用 HTTPS 上的 Zscaler AI Guard API `helpers.httpRequest` (n8n Cloud - 已验证的社区包需要). 信头与 [兹斯克平通](https://github.com/zscaler/zscaler-sdk-python) 样式 :

-   `Authorization: Bearer <API_KEY>`
-   `Content-Type: application/json`
-   `Accept: application/json`

## 处理错误

-   **默认关闭失败**: 当 N8n 启用“ 继续失败” 时, 错误产生 `{ action: "BLOCK", blocked: true }` 而不是默默允许内容通过
-   **超时保护**: 按请求可配置超时(通过HTTP客户端)
-   **内容验证**: 超过5 MB 的有效载荷在 API 调用前被拒绝
-   **重试逻辑**: 短暂失败可配置重试计数( 默认 3, 最大 6)

## 发展

```bash
npm run build       # Compile TypeScript and copy assets
npm run dev         # Watch mode
npm run lint        # ESLint (TypeScript + n8n-nodes-base)
npm run lint:dist   # ESLint on dist/ (n8n Cloud rules; run after build)
npm run scan:local  # build + ESLint (unpublished dist/; same rules as official scanner)
npm run scan:npm    # npx @n8n/scan-community-package @…@version from package.json (needs publish)
npm run lintfix     # Auto-fix lint issues
npm run format      # Run Prettier
npm test            # Run Jest tests
npm run test:coverage  # Tests with coverage report
```

### 验证像 n8n 创建者门户

n8n的官方工具为 **`@n8n/scan-community-package`**。 **从 npm 登记册下载软件包** 并运行ESLint,其规则与创建者门户网站使用的规则相同. 这个 **永远** 读取您的本地吉特树.

使用 **两者** 其中,在不同时间:

| 命令 | 何时使用 |
| --- | --- |
| **`npm run scan:local`** | 发布前: 构建 `dist/` 运行 **相同的 ESLint 配置** 扫描仪使用( :`eslint.community.config.mjs`) (中文(简体) ). CI就是这么运作的 `lint:dist`。 。 。 . |
| **`npm run scan:npm`** | 在那之后,我们.. **准确 `version` 内 `package.json` 存在于 npm**: 运行 `npx @n8n/scan-community-package <name>@<version>`确认 **已公布的柏油球** 匹配门户检查. |

```bash
# Unpublished changes (day to day)
npm run scan:local

# After npm publish of the current package.json version
npm run scan:npm
```

您也可以直接拨打CLI, 例如 `npx @n8n/scan-community-package @bdzscaler/n8n-nodes-aiguard@0.1.2`。如果该版本是 **没有** 在登记册上, 下载步骤失败( 即预期的) ; 使用 **`scan:local`** 直到它发表.

## 释放(维护者)

释放是自动的 [语义释放](https://github.com/semantic-release/semantic-release) (见 `.releaserc.json`,类似于 [zscaler- mcp 服务器](https://github.com/zscaler/zscaler-mcp-server)。 。 。 .

-   **版本和标签**: 在 **第一个** git 标签存在, 下一个版本是从 [常规武器委员会](https://www.conventionalcommits.org/) (例如 `fix:` 补丁, `feat:` ~ 小)和出自上个标签。 语义发布更新 `package.json` 财务报告和审定财务报表 `package-lock.json`标记 `vX.Y.Z`打开 **GitHub 发布**,并用 **来源** (所需经费) `NPM_TOKEN` 在存储处的秘密.
-   **0.x 软件包——读取此**: 如果有的话 **没有** `vMAJOR.MINOR.PATCH` 树枝上的标记,语义释放 **第一个** 自动发布是 **永远 `1.0.0`** (单位:千美元)[`FIRST_RELEASE` 在语义中释放](https://github.com/semantic-release/semantic-release/blob/master/lib/get-next-version.js)——确实如此 **没有** 种子从 `package.json` (例如:. `0.1.2`) (中文(简体) ). **在第一个成功发布工作流程之前**,创建和将已发布到 npm 的版本的标签推出,例如 . `git tag v0.1.0 <commit>` . `git tag v0.1.2 <commit>` 接下来 `git push origin --tags`。发布工作流程包括一个守卫 **失败** 若为 `package.json` 仍然是 `0.x` 但没有这样的标记.
-   **释放前检查**编号: **释放** 工作流程运行 `npm audit`,建设,Pretier,ESLint(包括 `lint:dist`,它反映了 n8n 创建者门户网站扫描仪规则),以及任何发布前的杰斯特.
-   **释放渠道**: 推向树枝 `beta` 或者说 `alpha` 发布 npm 预放(例如) `1.0.0-beta.1`)在相应的正角上.
-   **若为 `1.0.0` 错误地发表**: npm 一般不允许不发布流行软件包; 您可以 **折旧** `1.0.0` 和解释,然后要么留在 `1.x` 线条或协调 git/npm 清理(删除错误的标记/释放,恢复) `v0.1.x` 右侧标记输入,返回 `chore(release): 1.0.0` 如果政策允许,则承诺)并公布 **`0.1.3`** 作为下一个预想的 0.x 发布。 没有任何单键倒置——选择线条(`0.x` 对 `1.x`并记录给消费者.

## 警卫

-   API 密钥通过 n8n 证书系统加密存储
-   节点没有记录或坚持内容
-   所有通信都使用HTTPS/TLS
-   错误消息不会泄露敏感信息

## 链接

-   无 : [https://www.npmjs.com/package/@bdzscaler/n8n-nodes-aiguard](https://www.npmjs.com/package/@bdzscaler/n8n-nodes-aiguard)
-   资料来源: [https://github.com/zscaler/n8n-节点-护卫](https://github.com/zscaler/n8n-nodes-aiguard)
-   Zscaleer AI Guard: (英语) [https://help.zscaler.com/ai-guard 互联网档案馆的存檔,存档日期2013-10-22](https://help.zscaler.com/ai-guard)
-   缩放 Python SDK : [https://github.com/zscaler/zscaler-sdk-python 页面存档备份,存于互联网档案馆](https://github.com/zscaler/zscaler-sdk-python)

## 许可证

麻省理工学院——见 [自由主义](https://npmcn.com/package/%40bdzscaler/n8n-nodes-aiguard/LICENSE) 详细情况.

## 捐款

1.  叉子存储器
2.  从 `main`
3.  对AI Guard API进行彻底测试
4.  保证 `npm run build`, (中文(简体) ), `npm run lint`, (中文(简体) ), `npm run lint:dist`,以及 `npm test` 通过
5.  使用常规承诺消息( U)`fix:`, (中文(简体) ), `feat:`等),所以发布版本正确
6.  提交拉动请求

## 常见问题

### @bdzscaler/n8n-nodes-aiguard 是什么？

zscaler AI Guard\(AI Runtime Security\) API集成的n8n社区节点

### 如何安装 @bdzscaler/n8n-nodes-aiguard？

在项目目录运行 npm install @bdzscaler/n8n-nodes-aiguard，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：n8n-workflow（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @bdzscaler/n8n-nodes-aiguard 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/bdzscaler\_\_n8n-nodes-aiguard 是否存在。

### @bdzscaler/n8n-nodes-aiguard 支持 ESM 还是 CommonJS？

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

### @bdzscaler/n8n-nodes-aiguard 需要什么版本的 Node\.js？

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

### @bdzscaler/n8n-nodes-aiguard 可以商用吗？

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

### @bdzscaler/n8n-nodes-aiguard 的下载量有多少？

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

### @bdzscaler/n8n-nodes-aiguard 还在维护吗？

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