连接器

连接器把一个用途所需的访问能力放在一起。例如“项目发布”连接器可以包含代码托管 API 和制品服务的凭证，以及只读的发布数据库，不必把凭证分发给每位成员。ZAI 通过连接器访问业务系统，凭证值由 Z Tag 在请求时带上，不会放进 ZAI 的沙箱，见ZAI 实际看到什么。连接器在哪些群里可用、授权给哪些成员，由它的 使用范围 决定，见范围设置。

谁可以做：组织 Owner 新建、改名和删除组织连接器，修改它的使用指令、网络隧道和插件，并设置使用范围。组织 Admin 可以在已有的组织连接器里添加和维护凭证、域名、Database、SSH、Git 仓库与 Kubernetes。成员可以在 我的资源 → 连接器 新建只供自己使用的连接器，操作与本页相同，见在控制台管理自己的资源。

连接器包含什么

连接器详情是同一页上的八个分区，页头的分区条可以跳到任一分区（宽屏粘在页顶，窄屏收成「跳到分区」下拉），切换分区不会重新加载页面，也不会丢正在写的内容：

1. 概览：这个连接器现在能不能用、缺什么，以及下一步做什么。
2. 使用指令：告诉 ZAI 它的用途、什么时候用和有哪些限制，见怎样写使用指令。
3. 访问内容：ZAI 能访问什么。凭证、域名、Git 仓库、Kubernetes 与插件都在同一张表里，用表上方的类型筛选只看某一类：
   • 凭证：访问业务系统用的令牌、密码、密钥或证书（凭证值），加上它的访问目标：协议、主机、端口、路径和 HTTP 方法；数据库和 SSH 的账号也在这里添加。ZAI 访问落在访问目标里的地址时，由 Z Tag 自动带上凭证值。还可以按请求头、查询参数或 JSON 正文字段进一步限定哪些请求能用这份凭证（OSS、DataFinder 另有对象范围和分析资源范围），见请求规则。
   • 域名：无需凭证即可访问的地址，按协议、地址和端口放行，不带凭证。
   • Git 仓库：ZAI 在任务里拉取和推送代码用的仓库，单独配置 HTTPS 或 SSH 凭证和读写权限，包括 LFS 的下载与上传，见Git 仓库。
   • Kubernetes：集群的 Token 或客户端证书，ZAI 用 kubectl 访问，可以包含多个 context；能做哪些操作由集群自己的权限决定，见Kubernetes。
   • 插件：随连接器一起加载的插件。控制台的说明是“使用此连接器的 Session 从下一条消息起加载这些插件；同一轮回复内不变”，见技能与插件。
4. 事件入口：归属这个连接器的 Webhook，即外部系统推进来的事件；删除连接器时会一并删除，见Webhook 与事件。
5. 使用范围：连接器在哪些群或成员的范围里可用，以及每个范围的授权优先级。
6. 申请使用：是否允许成员申请使用、由谁审批，见成员授权与审批。
7. 来源与影响：有插件正在从这个连接器同步内容时出现，删除前先看这里。
8. 危险区：删除连接器。

连接器还可以指定一条 网络隧道，让其中的全部访问都从这条隧道发出；不指定时，按沙箱配置里的内网路由选择出口，见连接器指定隧道。

新建连接器

1. 进入 组织管理 → 连接器，点 新建。
2. 填写 名称。按用途命名，例如“项目发布”，不要用“某人的 token”这类名称。按需选择 网络隧道，默认是 使用沙箱配置的路由。
3. 在 使用范围 里选择一个初始范围，或保持 稍后分配，之后在详情的 使用范围 分区或 范围设置 页里添加。几个连接器都能访问同一个目标时，可以在 添加使用范围 的 高级设置 里调整 授权优先级。
4. 点 创建 后直接打开这个连接器，第一屏的 概览 会告诉你它还缺什么。点页头的 添加访问 添加第一份内容，在 使用指令 分区写使用指令。

在详情页，鼠标移到名称上会出现铅笔按钮，点它只修改名称；页头会显示当前的 网络隧道，点它可以换一条；点概览里的标识可以复制；要删除连接器，滚到页面最末的 危险区，删除前请先看修改与删除的影响。

添加访问

点页头的 添加访问，选择器在同一页展开，按 服务预设、自定义认证、原生资源、网络与仓库 与 插件 分组；选择服务后，按推荐配置填写凭证值和必要的实例信息，名称会自动填写。需要调整协议、路径或方法时，切换到自定义。字段旁的 ? 会在新标签页打开对应的说明，当前表单的草稿不会丢失。各服务的凭证怎样获取和填写，见服务与凭证配置。

GitHub、GitLab 的个人访问令牌只用于 HTTP API，不提供仓库选择；拉取和推送代码在 访问内容 分区里添加，见Git 仓库。

• 把访问目标收窄到所需的协议、主机、端口、路径和方法。
• 凭证值只填在 Token、密码这类凭证值字段里，不要写进名称、使用指令或域名。
• 保存后，用一个不会写入业务数据的最小请求，验证目标是否匹配、目标服务的权限是否正确，见验证与排错。
• 编辑凭证的访问目标时，原来的凭证值保留；替换凭证 才会更换凭证值。
• 从 服务预设 或 自定义认证 添加的凭证，要先 撤销凭证 才能删除；数据库和 SSH 可以直接删除。已撤销的凭证不能再编辑或替换。撤销和删除都在凭证行的菜单里，需要输入凭证名称确认。

