连接配置字段说明

在连接器的 访问内容 分区点 添加访问 添加和维护凭证，无需凭证的地址也在同一分区里管理。新建和编辑使用同一套字段说明；各服务特有的字段见服务与凭证配置里对应的页面。

推荐与自定义

选择服务预设后，表单默认使用 推荐配置：凭证类型和推荐的访问目标已预填，只需填写凭证值和服务实例的必要信息后保存。名称会自动填写，可以在 更多设置 里修改。

需要调整访问地址、路径或方法时，切换到 自定义；内网路由要求在推荐配置的 更多设置 里也能修改。推荐配置与自定义可以随时切换，表单空白或没有填完也能切换，已填内容不会丢失；保存时只按当前选中的方式校验和保存。

首次切换到自定义时，已填写的推荐配置会展开为目标字段，未填写的保持为空。返回上一步不会丢失同一服务的草稿；切换服务或取消未保存的配置前会有提示。

保存成功后，这份凭证在 访问内容 表里显示为 有效（快到期的显示 临近到期，OAuth2 授权码凭证登录前显示 未授权，见连接器的状态）。这只表示配置已保存，接着按验证与排错请 ZAI 发一次只读请求。

名称

名称用于区分同一个连接器中的访问能力。推荐配置已自动填写名称；多份同类服务可以按用途或实例区分。不要在名称中填写凭证值。

凭证类型

凭证类型在 添加访问 选择服务时决定：优先在 服务预设 里找对应的服务；没有时在搜索框输入名称或展开 自定义认证 分组，选择与目标服务官方要求一致的类型：

• Bearer Token：填原始 Token，见Bearer Token。
• 用户名与密码 / PAT：填账号和密码或 PAT，见用户名与密码 / PAT。
• 自定义请求头：填服务要求的请求头名称和值，见自定义请求头。
• OAuth2 Client Credentials：填 Client ID、Client Secret 与 Token endpoint，见OAuth2 Client Credentials。

需要对请求签名的云服务（如阿里云、火山引擎、腾讯云）使用各自专用的凭证类型，填法与同名的服务预设相同。

已创建的凭证不能切换凭证类型；需要换一种类型时，新建一份凭证。

协议

推荐配置一般只用 HTTPS；Nacos 可以填 HTTP 地址，但必须经网络隧道访问，见Nacos。自定义目标可以选 HTTPS、HTTP、WSS 或 WS。

协议必须与实际发出的请求一致。选择 HTTP 或 WS 时，凭证会以明文发送到目标服务，只在网络隧道等受控网络中使用。WebSocket 目标只使用 GET 握手。

端口

填写服务实际监听的端口。HTTPS / WSS 通常为 443，HTTP / WS 通常为 80；PostgreSQL 通常为 5432，MySQL 通常为 3306，MongoDB 通常为 27017，Redis 通常为 6379，SSH 通常为 22。非标准端口以该服务的管理员提供的连接信息为准。

路径匹配

路径以 / 开头，不填写 query 或 fragment。完整路径 只匹配自身；路径前缀 匹配自身及以 / 分隔的子路径，例如 /projects/42 不会匹配 /projects/420。除根路径外，前缀末尾不加 /。

通配路径 中的 * 匹配单个路径段内的字符，** 可跨越 /。匹配时区分大小写，并按 URL 编码后的路径比较；项目 ID 和项目路径不会自动互换。

