Zentrix Gateway 文档

接入外部注册中心（Nacos）

把 Nacos 中登记的外部智能体（A2A）与 MCP 服务同步到平台：版本要求、登记方式、网络放行、审核与分发

接入外部注册中心（Nacos）

企业已经用 Nacos 管理 A2A 智能体和 MCP 服务时，平台可以把一个 Nacos 命名空间作为「外部注册源」，按轮询间隔同步其中的条目。同步进来的外部智能体与 MCP 服务经网关代理调用，和手工接入的同类对象一样受分发、流量规则与审计约束。从登记、同步、审核到调用的完整链路与凭据划分见第 8 节。

1. Nacos 要求

  • 版本：Nacos 3.x，需提供 AI 注册管理接口（/nacos/v3/admin/ai/a2a、/nacos/v3/admin/ai/mcp）。平台已用 Nacos 3.1.2 验证。
  • 鉴权：开启鉴权时，平台用在注册源中填写的用户名与密码登录取得访问令牌，并在令牌过期前自动续取；未开启鉴权时用户名与密码留空。账号需能读取目标命名空间的 A2A 与 MCP 条目。
  • 地址：填写 Nacos 服务端地址（如 http://nacos.example.com:8848），不是控制台地址。平台的 HTTP 出站防护开启时只接受 https:// 地址。

2. 在 Nacos 中登记

外部智能体（A2A）

在 Nacos 中按智能体名称登记 AgentCard。平台读取每个智能体的完整名片，名片中的 url 必须是平台能访问的 A2A 端点。名片中声明的鉴权方式（securitySchemes）会带入平台，管理员在外部智能体详情中配置对应凭据。

以管理接口为例：

curl -X POST "http://nacos.example.com:8848/nacos/v3/admin/ai/a2a" \
  -H "accessToken: $TOKEN" \
  --data-urlencode "namespaceId=public" \
  --data-urlencode "agentName=order-agent" \
  --data-urlencode 'agentCard={"name":"order-agent","url":"https://agents.example.com/order/a2a", ...}'

MCP 服务

  • 直连 MCP：frontProtocol 为 mcp-streamable（Streamable HTTP）或 mcp-sse（HTTP+SSE），端点用 DIRECT 方式登记地址与端口，remoteServerConfig.exportPath 填 MCP 路径（如 /mcp、/sse）。平台同步后自动发现工具。
  • REST 转 MCP 模板：平台只同步能等价执行的部分；模板里含请求体或请求头改写、Go/GJSON 转换等平台无法逐字复现的写法时，该条目会被跳过，并计入「跳过模板」数。

3. 在平台中接入

  1. 从「管理控制台 → 外部注册中心」选择「新建源」，填写「名称」「地址」「命名空间」「轮询间隔（秒）」（默认 30，最小 5）。
  2. Nacos 开启鉴权时成对填写「用户名」「密码」；编辑时密码留空表示保留现有凭据。
  3. 选择要同步的对象：外部智能体、MCP 服务。
  4. 决定是否「自动批准（信任源）」，见第 5 节。
  5. 保存后选择「测试连接」，结果显示可同步的外部智能体数、MCP 数和跳过的模板数。
  6. 选择「立即同步」，或等待按轮询间隔自动同步。列表显示「健康」「最近同步」「同步计数」与「启用」。

4. 内网地址放行

平台访问 Nacos 地址以及访问 Nacos 中登记的服务地址（A2A 名片地址、MCP 端点）都经过出站防护，只在「管理控制台 → 安全设置 → 出站防护」的「平台 SSRF 出站防护」页面配置，不需要部署运维改环境变量或重启服务：

页面配置内网 Nacos 与登记的内网服务回环、链路本地、云元数据等高危地址
「SSRF 出站防护」关闭（默认）放行放行
开启，「内网出站放行名单」未启用放行拒绝
开启，「内网出站放行名单」已启用只放行名单中的 主机:端口拒绝

名单每项为精确的 主机:端口（例如 nacos.corp:8848），不支持只写主机、通配或网段；Nacos 地址与登记的服务地址都在同一份名单中维护。保存后数秒内对控制面与网关节点生效。

Nacos 中登记的服务地址按外部数据判定，不会命中页面上只读展示的「部署内置放行」项，避免注册中心登记的地址指向平台自身的内部服务。放行缺失时，「测试连接」或同步失败，注册源显示为「异常」或「降级」，对应条目不会被同步。

