导入 n8n 工作流
本演练将一个从 n8n 导出的工作流——一个使用 OpenAI 聊天模型和记忆来回答聊天消息的 AI 代理——导入为一个 Aggregate、一个 Release 和一个 Manifest,它们按原样即可为 Docker Compose 构建承载该工作流的 n8n;随后构建它们并运行结果。下面的每个文件和每段输出都来自一次真实运行;工作流和演练的每个阶段都位于 import-n8n 示例中,其中的检查脚本会再次运行导入,将它写出的内容、打印的内容以及本页引用的代码块与那里保存的文件进行比较,并验证和构建导入写出的内容。
生成示例
你可以使用本页的命令运行此导入,也可以让你的 AI 助手替你运行。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example import-n8n然后它会打印接下来要运行的命令。第一条命令进入新文件夹;其后的那条命令见下文,它进入新文件夹的 source 文件夹,该文件夹包含本页导入的内容,也是运行导入的位置:
cd import-n8n
工作流
support-agent.json 是为本演练按 n8n 导出工作流的格式编写的,包含四个节点:一个聊天触发器、一个带有简短系统消息的 AI Agent、一个选择 gpt-4o-mini 的 OpenAI Chat Model 节点,以及一个 Simple Memory 节点,它们由连接相连,n8n 按每条连接出发的节点名称列出这些连接。聊天触发器是公开的,因此发送到其 URL 的聊天消息会启动工作流;触发器会要求发送者提供用户名和密码,并根据 n8n 存储的基本身份验证凭据进行校验:
"parameters": { "public": true, "authentication": "basicAuth", "options": {} }, [… omitted: the node's identifier, name, type, version, position and webhook identifier] "credentials": { "httpBasicAuth": { "id": "Vx3mQ8rLb2Nk7Tz5", "name": "Chat basic auth" } }模型节点以相同的方式通过引用选择其凭据——导出内容携带每个凭据的标识符和名称,绝不携带用户名、密码或密钥:
"parameters": { "model": { "__rl": true, "value": "gpt-4o-mini", "mode": "list", "cachedResultName": "gpt-4o-mini" }, "options": {} }, "id": "6f1d2c3a-7b4e-4a8f-9c21-0d3e5f6a7b03", "name": "OpenAI Chat Model", "type": "@n8n/n8n-nodes-langchain.lmChatOpenAi", "typeVersion": 1.2, "position": [120, 220], "credentials": { "openAiApi": { "id": "Rb7nW2xQ9kT4mZ1c", "name": "OpenAI account" } }在工作流旁边,一个 .aggrega-config.yaml 使该文件夹成为工作区:
# The workspace key marks this directory as the workspace root, so an import run# here writes its drafts beside support-agent.json.workspace: {}# The registry the importer is fetched from the first time an import needs it.default_registry: hub.aggrega.ai而 import-answers.yaml 保存任何工作流都无法保存的内容的答案。面向 Docker Compose 的导入不需要任何答案:它通过 Docker Compose 从你的 shell 中填充的变量引用来附加 OpenAI 密钥。面向 Kubernetes 的导入则通过 Kubernetes Secret 的名称来附加它,而这个名称只有你能指定,因此该文件会指定该 Secret(参见在 Kubernetes 上):
# Values the import could not draft from the source, keyed by the drafted file and the key path inside# it. Write each one beside its key; an import of the same source, and a sync, read them from here and# ask nothing. A secret is never written here: its key asks where the secret comes from — a variable# name, ${NAME}, or the name of a Kubernetes Secret.release.yaml: # The origin of the secret value, written by the operator in the Release. Read exactly as # values.origin is. Write it here or in values.origin, never in both. A secret: name where it comes # from, never the value. spec.components.n8n.uses.model.openai-chat-model.features.credential.infra.origin: "openai-api-key"导入答案文件完整描述了该文件。
导入会将每个节点与工作区目录中的 Components 进行比对评估,而 --target 会根据该目录的 Recipes 起草一个 Manifest。工作区没有指定目录文件夹,因此导入会从获取其导入器的注册表中读取标准库目录:这是已发布目录的一个签名快照,由第一次导入获取、验证并保存在工作区的内容缓存中,并在导入写在其草稿旁的记录中以其摘要标明。指定了自己的目录文件夹的工作区——在 AGGREGA_CATALOG_DIRS 中,或在 workspace.catalog_dirs 下——则改为针对这些文件夹进行导入。进入 source:
cd source运行导入
aggrega import support-agent.json --target compose它在标准输出上列出所写的内容:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.json在标准错误上,其中 <workspace> 代表你运行它的文件夹:
[… omitted: a warning that the importer runs unverified, printed where its module is read from beside its Plugin entity in a catalog folder rather than fetched]read as the n8n format, with drafted paths relative to <workspace>warn: the value of credentials.httpBasicAuth.id of node When chat message received is carried as written in the flow the draft carries: its format marks the field as a credential, and setting empty_credentials to marked or all writes it emptywarn: the value of credentials.openAiApi.id of node OpenAI Chat Model is carried as written in the flow the draft carries: its format marks the field as a credential, and setting empty_credentials to marked or all writes it emptywarn: node OpenAI Chat Model reaches openai-chat-model, wired to the model socket of core/ai-agent/n8n as openai-chat-model, other than through that connection: an n8n @n8n/n8n-nodes-langchain.lmChatOpenAi node reaches the part at the address the stored credential it selects, or its own parameters, give; the platform delivers this connection as OPENAI_BASE_URL and OPENAI_API_KEY, but an n8n workflow reads a variable of the platform's environment only through an expression reading $env, which the platform refuses while values.allow_env_access_in_nodes is false, the value the draft leaves it at; setting it true lets every workflow, and every user who can edit one, read every variable of the platform's environment, the delivered credentials includedmade no choice for When chat message received (@n8n/n8n-nodes-langchain.chatTrigger)made no choice for AI Agent (@n8n/n8n-nodes-langchain.agent)mapped OpenAI Chat Model (@n8n/n8n-nodes-langchain.lmChatOpenAi) to core/ai-model/openai as a reference, HIGH at 0.9143made no choice for Simple Memory (@n8n/n8n-nodes-langchain.memoryBufferWindow) warning: node "n8n" (provider "compose"): artifact "n8n-flow.compose-fragment.yaml": skipped provenance label injection — the fragment declares no compose service. Compose carries build provenance as service labels, so a fragment contributing only top-level networks, volumes or configs carries none; the services this component emits elsewhere carry the full set.Pull complete: <workspace>/release.lock (entities=8, source_artifacts=0, external_inputs=0)
mapped行表明,OpenAI Chat Model 节点成为标准库的 OpenAI 模型core/ai-model/openai,以引用而非起草的方式出现,因为它以 0.9143 在高层级匹配:一个独立的组件,连接到平台的model插槽。made no choice行表明,触发器、代理和记忆保留在工作流内部,由 n8n 自己运行。- 前两条
warn行指出了触发器和模型节点所选的已存储凭据的标识符,n8n 将它们标记为凭据。它们是引用,而不是机密,并按原样保留。 - 第三条
warn行需要仔细阅读:模型节点使用它所选的已存储凭据访问 OpenAI,而不是通过草稿所接好的连接。平台将该连接传递到 n8n 的环境中,而当 Aggregate 将values.allow_env_access_in_nodes保持为false时(草稿正是如此),n8n 会拒绝工作流读取其环境。将其设为true会让每个工作流以及每个能编辑工作流的人都能读取平台的每个变量,包括所传递的密钥。因此,工作流所用的密钥是 n8n 存储的那个,如运行所示。 - 最后两行是拉取。没有剩下需要回答的内容,因此导入拉取了所起草 Release 的依赖项,与
aggrega pull的做法相同,并写入了release.lock;下面的构建不再需要其他任何东西。warning行构建时也会打印,验证与构建对其进行了说明。
答案文件指定了一个本次导入并未请求的 Secret:导入不会为它留下任何空项,因此不应用任何答案,并保持文件原样。
它写出的内容
该 Aggregate、Release 和 Manifest 命名为 imported/support-agent,取自工作流自身的名称 Support agent,缩减为 support-agent——没有名称的工作流按其文件命名——位于导入器的 target_namespace 设置所设定的命名空间下,除非你另行设置,否则该命名空间为 imported(设置)。
aggregate.yaml——标准库 n8n 平台 core/ai-agent/n8n 的一个实例,按导出时的原样承载该工作流(此处省略了其大部分内容),以及连接到其 model 插槽的模型:
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: imported/support-agent version: 0.1.0 description: Draft Aggregate imported from a source in the n8n format.spec: components: n8n: type: core/ai-agent/n8n values: workflow_id: 'sQ4vT8nKp2LmX7bR' flow_definition: | { "id": "sQ4vT8nKp2LmX7bR", "name": "Support agent", [… omitted: the rest of the workflow, as exported] } uses: model: openai-chat-model: target: openai-chat-model # For the compose target, the lines below declare credential on openai-chat-model: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none. features: credential: type: core/secret-value values: key: OPENAI_API_KEY # swap to core/ai-model/azure-openai (score 0.4125) by setting type: core/ai-model/azure-openai openai-chat-model: type: core/ai-model/openai values: model: |- gpt-4o-miniworkflow_id 是导出为该工作流指定的标识符。模型是 core/ai-model/openai,并带有节点所选的模型 gpt-4o-mini;其上方的注释指出了目录中与该节点相似的另一个 Component 及其得分。平台向模型提供的 OpenAI 密钥在连接上声明,并带有它在 n8n 环境中所用的变量 OPENAI_API_KEY;Release 说明了它的来源。
release.yaml——该 Release,它使用该 Manifest 部署该 Aggregate:
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: imported/support-agent # environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to. environment: development version: 0.1.0 description: Draft Release imported from a source in the n8n format.spec: aggregate: imported/support-agent manifest: imported/support-agent components: n8n: infra: # The image running core/ai-agent/n8n, at the version this importer drafts, which the catalog's Recipes for it are known to run; the import does not raise or lower it to follow the source. image: "n8nio/n8n:1.110.1" # Published on this machine's loopback address, 127.0.0.1: reachable from this machine only, by any process running on it. Delete this line to keep the service internal. published_port: 5678 uses: model: openai-chat-model: features: credential: type: core/secret-value infra: # Attached by reference, never as a value: the credential n8n presents to openai-chat-model on its model connection, read from the variable OPENAI_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value. origin: "${OPENAI_API_KEY}" openai-chat-model: {}environment为development,这是一个默认值,其上方的注释说明应将其改为该 Release 所部署到的环境。- 镜像是 n8n 1.110.1,即目录中 n8n 的 Recipes 所运行的版本。
published_port为 5678,即 n8n 提供服务的端口,因此编辑器在你的机器上通过http://127.0.0.1:5678响应。正如其注释所述,这台机器上的任何进程都可以在那里访问它,其他任何东西都不能;删除这一行即可让 n8n 只位于栈网络上。5678 以外的published_port需要在旁边加上infra.external_base_url: http://127.0.0.1:<published_port>,否则 n8n 会以localhost:5678报告其编辑器和 webhook 地址。- 密钥是一个变量引用
${OPENAI_API_KEY},Docker Compose 会在栈启动时从你的 shell 中填入该值。标准库的 OpenAI 模型是托管服务,与其建立的连接必须携带凭据,因此即使工作流从 n8n 的存储中读取其密钥,Release 仍会附加一个凭据。
manifest.yaml——平台和模型的 Compose Recipes,以及将密钥的变量引用按原样写入 Compose 文件的实现:
apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: imported/support-agent version: 0.1.0spec: mappings: components: type: core/ai-agent/n8n: compose/n8n core/ai-model/openai: compose/openai features: type: core/secret-value: compose/dotenv-secret.aggrega-import.json 记录了导入所写入的内容,供之后的 aggrega import --sync 读取;release.lock 按版本和摘要锁定该 Release 所解析到的每个目录实体。
验证并构建
aggrega validate --release release.yamlaggrega build --release release.yaml

验证打印:
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)release dependency validation passed: release.yaml (schema-pillar + dependency pillars)以及构建,其中 <workspace> 代表包含草稿的文件夹:
warning: node "n8n" (provider "compose"): artifact "n8n-flow.compose-fragment.yaml": skipped provenance label injection — the fragment declares no compose service. Compose carries build provenance as service labels, so a fragment contributing only top-level networks, volumes or configs carries none; the services this component emits elsewhere carry the full set. notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)[… omitted: a total build time, which differs per run]Build completed: 1 file written to <workspace>/distwarning 行涉及 Compose 文件中承载工作流的部分,即一个顶层 configs 条目,它没有可供放置构建标签的服务。notice 行仅为提示:该机密 Feature 接受来自 Aggregate 的 values 或 Release 的 infra 的 origin,而该提示报告有一个叶子在两处都有声明。两者都不改变结论。
dist/compose/docker-compose.yaml 包含 n8n,以及一个在 n8n 启动前导入工作流的服务:
services: n8n: image: n8nio/n8n:1.110.1 environment: OPENAI_BASE_URL: https://api.openai.com/v1 OPENAI_API_KEY: ${OPENAI_API_KEY} N8N_BLOCK_ENV_ACCESS_IN_NODE: "true" ports: - 127.0.0.1:5678:5678 [… omitted: the labels the build writes on every service, naming the Aggregate, the component, the environment and the compiler's version] volumes: - type: volume source: n8n--data target: /home/node/.n8n networks: - compose depends_on: n8n--import-flow: condition: service_completed_successfully [… omitted: the service's health check] n8n--import-flow: image: n8nio/n8n:1.110.1 command: - import:workflow - --input=/flows/workflow.json entrypoint: - n8n [… omitted: the labels the build writes on every service] volumes: - type: volume source: n8n--data target: /home/node/.n8n networks: - compose restart: "no" configs: - source: n8n-flow target: /flows/workflow.json工作流通过 n8n import:workflow 进入 n8n,它在每次栈启动时都会在同一个数据卷上、先于 n8n 本身运行。N8N_BLOCK_ENV_ACCESS_IN_NODE 为 "true",即 n8n 阻止工作流读取其环境的设置,因为 Aggregate 将 allow_env_access_in_nodes 保持为 false。因此 OpenAI Chat Model 节点从 n8n 自己的凭据存储中读取密钥,就像聊天触发器读取其用户名和密码一样,而下文的运行步骤会将两者都存入其中。n8n 的 Compose Recipe 仅在 Release 于 n8n 的 infra 中设置了 published_port 时才在你的机器上发布端口,并且只发布在回环地址 127.0.0.1 上;未设置时,只能在栈网络上访问该服务。
借助 AI 助手
配置了 Aggrega 工具的 AI 助手也可以完成同样的操作:将下面的提示词粘贴给它。
只使用 Aggrega 工具,不要自己创建任何文件夹。如果工作区文件夹中还没有 `import-n8n` 文件夹,调用一次 `scaffold` 工具,将 `example` 设为 `import-n8n`,不设 `dir`:它会将示例写入新的 `import-n8n` 文件夹,其中的 `source` 文件夹包含本页导入的内容。然后调用 `import` 工具,将 `workspace_root` 设为 `import-n8n/source`,`source` 设为 `support-agent.json`,`target` 设为 `compose`:它从 `support-agent.json` 旁边的 `import-answers.yaml` 读取所需的答案,将草稿写入 `import-n8n/source`,并拉取它们所需的内容。然后调用 `validate` 工具,将 `workspace_root` 设为 `import-n8n/source`,`release` 设为 `release.yaml`;再调用 `build` 工具,将 `workspace_root` 设为 `import-n8n/source`,`release` 设为 `release.yaml`,`write` 设为 true。告诉我构建写入了哪些文件;它们位于 `import-n8n/source/dist/` 下。在 VS Code 中打开
安装 适用于 Visual Studio Code 的 Aggrega 扩展 后,在 VS Code 中打开导入写入草稿的文件夹 import-n8n/source。该文件夹包含一个 Release,即起草的 release.yaml,因此编辑器会为你选中它,并在你编辑草稿时对照该 Release 检查草稿,将发现的问题标记在文件中和“问题”面板中。命令面板中的 Aggrega: Show topology graph 会绘制 Release 的组件及其之间的连接。Aggrega: Build、Aggrega: Preview build 和 Aggrega: Pull 作用于同一个 Release,并且每一个也是活动栏中 Aggrega 视图的 Commands 面板上的按钮;Build 会将其文件写入该文件夹的 dist/。在 Visual Studio Code 中使用 Aggrega 介绍了其余内容。
运行
n8n 按标识符从自己的存储中读取工作流所选的两个凭据:OpenAI 密钥位于 Rb7nW2xQ9kT4mZ1c 下,聊天的用户名和密码位于 Vx3mQ8rLb2Nk7Tz5 下。n8n 自己的命令行会从一个文件中以这些标识符存储它们。将它们连同你自己的值写入 credentials.json:
[ {"id": "Rb7nW2xQ9kT4mZ1c", "name": "OpenAI account", "type": "openAiApi", "data": {"apiKey": "your OpenAI key"}}, {"id": "Vx3mQ8rLb2Nk7Tz5", "name": "Chat basic auth", "type": "httpBasicAuth", "data": {"user": "a user of your own", "password": "a password of your own"}}]按照起草的 Release 读取密钥的方式,在你的 shell 中设置密钥,然后启动栈:
export OPENAI_API_KEY='your OpenAI key'docker compose -p support-agent -f dist/compose/docker-compose.yaml up -d --wait-p 用于为项目命名,正如导入如何运行的运行步骤所解释的那样。--wait 会在 n8n 报告健康后返回,此时导入工作流的服务已经运行并退出。将凭据复制到 n8n 的容器中,导入它们,然后删除该副本:
docker compose -p support-agent -f dist/compose/docker-compose.yaml exec -T n8n sh -c 'umask 077; cat > /tmp/credentials.json' < credentials.jsondocker compose -p support-agent -f dist/compose/docker-compose.yaml exec n8n n8n import:credentials --input=/tmp/credentials.jsondocker compose -p support-agent -f dist/compose/docker-compose.yaml exec n8n rm /tmp/credentials.json[… omitted: n8n's notices about its settings file's permissions, error tracking and deprecated settings]Successfully imported 2 credentials.n8n 现在已保存这两个凭据,因此请删除 credentials.json:
rm credentials.json然后激活工作流,并重启 n8n 以使激活生效:
docker compose -p support-agent -f dist/compose/docker-compose.yaml exec n8n n8n update:workflow --id=sQ4vT8nKp2LmX7bR --active=truedocker compose -p support-agent -f dist/compose/docker-compose.yaml restart n8n当 docker compose -p support-agent -f dist/compose/docker-compose.yaml ps n8n 再次显示 n8n 为 (healthy) 后,docker compose -p support-agent -f dist/compose/docker-compose.yaml logs n8n 会显示 Activated workflow "Support agent" (ID: sQ4vT8nKp2LmX7bR)。
测试
打开 http://127.0.0.1:5678,即 published_port 发布的地址:n8n 的编辑器在首次访问时要求创建所有者账户,然后显示 Support agent。
聊天触发器只接受带有上面所存储的用户名和密码的消息;没有它们时,它会回复 HTTP/1.1 401 Unauthorized 和 Authorization is required!,密码错误时则回复 HTTP/1.1 403 Forbidden。将两者放在 CHAT_USER 和 CHAT_PASSWORD 中后,curl 会从其标准输入读取它们,因此它们不会出现在任何命令行上:
printf 'user = "%s:%s"\n' "$CHAT_USER" "$CHAT_PASSWORD" | curl --config - -sS -i -X POST \ http://127.0.0.1:5678/webhook/a3c9e1f2-4b5d-4e6f-8a7b-9c0d1e2f3a04/chat -H 'Content-Type: application/json' \ -d '{"action": "sendMessage", "sessionId": "s1", "chatInput": "In one short sentence: what does a support plan cover?"}'HTTP/1.1 500 Internal Server Error[… omitted: the response's other headers]
{"message":"Error in workflow"}本次运行为 OpenAI 密钥存储了占位值,因此工作流在调用模型时停止。n8n 会保留这次执行,编辑器将其列在工作流的执行记录下,其中包含 OpenAI 的拒绝:Incorrect API key provided: sk-place*****************-key. 使用你的密钥时,回复是 HTTP/1.1 200 OK 和代理的回答,形式为 {"output": "…"}。
在 Kubernetes 上,应用 在 Kubernetes 上 所述的构建后,n8n 将数据保存在一个与其 pod 生命周期相同的卷中,因此新 pod 启动时不含你存储的内容;请改为在正在运行的实例上存储凭据并激活工作流。按照 运行 中的方式编写 credentials.json,在你应用构建的命名空间中通过 kubectl exec 从其标准输入导入它,之后将其删除:
kubectl exec -i -n <namespace> deploy/n8n -- n8n import:credentials --input=/dev/stdin < credentials.jsonDefaulted container "main" out of: main, import-flow (init)[… omitted: n8n's notices about its settings file's permissions, error tracking and deprecated settings]Successfully imported 2 credentials.将一个本地端口转发到 n8n 的 Service n8n-default,并让该命令保持运行:
kubectl port-forward -n <namespace> svc/n8n-default 5678:5678在另一个终端中,通过 n8n 的 API 设置所有者账户,这会让你登录并将会话保存在 cookies.txt 中,然后激活工作流:
curl -sS -c cookies.txt -X POST http://127.0.0.1:5678/rest/owner/setup -H 'Content-Type: application/json' \ -d '{"email": "owner@example.com", "firstName": "Your", "lastName": "Name", "password": "a password of your own"}'curl -sS -b cookies.txt -X PATCH http://127.0.0.1:5678/rest/workflows/sQ4vT8nKp2LmX7bR \ -H 'Content-Type: application/json' -d '{"active": true}'第二个回复是工作流,其中带有 "active":true。随后上面的聊天消息会原样通过同一地址到达它;本次运行得到了同样的 {"message":"Error in workflow"},执行记录中也是同样的拒绝。
使用下面的命令停止栈。-v 还会删除 n8n 的数据卷,连同其中存储的凭据和激活状态:
docker compose -p support-agent -f dist/compose/docker-compose.yaml down -v在 Kubernetes 上
同一个工作流可以使用 helm 目标为 Kubernetes 导入。用于 Docker Compose 的草稿已位于 source 中,而导入从不覆盖其中的 Aggregate,因此请使用 --output-dir 将这些草稿生成到单独的文件夹中,然后从该文件夹验证并构建:
aggrega import support-agent.json --target helm --output-dir helmcd helmaggrega validate --release release.yamlaggrega build --release release.yaml草稿在目标不同之处有所不同。Manifest 将平台映射到 helm/n8n,将模型映射到 helm/openai,将密钥映射到 helm/k8s-existing-secret,后者从命名空间中已有的 Secret 读取密钥。Release 将密钥附加为 core/referenced-secret,并根据答案文件指定该 Secret,即 openai-api-key。
构建会在工作区根目录 source 下的 dist/helm/ 中写入普通的 Kubernetes 清单,从 helm 看即为 ../dist/helm/。在你要应用到的命名空间中创建该 Secret,将密钥保存在数据键 value 下,然后按照导入的运行方式中运行步骤的说明应用该文件夹。工作流仍然从 n8n 自身的存储中读取其凭据,在 Kubernetes 上由测试填充该存储。