请求路径里有 . 或 .. 段（包括写成 %2e 的）、以两个以上 / 开头或含反斜杠时，目标服务可能把它当成另一个路径处理。只要决定这次请求的凭证限定了路径（路径不是根路径 / 或 /**），平台就拒绝它，返回 egress-denied: ambiguous_request_target，请改用不含这些写法的路径。S3 兼容存储的凭证不受此限：对象名可以含 ..，签名按原样计算。

请求方法

自定义配置可在 请求方法 中填写 GET, POST 等 HTTP 方法，留空表示全部方法。方法限制不能代替目标服务账号或 Token 的权限：不少服务用 POST 完成查询，也有 GET 返回敏感信息。

内网路由要求

连接器指定了网络隧道时，其中的全部访问目标都经由这条隧道，不需要另外创建内网路由。

连接器没有指定网络隧道时，每个访问目标的 内网路由要求 决定怎样出网：

• 按沙箱配置的内网路由：匹配到生效沙箱配置里的内网路由时经由路由访问，否则直接访问。
• 必须经内网路由：必须有可用的内网路由匹配到目标，否则请求失败。

组织连接器的网络隧道只有组织 Owner 可以指定，见组织角色与权限；你自己的连接器由你本人指定。要给连接器指定网络隧道，在连接器详情页把鼠标移到名称上，点击名称旁出现的铅笔按钮，在编辑框的 网络隧道 里选择。内网路由在沙箱配置与网络隧道里添加。填写了公网域名，也不代表这个地址一定能从当前网络访问。

到期时间

到期时间是平台停止使用这份凭证的时间，可以留空。它只能在添加或替换凭证时设置：推荐配置下在 更多设置 里，自定义配置和 替换凭证 时在凭证值字段下方。表单标出所用的时区；遇到夏令时跳过或重复的钟点，请选择不会产生歧义的时间。

到期时间不会延长第三方凭证自身的有效期。第三方凭证提前过期或被撤销时，请求仍会失败。

不是每种凭证都有到期时间：使用自定义请求头的凭证（包括 GitLab、Linear、Datadog 与 API Key（x-api-key 请求头）），以及数据库和 SSH，都没有这一项。Git 仓库与 Kubernetes 的到期时间分别见Git 仓库和Kubernetes。

修改与替换

编辑名称或访问目标时不需要重新输入凭证值。要更换凭证值，在凭证的行菜单里选 替换凭证 并提交新值；已保存的值不会再显示。替换自定义请求头凭证时，请求头名称必须与原来一致。

编辑页 服务配置 中列出的参数（如 Region、Bucket、Token endpoint、允许的操作），以及 API Version、Bucket 访问方式，在创建时确定，不能修改；需要变更时新建凭证。

通过 服务预设 或 自定义认证 添加的凭证，要先 撤销凭证 才能 删除；原生资源 里的数据库和 SSH，以及 Git 仓库和 Kubernetes，可以直接删除。已撤销的凭证不能再编辑或替换。

请求规则

在自定义配置的 访问目标 中，每个目标地址下方的 请求规则 可以进一步限定哪些请求能使用这份凭证：把 限制方式 改为 按请求字段限制，再点 添加条件。每个条件选择 字段来源（请求头、查询参数或 JSON 正文），填写字段名称或路径，选择 匹配方式（等于、属于集合、数组非空且全部属于集合），再填写值。所有条件都要同时满足。

请求头和查询参数填写字段名，JSON 正文填写 /tenantId 这样的字段路径；值填写 JSON 字面量，例如字符串 "team-a" 或集合 [101, 102]。数组非空且全部属于集合 要求请求里的数组至少有一项，并且每一项都在集合里。

多份凭证同时匹配同一个请求、按同一目标匹配到多份时的规则也分不出先后时，这个请求会被拒绝；请调整各自的请求规则，避免重叠。

使用 JSON 正文条件时，平台要先读完整个请求正文才能判断是否使用这份凭证，正文过大的请求会失败；上传文件等大正文接口请改用请求头或查询参数条件。需要对请求签名的云服务凭证本身就要读取正文，改用这两种条件对它们无效。

ZAI 能看到连接器的使用指令和各目标的请求规则，看不到凭证值；实际访问时平台仍逐次检查授权，见ZAI 实际看到什么。阿里云 OSS 与火山引擎 DataFinder 用各自的范围设置，见对象范围与分析查询范围。

验证与排错

控制台不提供测试请求，保存成功也不代表凭证可用。保存后，在这个连接器生效的聊天里，请 ZAI 用它发一次不写入业务数据的最小只读请求：

• 连接器的 使用范围 包含某个 Channel、它所在的 Workspace 或 整个组织 时，在这样的频道或群聊里 @zai 提出请求。
• 连接器授权给了你或 全体成员，或者是你自己的连接器（使用范围含 我的个人范围）时，在你和 ZAI 的私信里直接说。

例如：「用 GitLab 连接器读取 group/project 最近 5 次流水线的状态，只读，不要修改任何内容」。每个服务页的「验证」一节给出了该服务适合的只读请求。

请求成功后，再确认三件事：请求的地址、路径和方法确实落在这份凭证的访问目标里；内网服务经由预期的网络隧道或内网路由到达；返回内容属于预期的账号、组织或实例，账号权限足够完成任务。

凭证行菜单和凭证编辑页底部的 检查规则 只核对配置：它按凭证的第一条访问目标拼一条示例请求，说明这条请求会不会命中这个连接器里的凭证、请求规则是否允许。判定按连接器里已保存的凭证做：编辑页上的示例请求取自表单里的第一条访问目标，但未保存的修改不参与判定。它不读取凭证值、不访问目标服务、不解析 DNS，也不看使用范围、到期时间、网络隧道和内网路由，其他连接器和域名也不在其中，所以不能代替上面的真实请求：显示会命中时，真实请求仍可能失败；显示不会命中任何凭证时，请求仍可能由域名或其他连接器放行。

请求失败时，按返回结果排查：