5. 自动批准与人工审核

  • 自动批准（新建时默认打开）：同步进来的外部智能体直接为「已批准」，MCP 服务直接生效，可被代理调用。
  • 关闭自动批准：外部智能体以「待审批」进入「外部智能体」列表，由管理员逐条「批准」或「拒绝」；MCP 服务以未生效状态进入，核对后再发布。被拒绝的条目在下次同步时回到「待审批」。

6. 分发后可见

无论是否自动批准，同步进来的外部智能体与 MCP 服务都要在各自的「分发」中设置可用范围（全租户、部门、职能组等），成员才能在外部智能体广场与 MCP 广场看到并调用。外部智能体列表中这类条目的来源显示为「注册中心」。上线前分别用范围内与范围外账号验证可见性和调用结果。

7. 同步与删除规则

  • 同一注册源的同一条目重复同步时更新原记录。
  • 上游条目连续两次轮询都不存在才视为删除：外部智能体被停用，MCP 服务被归档并吊销其网关令牌。
  • 单次同步结果为空，或一次要删除超过一半的条目时，平台暂停删除并把注册源标记为「降级」，避免 Nacos 故障导致整批下线。
  • 删除注册源会吊销其同步进来的 MCP 网关令牌，并移除已同步的外部智能体与 MCP 服务；之后可重新接入。

8. 端到端链路

本节说明一个 MCP 服务从在 Nacos 中登记到被成员调用的完整过程，以及每一段使用的凭据。外部智能体（A2A）的登记、同步、审核与分发过程相同，调用段经外部智能体网关转发。

流程图

① 登记      服务方 ──登记 MCP / A2A 条目──▶ Nacos 命名空间

② 同步      平台控制面 ──Nacos 用户名与密码登录──▶ Nacos
            Nacos ──访问令牌──▶ 平台控制面（缓存，到期前 60 秒重新登录续取）
            平台控制面 ──携带访问令牌，按轮询间隔列出条目──▶ Nacos
            平台控制面：与上次结果比对差异 → 新增 / 更新 / 停用或归档
            平台控制面 ──对新同步或更新的 MCP 服务──▶ 工具发现

③ 审核分发  自动批准：直接生效 ┐
            人工审核：管理员核对后生效 ┴──▶ 分发给成员（全租户、部门、职能组等）

④ 取得令牌  方式一：成员 → MCP 服务详情「获取连接配置」→ 签发 MCP 令牌（zg_mcp_ 开头，只显示一次）
            方式二：MCP 客户端 ──OAuth 授权码 + PKCE S256──▶ 平台授权
                    成员登录并在授权页同意 → 平台签发 MCP 令牌（zg_mcp_ 开头）给客户端

⑤ 调用      MCP 客户端 ──Authorization: Bearer zg_mcp_…──▶ 网关节点
            网关节点：在本机快照中校验令牌（不逐请求访问控制面）
            网关节点 ──注入上游凭据后转发──▶ 上游 MCP 服务
            上游 MCP 服务 ──结果──▶ 网关节点 ──▶ MCP 客户端

⑥ 记录      网关节点：生成调用记录与审计事件 ──本机队列异步上送──▶ 平台控制面

