Celigo 扩展代码需要自有计算或合规隔离时：创建并绑定…

当 Celigo 托管 JavaScript runtime 不足以运行扩展代码，或要运行自定义 connector wrapper 时，用 stack 把 hook/wrapper 的执行派发到自托管 server 或 AWS Lambda。

适用场景

解决思路

1. 先确认是否真的需要 stack：默认不需要；只有需要库/原生依赖/更多内存/更长执行、合规/安全要求扩展代码及其接触的数据不离开你的环境、或自定义连接器 wrapper 时才创建；常规 hook 做转换/过滤/丰富记录继续用 Celigo 托管 JavaScript runtime。
2. 若需要的是访问防火墙后的私有数据库或应用，不要创建 stack；那是连通性问题，应使用 on-premise agent。
3. 选择 stack 类型：server 是自托管、常开的 HTTP endpoint，由你运行和打补丁；lambda 是 Celigo 调用的 AWS Lambda 无服务器函数；按团队已有基础设施和运营方式选择，二者没有优劣。
4. 为 server 配置：server 配置块必填 hostURI（Celigo 调用的可达 HTTP(S) endpoint）；可选 ipRanges allow-list；systemToken 自动生成，不要设置。
5. 为 lambda 配置：lambda 配置块必填 accessKeyId、secretAccessKey、awsRegion、functionName；可选 language，默认 Node.js，也可为 C#、Java、Other；awsRegion 是枚举（如 us-east-1、us-west-2、eu-west-1、eu-central-1、ap-southeast-1 等）；functionName 可为 Lambda 函数名或完整 ARN。
6. 每个 stack 必填 name 和 type；framework 必须设为 twoDotZero，它是唯一支持的版本。
7. 检查是否已有可复用 stack：运行 celigo stacks list；运行 celigo account search "stack"；运行 celigo account search "<keyword related to the extension>"。
8. 创建 server stack（自动生成 systemToken，不要包含 systemToken）：运行 echo '{"name":"Order Enrichment Server","type":"server","framework":"twoDotZero","server":{"hostURI":"https://ext.example.com"}}' | celigo stacks create。
9. 创建带 IP allow-list 的 server stack：运行 echo '{"name":"Order Enrichment Server","type":"server","framework":"twoDotZero","server":{"hostURI":"https://ext.example.com","ipRanges":["203.0.113.0/24"]}}' | celigo stacks create。
10. 创建 lambda stack：通过本地未跟踪文件输入 AWS secret，运行 celigo stacks create < lambda-stack.json；不要将真实 secret 粘贴到聊天中。
11. lambda-stack.json 示例：包含 name、type、framework、lambda.accessKeyId、lambda.secretAccessKey、lambda.awsRegion、lambda.functionName、lambda.language；在示例中用占位符，真实 key 只在本地文件或 UI 中提供。
12. server 认证：创建时生成 systemToken；从 UI 的 Show token 或 GET /v1/stacks/{id}/systemToken 获取未掩码值；在每个运行扩展代码的服务器上设置为 INTEGRATOR_EXTENSION_SYSTEM_TOKEN 环境变量。
13. 轮换 server systemToken：使用 DELETE /v1/stacks/{id}/systemToken；旧 token 立即失效，然后重新获取新 token。
14. lambda 认证：accessKeyId/secretAccessKey 对应的 AWS IAM 用户必须拥有目标函数的 lambda:InvokeFunction 权限；awsRegion 必须与函数部署区域匹配。
15. 将 hook 指向 stack：在 export/import 的 hook definition 中加入 _stackId（与 _scriptId 和 function 并列），让该 hook 派发到 stack。
16. 将 wrapper connection 指向 stack：在 wrapper 类型的 connection 上设置 _stackId，指向实现该连接的服务器端 JavaScript 的 stack；独立 wrapper 连接表单要求这样做；wrapper stack 必须暴露 ping 函数，以便 Celigo 健康检查连接。
17. 验证引用：运行 celigo stacks get <id>；运行 celigo account dependencies stack <id>；或使用 GET /v1/stacks/{id}/dependencies 列出指向该 stack 的 hooks 和 wrapper connections。
18. CRUD CLI：运行 celigo stacks list；celigo stacks get <id>；celigo stacks create < stack.json；celigo stacks update <id> < stack.json；celigo stacks delete <id> [-y]。
19. 发现已有 stack：运行 celigo account search "<keyword>"。
20. 无专用 CLI 子命令时使用 UI/API：GET /v1/stacks/{id}/systemToken 获取 server system token；DELETE /v1/stacks/{id}/systemToken 轮换 server system token；GET /v1/stacks/{id}/dependencies 列出 dependents。
21. 提交前检查：确认 stack 确有必要（更重/专用代码、合规、或自定义 connector wrapper），不是托管运行时能处理的常规 hook。
22. 提交前检查：根据团队运营基础设施的位置选择正确的 type（server vs lambda）。
23. 提交前检查：framework 设为 twoDotZero。
24. 提交前检查：server 的 hostURI 可通过 HTTPS 访问；若设置 ipRanges，要包含 Celigo 的出站 IP。
25. 提交前检查：server 获取而非设置 systemToken，并配置为 INTEGRATOR_EXTENSION_SYSTEM_TOKEN。
26. 提交前检查：lambda 提供 awsRegion、functionName、AWS keys，且 IAM 用户有 lambda:InvokeFunction。
27. 提交前检查：不要将 secret 粘贴到聊天或 tracked file；AWS secretAccessKey 仅通过 UI 或本地未跟踪文件输入。
28. 提交前检查：消费 hook（export/import hook 上的 _stackId）或 wrapper connection（_stackId）实际指向该 stack。
29. 提交前检查：验证 dependents，明确 stack 上到底运行什么。
30. 记住 stack 是运行时而不是代码：它本身不执行逻辑；只有 hook 或 wrapper 通过 _stackId 指向它时才派发执行；创建 stack 单独不会改变行为。
31. 记住大多数账户不需要 stack：hooks 默认在 Celigo 托管 JavaScript runtime 上运行；只有真实触发条件才升级到 stack。
32. 记住 server systemToken 自动生成，不要设置；通过 GET /v1/stacks/{id}/systemToken（或 UI）获取，存为 INTEGRATOR_EXTENSION_SYSTEM_TOKEN，必要时用 DELETE /v1/stacks/{id}/systemToken 轮换。
33. Secrets 处理：不要将 secret 粘贴到聊天；systemToken 和 AWS secretAccessKey 在响应中掩码为 ******；粘贴到有日志的对话即视为泄露，需轮换（回收 system token 或轮换 AWS key）并通过 UI 重新输入。
34. 不要将掩码值 ****** 写回作为真实凭证：secretAccessKey 是 write-only；要修改就发送真实值；要保持现有值就重新提供真实值或通过 UI 编辑；绝不持久化字面量 ******。
35. 更新 stack 时注意 PUT 会清除省略的可选字段：先 GET stack，修改，再 PUT 完整对象。
36. 记住 twoDotZero 是唯一支持的 framework 版本；没有其他有效值。
37. 记住 lambda 需要 lambda:InvokeFunction；functionName（名称或 ARN）必须存在于指定 awsRegion，且 language 必须匹配已部署函数。
38. 记住 stack != on-premise agent：不要创建 stack 来访问私有数据库；stack 是为你的代码提供计算，on-premise agent 是连通性。
39. 删除是软删除，进入 30 天 recycle bin；仍被 hooks 或 wrapper connections 引用的 stack 不能删除，必须先重新指向或移除引用。
40. 常见错误修复：422 missing_required_field on create——为所选 type 提供完整 config block；错误的 field 会指出缺失路径。
41. 常见错误修复：422 dependency-conflict on delete——先重新指向或移除 dependents；用 GET /v1/stacks/{id}/dependencies 列出。
42. 常见错误修复：Hook 或 wrapper 仍在 Celigo runtime 上运行——在 hook（export/import）或 wrapper connection 上设置 _stackId。
43. 常见错误修复：systemToken 返回 404 "Stack of type server not found."——system token 只存在于 server stack；验证 _id 和 type。
44. 常见错误修复：你的 server 调用失败/返回 401——通过 GET /v1/stacks/{id}/systemToken 获取当前 token，并设置 INTEGRATOR_EXTENSION_SYSTEM_TOKEN。
45. 常见错误修复：Lambda AccessDenied/未调用——授予 lambda:InvokeFunction，确认 region 与函数匹配，重新输入 AWS keys。
46. 常见错误修复：Wrapper connection 显示 offline——在扩展中实现 ping 函数；Celigo 会每小时以指数退避重新 ping 离线连接。

适用边界 · 注意事项

• 常规 hook 只做记录转换、过滤、丰富时，不需要 stack；继续使用 Celigo 托管 JavaScript runtime。
• 需要访问防火墙后的私有数据库或应用时，不要用 stack；应使用 on-premise agent 解决连通性。
• 大多数账户默认不需要 stack；没有更重/专用代码、合规要求或自定义 connector wrapper 等真实触发条件时不要创建。