无需凭证的地址从 访问内容 分区添加，见域名（无需凭证）。

添加数据库或 SSH

点 添加访问，在 原生资源 里选择 PostgreSQL、MySQL、MongoDB、Redis 或 SSH，再填写服务端点、目标账号，以及 TLS 或 SSH 主机校验信息。

ZAI 通过 Z Tag 提供的查询和命令工具使用这些资源，也可以在它的沙箱里临时开启本地连接通道，配合常用的数据库客户端或 SSH 客户端使用；它看不到数据库密码和 SSH 私钥。每次连接有时长上限，见常用限制。

数据库能做什么，由填写的数据库账号的权限决定。SSH 只开放勾选的 执行命令、交互终端 和 文件传输，不支持端口转发等其他用法，见SSH。

修改与删除的影响

修改前先查看详情的 使用范围 和 来源与影响 分区，了解改动会影响哪些范围和资源。撤销和删除影响之后的新请求；已经提交的 SQL 或远程命令不会因为连接中断自动回滚，结果不确定时，不要盲目重试。

在 危险区 里删除连接器，会立即删除其中的全部凭证（包括没撤销的）、数据库、SSH、Git 仓库、Kubernetes 和域名，以及它的使用范围和全体成员授权；归属它的 Webhook 也会一并删除，包括这些 Webhook 的事件定义、订阅和接收记录。这些都不经撤销，无法恢复。这样删除的 Webhook，调用方之后收到 404；需要调用方收到 410 时，先在Webhook 详情里撤销 Webhook。删除确认框会列出将一并删除的 Webhook 和订阅的数量。

有插件来源选用了这个连接器里的 Git 仓库时，连接器不能删除，确认框会列出这些插件来源；先在插件来源里改选仓库，或删除插件来源。

连接器的状态

连接器列表和详情页名称下方显示连接器的状态：

我的资源 里标有 组织提供 的连接器总是显示 已配置。

访问内容 表里，凭证、数据库、SSH、Git 仓库和 Kubernetes 每一行另有自己的状态：

• 有效：已保存，没有到期时间，或离到期还早。和连接器的 已配置 一样，它不表示目标服务接受这份凭证。
• 临近到期：快到这份凭证的到期时间了，请在到期前替换。
• 已过期：超过了这份凭证的到期时间。
• 已撤销：不能再编辑或替换，只能删除。
• 未授权：只出现在 OAuth2 授权码 凭证上，表示还没人完成登录，或服务已不再接受这份授权；在凭证的编辑页重新登录。

域名行的状态总是 放行中，插件行写 随连接器启用。

ZAI 实际看到什么

ZAI 能看到连接器的名称、使用指令和访问目标（协议、地址、端口等，不含凭证值），用它们判断该用哪个连接器。它的沙箱里只有占位值，看不到真实的令牌、密码、私钥或自定义请求头的值；ZAI 访问匹配的地址时，由 Z Tag 带上真实的凭证值。

能看到连接器，不等于每次请求都会成功。每次真正使用前，Z Tag 都会重新核对授权、目标、凭证有效期、沙箱配置和内网路由，业务系统自己的权限也照常生效，见管理原则。

使用 OAuth2 Client Credentials 凭证（包括基于它的服务预设）或 Nacos（用户名密码） 凭证时，由 Z Tag 换取并刷新短期令牌，令牌同样不会交给 ZAI。连接器指定了网络隧道时，换取和刷新令牌也经过这条隧道。换取令牌失败时（例如令牌地址不可达、凭证被拒绝），这次请求会失败。

业务系统设有 IP 白名单时，出口取决于请求是否经过网络隧道。连接器指定了网络隧道，或请求命中了沙箱配置里的内网路由时，请求从隧道所在的企业网络发出，请向你们的网络管理员确认出口 IP；不经过网络隧道时，请求从 Z Tag 服务的公网出口发出，出口 IP 请向 Z Tag 管理员索取。

怎样写使用指令

本节适用于连接器、远程设备和网络隧道的使用指令，也适用于成员在 我的资源 里为自己的资源写的指令。

使用指令告诉 ZAI 这项资源用来做什么、什么时候用、有哪些限制。审批人处理这项资源的申请时，也会看到它。

• 在哪里填写：连接器在 使用指令 分区里填写 使用指令，再点 保存指令；远程设备和网络隧道在新建或编辑对话框的 使用指令（可选） 里填写。
• 长度：最多 1024 个字符，输入框下方显示已用的字数。
• 写法：短而具体，写清用途、默认的操作边界，以及哪些操作要先取得确认。
• 不要写的内容：凭证，以及临时的任务进度。使用指令是长期规则，任务进度会很快过时。

例如：

用于查询发布状态和读取流水线日志。默认只读；执行重试、取消或任何写操作前，必须取得当前任务中的明确授权。项目路径以用户提供的仓库为准，不要遍历其他项目。