企业官网建设流程全解析

• 工作流自动化
• 低代码
• 桌面应用
• AI Agent
• 后端

AstronRPA 在自托管 n8n 中以社区节点（Community Node）形式提供了一套受控的 RPA 工作流集成能力：通过经认证的 HTTPS MCP 协议，你可以发现工作流、启动执行、持久等待结果、查询状态并请求取消，而无需在 n8n 中自行维护轮询循环或直接暴露 RPA 执行接口。本文以 integrations/n8n/n8n-nodes-astron-rpa/README.md 为骨架，结合仓库源码与联调验收记录，完整讲解该节点的适用范围、构建安装、连接配置、执行模式、数据契约与故障恢复机制，帮助你在自托管 n8n 上安全、正确地接入 AstronRPA 发布的工作流。

适用范围与前置要求

这是一个开发验证阶段（development）的社区节点包，用于控制经过单独审批（individually approved）的工作流，其声明的supportScope为controlled-validation。需要注意：一个已批准的工作流并不代表整个 RPA 能力族被开放，文件传输、GUI 依赖、运行时对象适配、桌面/UI 操作以及任意本地路径访问，都不在本次json-data能力范围内。

该包验证通过的宿主配置与声明如下：

• 自托管 n8n2.36.9，Node.js24+，单个 OpenAPI 连接所有者（one OpenAPI connection owner），一个与仓库源码核对一致的 Windows 客户端，托管协议为1。
• 包声明n8n-workflow >=2.36.4 <3；其他宿主版本、队列模式、多副本或多终端、n8n Cloud 以及更旧客户端均不在本次验证范围内。
• OpenAPI 服务必须提供集成契约1、声明 Schema1和 MCP 协议2025-11-25。节点的所有业务操作均通过 MCP 执行，并使用既有 API Key 鉴权。
• 首个分类能力为json-data：其声明必须同时包含capabilityClass: "json-data"与capabilities: ["json-data"]，且必须明确声明无文件传输、无 GUI 要求。声明描述的是工作流本身，并不会为其能力附加适配器。

输入输出的有界 JSON 契约

json-data能力下，输入输出使用有界 JSON，服务端声明为权威：

节点会在本地执行同样的限制校验，并在服务端声明不一致时拒绝匹配失败的契约（返回CAPABILITY_UNSUPPORTED）。这一套限制在源码 mapping/contracts.ts 中以JSON_LIMITS常量定义，并在 tests/runner.test.cjs 中通过大小、深度、Unicode、对象键、循环引用等用例逐项验证；json-data工作流的 profile 必须与节点公布的这套限制完全一致（见checkWorkflow对jsonLimits的逐字段比对）。

关于 Node.js 版本的关键提醒

该包要求 Node.js>=24。官方 n8n2.36.9的 Dockerfile 将运行时基础固定为 Node.js24.18.1，满足此要求。安装前请检查 n8n 容器内部的 Node 版本，例如：

docker exec YOUR_N8N_CONTAINER node --version

宿主机的 Node 版本并不能决定容器运行时版本；仍在使用 Node.js 20/22 的旧镜像不满足本包要求。这一点与 integrations/n8n/VALIDATION.md 中记录的验证环境（Node.js24.18.0）一致。

构建、安装与连接配置

构建与测试命令

在包目录integrations/n8n/n8n-nodes-astron-rpa下、独立于前端工作区执行：

npm ci npm run typecheck npm run lint npm run format:check npm test npm pack