分步说明

  1. 服务方在 Nacos 登记服务。 按第 2 节在目标命名空间登记 MCP 服务或外部智能体名片。登记信息只描述服务地址、协议与工具，不携带上游鉴权所需的凭据。
  2. 平台登录 Nacos 并同步。 同步由平台控制面执行，多实例部署时只有一个实例轮询 Nacos。Nacos 开启鉴权时，平台用注册源中填写的用户名与密码调用 Nacos 登录接口取得访问令牌，在令牌有效期内复用，到期前 60 秒重新登录；Nacos 未返回有效期时按 5 分钟处理。平台按「轮询间隔（秒）」列出命名空间中的条目，与上次结果比对后新增、更新或删除（删除规则见第 7 节）；对已知条目，平台同时监听 Nacos 的配置变更，变更后无需等到下一个轮询周期即可更新。每个同步进来的地址在写入前都经过出站防护校验（见第 4 节）。直连 MCP 服务同步后，平台连接该服务自动发现工具；REST 转 MCP 模板由平台在本地编译为工具。
  3. 管理员审核并分发。 注册源打开「自动批准（信任源）」时，同步进来的 MCP 服务直接生效；关闭时以未生效状态进入，由管理员核对后发布（见第 5 节）。随后在 MCP 服务的「分发」中设置可用范围（见第 6 节）。
  4. 成员取得 MCP 令牌。 两种方式由租户在「管理控制台 → 组织与权限 → 账号与会话安全」的「安全策略」中通过「允许类型」开启：
    • 令牌：成员在「MCP 广场」打开服务详情，选择「获取连接配置」，选择「令牌有效期」后签发。令牌以 zg_mcp_ 开头，只在签发时显示一次，调用时代表当前成员本人。有效期不超过租户设置的「最长 令牌有效期」。
    • OAuth：成员在服务详情中选择「显示 MCP 配置」，把接入地址写入支持 OAuth 的 MCP 客户端。客户端首次连接收到 401 后，按授权码加 PKCE S256 流程跳转平台授权；成员登录并在「授权请求」页面选择「允许访问」后，平台向客户端签发同样以 zg_mcp_ 开头的 MCP 令牌。此方式要求租户已启用「企业 IAM (OAuth2)」身份源，登入方式为「外部 OAuth2 IAM」或「平台账号直接登录」；OpenID Connect 类身份源只用于网页登录，不能用于此流程。
  5. 客户端携带令牌调用网关。 接入地址为 https://<网关地址>/api/v1/agent-gateway/mcp-servers/<服务 ID>/mcp，请求头为 Authorization: Bearer zg_mcp_…。网关节点在本机保存的租户快照中校验令牌：令牌是否存在且未撤销、是否过期、是否属于所调用的服务、服务是否生效、租户许可是否有效，任一项不满足即返回 401。校验不逐请求访问控制面；刚签发的令牌尚未进入本机快照时，节点会按租户补取一次快照后再校验。校验通过后，网关解密该服务的上游凭据并注入请求，再转发到上游 MCP 服务，同时执行流量规则、内容安全与出站防护。
  6. 网关生成调用记录与审计。 每次调用的结果、耗时、所用令牌与工具名在网关节点生成调用记录与审计事件，写入本机队列后异步上送控制面。管理员可在「MCP 服务」页面的「令牌管理」中查看每个令牌的使用记录与最近活动。

凭据与认证

整条链路涉及三类凭据，各自只用于一段，互不替代：

凭据使用方 → 对象由谁配置或签发调用方是否可见
Nacos 用户名与密码平台控制面 → Nacos管理员在注册源中填写，加密保存；编辑时密码留空表示保留不可见，只用于同步
MCP 令牌（zg_mcp_），含 OAuth 授权后签发的令牌MCP 客户端 → 网关成员在服务详情中签发，或 OAuth 授权完成后由平台签发由成员或客户端持有，代表成员本人
上游凭据网关 → 上游 MCP 服务与手工接入的 MCP 服务相同，在平台中为该服务配置；服务使用「使用用户个人凭据」时由成员填写个人凭据或完成个人授权不可见，由网关在转发时注入

统一认证的方式是：调用方只面对网关签发的 MCP 令牌，无论服务来自 Nacos 还是手工接入，网关都按同一套规则校验身份、分发范围与许可；Nacos 账号与上游凭据都不交给调用方。令牌过期由网关节点按本机时钟即时判定；令牌被撤销、成员被停用或服务不再分发给该成员时，在网关节点下一次更新快照后生效；注册源删除或上游条目被确认删除时，平台吊销该服务的全部 MCP 令牌（见第 7 节）。

当前边界： MCP 服务的调用入口目前只接受 MCP 令牌（直接签发或经 OAuth 授权签发）。业务系统携带企业身份源签发的用户令牌直接调用，目前只覆盖模型调用入口（见用企业身份调用模型），不适用于 MCP 服务与外部智能体。

网关扩展开发

用 Rust 或 Lua 编写 WASM 网关扩展：获取模板、构建校验、运行限制与发布

On this page

接入外部注册中心（Nacos）1. Nacos 要求2. 在 Nacos 中登记外部智能体（A2A）MCP 服务3. 在平台中接入4. 内网地址放行5. 自动批准与人工审核6. 分发后可见7. 同步与删除规则8. 端到端链路流程图分步说明凭据与认证