在 Celigo 中配置连接与 iClient…

需要创建或编辑 Celigo connection（连接外部系统的凭据与配置对象）或 iClient（可复用 OAuth 凭据存储）时，按系统类型选型、配置认证、测试连通性并安全处理凭据。

适用场景

解决思路

1. 先识别目标系统：确定连接类型、认证方式和配置结构。
2. 按系统/环境命名连接，而不是按操作命名（如用 `Shopify - my-store` 而非 `Shopify - Customer Upsert`）；若同一系统有多个环境或实例，加入区分信息（店铺名、环境、账户 ID）。
3. 创建前先检查已有连接：用 `celigo account search "<application-name>"` 搜索账户、`celigo account dependencies connection <id>` 查看依赖、`celigo account lint` 查找离线/孤立连接、`celigo templates marketplace` 搜索模板、`celigo templates preview <id> --model Connection` 预览模板连接模型、`celigo connections list` 列出全部连接并按名称过滤；账户索引超过 4 小时会自动刷新，可用 `celigo account snapshot` 强制刷新。复用已有连接可避免重复凭据并共享并发。
4. 向用户展示连接选项时，过滤掉 `offline: true` 或 `status: "offline"` 的连接，只展示在线/活跃连接；若全部离线则说明并让用户决定。
5. 对 HTTP 连接先搜索预构建连接器：用 `celigo http-connectors list` 搜索 550+ 应用连接器、`celigo http-connectors get <id> --full` 查看认证配置与端点、`celigo tp-connectors list` 搜索贸易伙伴连接器；仅当无连接器或不满足需求时才手动配置。若存在连接器，在连接上设置 `http._httpConnectorId` 和 `http._httpConnectorVersionId`。
6. 检查全局 iClient：许多预构建连接器自带 Celigo 托管的全局 iClient。有则默认使用，设置 `http.auth.type: "oauth"`、`http.auth.oauth.useIClientFields: true` 和 `http._iClientId` 指向全局 iClient ID；不要因暂无实时凭据就退回静态 bearer token（`auth.type: "token"`），应使用正确 OAuth 结构并保存为 `offline: true`；仅当客户有自己的应用注册或全局 iClient 缺少所需 scope/consent 时才创建自定义 iClient。可通过账户中同连接器的可用连接查看其 `http._iClientId`，或用 `http-connectors get <id> --full` 检查连接器认证配置。
7. 按连接类型表选择 `type` 值并打开对应 schema 获取认证选项与必填字段；每个连接至少需要 `name`、`type` 和类型专属配置块（`http{}`、`netsuite{}`、`ftp{}` 等）。
8. 离线连接必须使用正确的认证结构：无实时凭据时（演示、占位、预置）仍配置最终会用的完整认证结构（OAuth 类型、iClient 引用、grant type 等）并保存为 `offline: true`，以便后续就地授权而无需重配；绝不用静态 token 认证替代 OAuth 连接。
9. 测试连接：用 `celigo connections ping <id>`；OAuth 连接先用 `celigo connections authorize <id>` 通过浏览器授权。
10. 使用 CLI 命令管理连接：`celigo connections list/get/create/update/delete`、`celigo connections ping <id>`、`celigo connections authorize <id> [--timeout <seconds>] [--print-url]`、`celigo connections enable-debug <id> [--duration <minutes>]`、`celigo connections disable-debug <id>`、`celigo connections debug-logs <id>`、`celigo integrations register-connections/deregister-connections`、`celigo flows replace-connection <flowId> <oldConnectionId> <newConnectionId>`。注意 `connections set` 和 `iclients set` 只应用 PATCH 白名单字段（如 `name`、`debugDate`、`debugUntil`，iClient 还有 `oauth2.failPath`），PATCH 不会重发 GET 返回的 `"******"` 掩码凭据，安全；非白名单字段会报错而非退回全量 PUT，需用 `update`（会防止提交掩码值）。
11. 提交前检查：名称描述系统/环境而非操作；`type` 匹配目标系统；存在类型专属配置块；凭据为真实值而非 GET 返回的 `"******"`；HTTP 已搜索预构建连接器；HTTP 连接器已设置 `_httpConnectorId` 和 `_httpConnectorVersionId`；OAuth 优先用全局 iClient；OAuth 的 `auth.type` 为 `"oauth"`（即使 `offline: true`）；NetSuite 用 `token-auto`（非废弃的 `basic`）；RDBMS 提供 host、port、database、user、password。
12. 避免常见陷阱：GET 会掩码凭据（密码/token/secret 返回 `"******"`），切勿将 GET 响应直接回传 PUT；PUT 会擦除省略字段，先 GET 再修改再 PUT 完整对象；OAuth 连接创建后需浏览器授权；`rest` 类型已废弃，新 REST 连接用 `http`；NetSuite `basic` 认证已废弃，用 `token-auto`；调试日志是连接级作用域；`_borrowConcurrencyFromConnectionId` 共享槽位时借用连接的 `concurrencyLevel` 被忽略；按系统而非操作命名连接；OAuth 连接器使用全局 iClient 而非静态 bearer token。
13. 处理常见错误：401 验证凭据或重新授权；403 检查目标系统用户/角色权限；422 类型无效用精确 `type` 值，缺字段补全必填项；ping 返回 offline 检查 host/URL、凭据、防火墙、VPN/agent；ECONNREFUSED/ETIMEDOUT 检查 host/port、DNS、防火墙，本地系统确认 `_agentId`；OAuth `invalid_grant` 重新授权；`"******"` 被保存为凭据说明回传了掩码值；429 启用自动恢复或降低 `concurrencyLevel`。
14. 凭据纪律：Celigo 要求每次更新连接都重新提交外部系统凭据（安全护栏）。聊天记录为明文，绝不在聊天中接受、请求或回显真实凭据。程序化更新时用占位值发送凭据字段以便非凭据变更（重命名、URL、并发）正常保存，然后告知用户在 Celigo UI 中重新输入真实凭据；每次更新（包括重命名）都要提示。若用户粘贴真实凭据，视为已泄露：先在外部系统轮换凭据（重新生成 API key、重置 OAuth 授权、轮换 SFTP 密码、吊销并重发证书对），再在 Celigo UI 用轮换后的值更新连接。
15. 在线/离线处理：连接为在线（凭据有效、目标可达）或离线（token 过期、API 变更、网络不可达、凭据轮换未更新、证书过期）；用 `celigo connections ping <id>` 探测。当流程失败根因是连接时，修复共享连接而非每个依赖流程——一个连接支撑多个消费者，连接恢复后所有依赖立即恢复。
16. 并发队列模型：每个连接有独立 FIFO 队列，两个流程共用同一连接则共享一个队列，一个流程触及多个连接则进入多个队列。`concurrencyLevel` 设置队列并行处理数，匹配外部系统 API 治理限制（如允许 25 并行则设 25）。队列深度是连接级、由所有消费者共同拥有，不要归因于单个流程。吞吐症状通常指向连接：命中速率限制则 `concurrencyLevel` 过高或未启用自动恢复；流程慢则 `concurrencyLevel` 过低；流程互相饿死则高流量流程共享队列，按优先级拆分为独立连接；需限流则降低对应连接的 `concurrencyLevel`。
17. 自动恢复速率限制错误：新连接默认启用，按适配器有目标并发（HTTP 默认 25，FTP 默认 1，可按连接调整）。遇速率限制错误（429 或等效）时：降到并发 1 并等待约 1 分钟后重试；每次再遇速率限制错误等待翻倍（2、4、8……最多 1024 分钟），最多十一次尝试、累计约 34 小时退避；成功重试后并发逐步回升（1→2→4→8……），回升中遇速率限制错误则从并发 1 重启；若完整序列仍遇速率限制错误，平台自动禁用该设置，需手动重新启用，期间速率限制错误进入 Open errors。恢复的记录进入 Resolved errors 标签，并发调整出现在连接审计日志。运行中禁用自动恢复会取消恢复（流程按目标并发继续，未解决的速率限制错误进入 Open errors），更改目标并发立即对后续重试生效。
18. 借用并发：多个连接指向同一系统但系统有账户级速率限制时，在借用连接上设 `_borrowConcurrencyFromConnectionId` 指向父连接，父连接 `concurrencyLevel` 设为系统限制；所有借用者共享该预算（借用者自身 `concurrencyLevel` 被忽略）。借用连接无自己的自动恢复开关，由父连接的设置控制。
19. 线级调试日志：当在线/离线无法解释失败时，用 `celigo connections enable-debug <id> [--duration <minutes>]`（默认 15 分钟，最多约 1 小时）、`celigo connections debug-logs <id>`、`celigo connections disable-debug <id>`。捕获连接的所有请求/响应并掩码敏感字段，每条含 ISO 日期、配对请求响应的 UUID、使用连接的资源类型和 id、请求或响应体（按共享 UUID 匹配）。日志仅在数据实际流动时出现，保留 24 小时。调试是连接级作用域。DynamoDB、MongoDB、wrapper 连接器不支持，改用测试模式流程运行、模拟数据或目标系统日志。高流量流程（数百万记录）会明显变慢，仅在代表性测试运行中短暂启用或缩小源导出条件后关闭。
20. iClient 使用判断：预构建连接器有全局 iClient 则用全局 iClient（设 `http._iClientId`）；HTTP OAuth2 用自定义应用注册则创建自定义 iClient 并设 `http._iClientId`；Salesforce `packagedOAuth: false` 则存 Connected App 凭据；NetSuite `authType: "token-auto"` 则存集成记录的 consumer key/secret；HTTP 预构建连接器无全局 iClient 则视连接器认证要求而定；token 认证（非 OAuth）则凭据直接放连接上；数据库、FTP 或非 OAuth 连接则不需要。
21. 构建 iClient：先确定 `provider`（Google 用 `google`、Salesforce 用 `salesforce`、Azure AD/Microsoft 用 `azureoauth`、NetSuite TBA 用 `netsuite`、Shopify 用 `shopify`、自定义 OAuth2 用 `custom_oauth2`、eBay 用 `ebay` 或 `ebay-xml`）；用匹配 provider 的 schema 构建，至少需要 `provider` 和匹配的 provider 专属配置块（`oauth2{}`、`netsuite{}`、`salesforce{}` 等）；创建后在连接上设置 `_iClientId`（`http._iClientId`、`netsuite._iClientId`、`mcp._iClientId`），OAuth 连接用 `celigo connections authorize <connectionId>` 授权。
22. `custom_oauth2` 仅用于无命名 provider 的 OAuth2 API：提供 `clientId`/`clientSecret`、`scope`（+ `scopeDelimiter`）和 `redirectUri`（必须与 provider 注册的回调完全一致）、`grantType`（`authorization-code`、`client-credentials` 或 `password`）、token/refresh/revoke 端点、`clientCredentialsLocation`（basic-auth 头或请求体）、PKCE 设置，以及必需的 `validDomainNames`（列出 auth/token/revoke URL 的每个唯一域名，仅主机名无 scheme 或 path）。
23. JWT 认证：需要 JWT 断言时设 `enableJWT: true` 并填充 iClient 的 `jwt` 块；Salesforce JWT bearer 提供 `privateKey`；Handlebars 模板用 `{{{iClient.jwt.token}}}` 引用签名 token；`clientSecret` 和私钥是凭据，遵守凭据纪律。
24. 一个 iClient 多个连接：iClient 是应用注册而非身份，持有 `clientId`/`clientSecret`，而每用户 access/refresh token 在连接上。默认一个 iClient 多个连接——注册应用一次存为 iClient，所有应作为该应用认证的连接通过 `_iClientId` 指向它。仅当连接需要不同注册应用（不同开发者账户、不同 scope 授权、独立速率限制池、环境硬隔离）时才用不同 iClient。
25. iClient 就地更新 vs 新建：密钥轮换（provider 重发或泄露）则就地更新现有 iClient，所有连接自动获取新密钥；应用本身变更（不同注册应用、不同开发者账户、新 client ID）则新建 iClient，旧 iClient 仍可用于旧应用的连接。
26. iClient CLI：`celigo iclients list/get/create/update/delete`。
27. iClient 陷阱：`_httpConnectorId` 不可变，链接后无法更改，需不同连接器则新建 iClient；`provider` 决定有效字段，provider 与配置块不匹配会静默忽略错误块；Handlebars 用 `{{{iClient.fieldName}}}` 访问 `encrypted` 或 `unencrypted` 对象中的值；`custom_oauth2` 必须提供 `validDomainNames`；删除 iClient 会破坏引用它的连接，删除前检查引用；编辑共享 iClient 凭据影响所有引用连接，更改前确认依赖关系。

适用边界 · 注意事项

• 不涉及 Celigo 平台或不需要配置外部系统连接/iClient 的场景。
• 没有 Celigo 账户或 CLI 工具（`celigo` 命令）时无法执行这些操作。
• 目标系统不在 Celigo 支持的连接类型或 provider 列表中时，无法按本经验配置。