# 工作流调试、异常捕获与版本回滚

> 使用画布运行预览、节点级输入输出检查、错误捕获分支与版本历史保障工作流可靠性。

Source: https://doc.fastgpt.cn/zh-CN/guide/build/workflow/debug-and-error-handling

复杂工作流包含多模型调用、外部 HTTP 请求、代码沙箱与嵌套容器。在正式发布前，可通过画布调试、异常捕获分支（Error Handling）与版本快照机制定位问题并建立容错路径。

## 一、画布调试与节点运行详情

1. **启动调试**：在工作流编辑器右上角点击**运行**，打开右侧调试预览抽屉。包含前置全局变量时，先填写测试变量值，再输入测试问题。
2. **实时状态高亮**：运行过程中，画布上正在执行的节点会高亮显示运行状态；遇到[用户选择](/zh-CN/guide/build/workflow/nodes/user-selection)或[表单输入](/zh-CN/guide/build/workflow/nodes/form_input)节点时，工作流进入交互挂起状态并等待调试面板提交输入。
3. **检查节点输入与输出**：回复完成后，点击消息下方的**运行详情**，按执行顺序逐个展开节点，核对：
   * **输入参数**：实际解析后的提示词、变量值、检索过滤条件或请求体。
   * **输出结果**：模型回复、引用分块数量、提取字段、脚本返回值或错误信息。
   * **耗时与计费**：单节点执行时长（秒）及模型 Token / 积分消耗。

![在运行详情中检查节点输入与输出参数](/imgs/optimized/current/variable-update-detail.png.webp)

## 二、报错捕获分支（Error Handling）

调用外部服务或执行动态逻辑的节点在输出区标题右侧提供**报错捕获**开关。开启后，输出区下方会多出错误输出区块，从该区块右侧的连接点连线，即可将单节点报错引导至容错分支处理：

### 支持报错捕获的核心节点

| 节点类型                                                                                 | 错误输出字段                                        | 常见触发场景                          |
| ------------------------------------------------------------------------------------ | --------------------------------------------- | ------------------------------- |
| **HTTP 请求**（`httpRequest468`）                                                        | `错误信息`（`error`）、`完整错误`（`system_httpRawError`） | 目标接口超时、连接失败，或返回异常状态码            |
| **代码运行**（`code`）                                                                     | `错误信息`（`error`）                               | JS / Python 脚本语法异常、运行时抛出错误或沙箱超时 |
| **AI 对话 / Agent / 文本内容提取 / 工具调用**（`chatNode` / `agent` / `contentExtract` / `tools`） | `错误信息`（`system_error_text`）                   | 模型渠道限流（429）、上下文超限、凭证失效或工具调用异常   |
| **知识库搜索**（`datasetSearchNode`）                                                       | `错误信息`（`system_error_text`）                   | 向量或重排模型调用异常、检索超时                |
| **循环节点**（`loopRun`）                                                                  | `错误信息`（`system_error_text`）                   | 子流程内部节点执行报错                     |

并行执行（`parallelRun`）没有报错捕获开关。它的 `完成状态`（`parallelStatus`，取值 `success` / `partial_success` / `failed`）和 `完整结果`（`parallelFullResults`）是常规输出，可接[判断器](/zh-CN/guide/build/workflow/nodes/tfswitch)按完成状态分流。

### 配置容错与降级流程

1. 将主节点（如 HTTP 请求）原有的右侧出口连接到正常业务处理节点。
2. 开启 **报错捕获**，将错误输出区块右侧的连接点连接到降级处理节点（例如备用模型、固定提示的[指定回复](/zh-CN/guide/build/workflow/nodes/reply)，或用于告警记录的节点）。
3. 在降级节点中引用上游节点的 `错误信息` 字段，向用户返回友好提示或在日志中保留诊断上下文。

## 三、草稿自动保存与历史版本回滚

1. **草稿与正式版隔离**：在画布上的移动、连线与参数修改会自动保存在当前草稿中，仅在编辑器“运行”调试时生效，线上已发布的分享链接、门户和 API 保持运行上一个正式发布版本。
2. **发布版本快照**：点击右上角**保存**按钮并选择**保存并发布**（或选择**仅保存**更新草稿），在弹窗中确认版本**名称**（默认填充当前时间戳），即可生成不可变的正式版本快照。
3. **查看与回滚历史版本**：点击右上角**运行**按钮左侧的时钟图标按钮打开版本面板。面板分为**我的编辑**和**团队云端**两个标签页：“我的编辑”列出你的画布编辑快照，“团队云端”列出已保存的版本，已发布版本带“当前版本”或“发布过”标记。点击任一版本会直接将画布切换为该版本，并提示“切换成功”；确认无误后再次点击**保存 → 保存并发布**即可完成线上回滚。

## 常见排障清单

| 故障现象           | 诊断位置与修复方式                                                                   |
| -------------- | --------------------------------------------------------------------------- |
| 分支切换后下游节点被意外跳过 | 查阅 [工作流调度原理](/zh-CN/guide/build/workflow/intro) 中的入边就绪与跳过传播规则，确认汇合节点的上游入边状态 |
| 连线无法吸附到目标端口    | 查阅 [工作流编排规则校验](/zh-CN/guide/build/workflow/rules)，检查普通连线与工具连线、容器内外部边界限制     |
| 线上用户报错但本地调试正常  | 进入 [对话日志](/zh-CN/guide/build/logs) 查看线上真实输入、文件链接有效性与发布版本差异                  |