• npm test会先执行npm run build（TypeScript 编译），再运行node --test tests/*.test.cjs，即三个测试文件node.test.cjs、runner.test.cjs、transport.test.cjs中的全部用例。
• npm pack在打包前会通过prepack钩子再次执行构建，最终产出 tarball（验证包为n8n-nodes-astron-rpa-0.1.0-dev.1.tgz，其 SHA-256 记录在 VALIDATION.md 中）。

将生成的 tarball 安装到自托管 n8n 的社区包目录并重启 n8n 即可。包元数据声明了engines.node >=24、peerDependencies.n8n-workflow >=2.36.4 <3，以及 MCP TypeScript SDK1.30.0依赖，见 package.json。

凭据字段

在AstronRPA节点中选择AstronRPA MCP API凭据类型（astronRpaApi），其字段定义于 credentials/AstronRpaApi.credentials.ts：

TLS 校验保持启用。带 URL 凭据、带查询串和重定向的地址会被拒绝。凭据测试（astronConnectionTest）只执行发现（astron_integration_get）与就绪读取，不会启动任何执行；空工作流列表或桌面端离线并不会使认证失效。

传输层安全细节（源码级）

在 transport/mcp.ts 中，endpoint()对 URL 做了严格的准入校验：仅允许https:协议、拒绝username/password、拒绝search/hash、路径必须以/mcp/结尾且不允许歧义路径（如//mcp/、/mcp/mcp/）。HTTP 请求通过注入的fetch强制redirect: "error"（拒绝一切重定向，包括同源路径变更），并使用AbortSignal.timeout对单次网络请求设限。测试 tests/transport.test.cjs 专门验证了跨源 307 重定向在凭据到达目标前即被拒绝、无响应请求被限时且不会被误判为执行超时、未支持协议与空 Key 在发起任何网络请求前就失败。

如果你的 AstronRPA 部署只暴露 HTTP（例如http://IP:32742），必须先在网关或反向代理处配置 TLS 终止，并使用其 HTTPS/mcp/端点；证书必须被 n8n 运行时信任，HTTP 端点不能直接使用。参见仓库的 HTTPS 部署指南。

启动 Windows 客户端

通过桌面应用启动 Windows 客户端即可。单独启动 Scheduler 可能导致依赖桌面的工作流无法运行，因此应保持客户端整体按仓库配套方式启动。

运行一个工作流

标准操作流程

1. 先审批后执行：由服务器管理员通过INTEGRATION_POLICY_FILE审批已发布的工作流版本。连接成功本身不授予执行准入。
2. 使用List Workflows与Get Workflow获取项目 ID、已发布版本、输入 Schema 与准入结果。
3. 选择Execute，填入 project/version 与 JSON 输入并选择执行模式。当需要在多次 n8n 执行之间恢复时，提供一个稳定、非机密的业务键（Business Idempotency Key）。
4. 保留返回的executionId，用于后续查询或取消。

操作行为一览

从源码看，这五个操作映射到 MCP 工具astron_workflow_list、astron_workflow_get、astron_workflow_execute、astron_execution_get、astron_execution_cancel，并且astron_integration_get负责连接测试与每次执行前的契约核验（见 nodes/AstronRpa/AstronRpa.node.ts 与checkIntegration）。

节点参数与输入输出语义

Execute 相关的核心参数（定义于节点描述properties，见 AstronRpa.node.ts）：

输入输出语义要点：

• 输入保真：0、false、null、数组与对象在传输中保持原样。n8n 表达式在准备请求时求值，其产生的 JSON 值在该次执行中被固定。
• 结果聚合：结果保留在result字段中，数组不会被展开成额外的 n8n item。
• 输出身份：输出包含执行/项目/版本身份、状态、终态标志、时间戳与取消状态。
• 秘密输入抑制结果：带秘密输入的工作流会抑制整个 RPA 结果，resultVisibility: "suppressed-for-secret-inputs"用于解释 null 结果。注意这不会从 n8n 的执行存储中删除输入本身——请把 API Key 放在凭据中，而不是工作流输入里。

执行数据保留（务必阅读）

Wait 与 Sync 会创建一个子执行（child execution），其saveDataSuccessExecution: "all"与saveDataErrorExecution: "all"都被显式设置（见 execution/workflow.ts 中内联工作流的settings）。子执行的输入与等待检查点（waiting checkpoints）包含准备好的请求，包括在 AstronRPA 中标记为 secret 的参数。这些值在完成后仍可能保留在 n8n 执行记录中；仅在父工作流上禁用成功执行存储，并不能禁用子执行的显式设置。Async 的输入也可能按父工作流设置被保留。

因此请：限制对 n8n 执行记录与备份的访问，并在 n8n 主机上启用执行数据清理。例如按你的保留需求调整：

EXECUTIONS_DATA_PRUNE=true EXECUTIONS_DATA_MAX_AGE=168 EXECUTIONS_DATA_PRUNE_MAX_COUNT=10000

• EXECUTIONS_DATA_MAX_AGE以小时为单位。
• 清理只会缩短已结束执行的保留期，不是即时的机密擦除，也不会删除备份中的副本。
• 请保留等待检查点直到对应执行被解决，因为持久恢复依赖保存的请求与执行身份。

json-data 工作流边界

每次执行前请先调用 Get Workflow 并核验：

1. profile.capabilityClass为json-data；
2. profile.admission.allowed为true；
3. 返回的inputSchema与将要发送的数据匹配。

在节点侧，checkWorkflow（见 mapping/contracts.ts）会同时核验schemaVersion=1、projectId/version 一致、准入允许、声明 revision 存在，并强制json-data类声明同时具备capabilities: ["json-data"]与完全一致的jsonLimits，否则抛出ADMISSION_DENIED或CAPABILITY_UNSUPPORTED。

未知字段、非有限数值、运行时对象、文件值以及超过发布限制的值，都会在派发前被拒绝。结果始终是result下的单个 JSON 值，数组不会展开为 n8n items；可选的outputSchema只用于文档化结果形状，不会开启文件、GUI 或运行时对象能力。其他 RPA 能力类别不在本发布版本的节点契约内。

对 json-data 执行，服务端在受理时冻结输出 Schema 与 JSON 限制，并在持久化前检查成功结果：

• 超过字节限制或不符合 Schema 的结果变为failed / UNSUPPORTED_RESULT，不保存业务负载；
• 字节限制衡量的是业务结果的紧凑 UTF-8 编码，执行 ID、状态等信封字段不消耗该额度；
• 节点单独校验结果值与执行元数据，因此恰好 1 MiB 的结果仍可被正常读取。这一点在 tests/runner.test.cjs 中有专门的字节边界用例（含多字节字符"界"），并在 VALIDATION.md 的 JSON 数据契约审阅修订验证中实测确认：1,048,576 字节成功持久化，1,048,577 字节转为失败封装。

执行行为与限制

幂等与重试

每一次启动都带有幂等键。自动键按 n8n 执行、节点、run 与输入项隔离；新的 n8n 执行或手动重跑会生成新键（源码中自动键通过hash([instanceId, executionId, nodeId, $runIndex, itemIndex])生成，并利用节点上下文中的指纹记录在重试时拒绝变更后的请求——REQUEST_CHANGED_ON_RETRY，测试见 tests/node.test.cjs）。

要在多次执行之间恢复既有请求，请使用原始业务键 + 版本 + 输入 + RPA 期限 + 声明 revision；请求内容变化会产生冲突。

Frozen Declaration Revision（冻结声明修订）：如果发布或准入发生了变化，该参数接受原始correlation.profileRevision与完整的原始请求及业务键一起提交。服务端会重新做授权检查并返回已有的匹配回执；该修订不会授权未经批准的启动（节点要求使用此参数时必须同时提供非空业务键，否则报RECOVERY_KEY_REQUIRED）。

关键警告：在 n8n2.36.9上，Retry On Fail 不会重跑持久等待返回的业务失败。同键恢复返回原始失败回执；要刻意再次执行业务操作，必须使用新键。该行为已由真实联调验证（见 VALIDATION.md 中“失败恢复与原生重试”一项）。

等待、取消与批处理

三个超时概念的区分非常关键：

Wait 模式顺序处理输入项。前一项状态未知或未解决时，会阻塞后续项的启动，即使开启 Continue On Fail 也一样（错误码PREVIOUS_EXECUTION_UNRESOLVED）；已确认失败时，在启用继续的情况下可以进入下一项。Async 模式顺序提交且不等待桌面可用性——客户端忙碌并不构成隐式队列。

Cancel 针对指定执行。注意：取消请求本身不是完成证据，停止进程也不会撤销已经产生的业务影响。

恢复与错误处理

• 等待检查点可以在 n8n 重启后恢复；恢复可能因 n8n 的 waiting-execution 扫描而延迟。活跃步骤中的任意崩溃、以及等待执行在包版本之间的迁移，不在恢复保证范围内。请保留执行数据直到在途工作解决，并在升级或回滚节点前先解决等待中的执行。
• unknown状态不能确认任务已停止。请通过原始 ID 或原始请求/业务键恢复；不要仅仅因为一次响应丢失就切换传输方式或创建新键。
• Execute 失败遵循 Stop/Continue/error-output 设置；Query 与 Cancel 以数据形式返回快照。在错误分支上，$json.error包含一个携带安全执行身份的 JSON 信封，可用JSON.parse($json.error).executionId读取已知 ID；受理前的错误可能没有 ID。
• 节点的状态快照校验（snapshot）会强制 UUID 格式、状态枚举（accepted/running/succeeded/failed/cancelled/timeout/unknown）与终态标志的一致性，并在不匹配时抛出不确定错误INVALID_EXECUTION_RESPONSE，避免把伪造或异常响应当作事实（见 mapping/contracts.ts）。

重新发布后的执行管理

普通重新发布会保留对已受理执行的管理：已受理执行的查询、同键恢复与取消在重新发布后仍然有效。工作流删除、所有权变更、外部访问被禁用以及 API Key 吊销，仍会拒绝访问。

这也改变了既有 REST 行为：工作流重新发布后，GET /executions/{execution_id}仍可返回此前受理、仍使用原版本的执行，而不是仅因发布版本变化就拒绝；GET /executions/get同样包含符合条件的旧版本执行。所有权、外部访问与 API Key 检查仍然生效。启动新执行仍须使用当前发布版本；查询旧执行不会授权对旧版本发起新启动。服务端侧的实现与说明见 backend/openapi-service/app/services/workflow_control.py 与 backend/openapi-service/README.md。

服务端准入配置（INTEGRATION_POLICY_FILE）

节点的准入执行依赖 OpenAPI 服务端的声明与准入策略。在 OpenAPI 上设置INTEGRATION_POLICY_FILE指向管理员所有的 JSON 策略文件即可；模型定义于 backend/openapi-service/app/services/integration_policy.py，空策略为：

{ "schemaVersion": 1, "enforcedUsers": [], "declarations": [] }

• 空策略不允许任何工作流通过社区节点执行。需要把目标用户加入enforcedUsers，并为每个已批准的项目/版本添加经评审的声明（declaration）。
• 声明绑定所有者、项目、版本与输入 Schema 摘要，并描述能力、可选能力类别、文件输入输出、GUI/人工要求、环境、副作用、风险、执行类型、独占终端要求与可选输出 Schema。
• json-data类别要求同时具备capabilityClass: "json-data"与capabilities: ["json-data"]，拒绝文件传输与 GUI 要求，并在工作流 profile 中暴露有界 JSON 限制。
• 支持范围为controlled-validation；文件传输类声明被拒绝。未知值区别于 false。
• 在 enrolled 用户范围内，固定 MCP、动态 MCP 与 REST 启动共享准入校验；未知、不完整、过期或被拒绝的声明一律拒绝。格式错误的配置文件会拒绝新启动，而不是静默关闭策略执行。
• 每个 OpenAPI 进程按解析路径与文件元数据（含纳秒 mtime、大小与文件身份）缓存最后成功解析的策略；未变更的文件不会反复读取/解析。更新时请原子替换文件。缺失、不可读、损坏或读取期间变更的文件一律INTEGRATION_POLICY_UNAVAILABLE关闭（fail closed），绝不回退到旧的合法策略。
• 公开的revision是完整声明的摘要，任何声明内容的变更都会改变该修订。profileRevision将已准备的请求绑定到该修订；同键恢复在授权范围内返回已有的受理回执，而无需为该执行重新申请新声明。

示例工作流与验证记录

仓库提供了可直接导入的示例：examples/execute-and-query.json 演示了AstronRPA Execute（Async）→ AstronRPA Query（Get Execution）的最小链路。导入后需自行选择凭据，并把projectId、version与idempotencyKey替换为已批准的发布；Query 返回的是当前状态，不代表完成。如需节点自持的持久完成，把 Execute 模式改为Wait即可，无需外部等待循环；需要取消时使用Cancel Execution传入精确返回的 ID。示例均为配置示例而非已准入的测试夹具，不含部署端点或凭据值；在原生错误输出上，可从$json.error解析安全信封，例如JSON.parse($json.error).executionId（详见 examples/README.md）。

integrations/n8n/VALIDATION.md 记录了完整的验收过程：节点测试 21–24 项通过，OpenAPI 定向回归 203–244 项通过；真实联调覆盖了安装发现、鉴权传输、客户端离线/忙碌、跨入口准入、Async/Wait/Sync、幂等与响应丢失、n8n 重启恢复、等待预算与执行期限、批量失败与错误路由、取消竞态、版本变化与设计器发布、OpenAPI/客户端重启、秘密输入抑制以及 JSON 数据型工作流等场景。同时它明确列出了两个未完成项：全仓make check因 frontend 根目录缺少tsconfig.json而未通过；运行中设计器完整 UI 发布的组合验证尚未完成。部署前建议通读该文件，以准确理解验证边界。

仓库参考文档

• 服务端准入配置说明
• 示例工作流
• 验证结果与未完成检查

以上引用均位于源仓库中；验证流程、环境细节与执行证据维护在验证记录文件中。生产接入前，请务必核对你的 n8n 版本、OpenAPI 契约版本、客户端托管协议与上述验证范围保持一致。

• 工作流自动化
• 低代码
• 桌面应用
• AI Agent
• 后端