联枢:接口与工具

放行来源与上游连接

部署侧先放行上游来源,再登记连接、认证方式和访问权限说明。

先放行来源

联枢的所有出站请求都经过同一个出口,来源白名单、HTTPS 规则和出站策略对每个请求生效。前三项由部署管理员改 .env 后重新运行 docker compose up -d,见部署与初始化。第四项的登记表默认不会传进容器,见表后说明。

配置项作用
ECHOMIND_INTEGRATIONS_ALLOWED_ORIGINS允许登记的上游来源,写成 JSON 数组,每项是精确的来源(协议、主机、端口),例如 ["https://erp.example.com"]。连接地址和令牌端点都必须属于它,不含查询串。没配置时,任何地址都不能保存。
ECHOMIND_INTEGRATIONS_INSECURE_ORIGINS允许使用明文 http: 的来源,逗号分隔的精确来源。来源默认必须是 https:,明文来源要同时列入这一项,否则登记和调用都返回 INSECURE_ORIGIN。
ECHOMIND_EGRESS_ALLOW上游在回环、私网等受限网段时,要在这里列出精确的主机名、IP 或 CIDR,与数脉共用同一策略。解析到受限网段又没有放行的地址,调用返回 EGRESS_DENIED,不发出请求。
ECHOMIND_INTEGRATIONS_STDIO_SERVERS本地 stdio MCP 服务的登记表,只有运维能写,见「上游连接」一节。默认的 compose 不会把它传进容器,要在部署的 compose 里另行传入,还要自己派生带有该服务运行环境的镜像。只改 .env 不会生效。

每次网络请求连同域名解析限时 10 秒,请求体最大 32KB,响应最大 96KB。不跟随重定向,3xx 视为失败。白名单只应放可信的目标服务,它不是跨租户的网络沙箱。

联枢面板的布局

在控制台左侧「业务模块」里打开「接口与工具(联枢)」。面板标题写作「联枢 · 当前页面」,页面按任务分成五组:

分组页面
能力目录能力组、接口与工具
编排与触发工作流、计划与执行、批量计划、事件触发、轮询代替推送、延时启动、定时任务
调用与审批在线调试、调用模板、调用请求
运行记录调用日志、运行概览、操作审计
接入管理上游连接

页头的「更多」菜单里有「授权管理(联枢 Agent 授权)」和「平台审计日志」两个入口,会跳到控制台对应页面。Agent 与 Key、授权和平台审计不在联枢面板里,都在控制台的平台页面。

登记上游连接

打开「接口与工具(联枢) › 接入管理 › 上游连接」,点右上角「新增连接」,在右侧栏里依次填「连接信息」「上游认证」「访问权限」三节,点「保存配置」。保存后先点行上的「测试连接」,再去登记工具。每个联枢最多登记 100 个连接。

联枢新增连接侧栏
「接口与工具(联枢) › 接入管理 › 上游连接」的「新增连接」侧栏。截图来自测试环境,数据为示例。

连接信息

字段说明
连接名称必填。
连接协议「HTTP JSON API」或「MCP(工具)」。已保存的连接不能更换协议。
MCP 传输方式只在选 MCP 时出现:「远程 Streamable HTTP」或「本地 stdio(运维登记的服务)」。已保存的连接不能更换传输方式。
所属业务、环境用来在列表里分类,环境必填,所属业务可空。
服务地址HTTP 和远程 MCP 填写,必须属于允许的来源,地址框下方会列出当前允许的来源。选本地 stdio 时没有这一项,改为从列表里选一个已登记的服务。
启用勾选项,默认勾选。停用的连接,其下工具都不能调用。

上游认证

每个连接选一种认证方式。非机密的设置对管理员可见,机密部分只写不读:保存后只显示「已设置」或「未设置」,可以替换或清除,任何接口都不会返回它的值。凭据加密保存,国际套件用 AES-256-GCM,国密套件用 SM4-GCM。

认证方式要填什么怎么发给上游
无需认证无不带凭据
Bearer TokenBearer TokenAuthorization: Bearer …
X-API-KeyAPI Key请求头 X-API-Key
HTTP Basic(用户名 + 密码)用户名(不含冒号)、密码Authorization: Basic …
自定义请求头请求头名称、请求头的值按你指定的请求头
OAuth2 客户端凭据Client ID、Client Secret、令牌端点、Scope(可选)、客户端认证方式(HTTP Basic 为推荐,或放在请求体)联枢向令牌端点换取访问令牌,再以 Bearer 调用上游
换取访问令牌(企业微信 / 钉钉 / 飞书等)令牌端点、应用 ID、应用密钥,以及换取方式(GET 或 POST)、两个参数名、令牌和有效期在响应里的位置、令牌放在查询参数还是请求头令牌放在你指定的查询参数或请求头
机器人签名(钉钉 / 飞书)签名格式、加签密钥、Webhook 令牌每次调用按平台规则附加时间戳和签名
账号登录换会话(Cookie)登录接口地址(须与服务地址同源)、登录用户名、登录密码、会话 Cookie 名称、登录请求格式、两个参数名联枢用这个服务账号登录,取响应里的会话 Cookie,随每次调用发送
  • 「换取访问令牌」有「快速填写」预设:企业微信 gettoken、钉钉 accessToken(新版)、飞书 tenant_access_token,会填入令牌端点和参数名,应用 ID 和密钥仍要自己填。
  • 令牌端点同样要属于允许来源,响应最大 16KB。换得的访问令牌只放在服务进程内存里,不写入数据库和日志,到期前自动刷新。上游返回 401 时,读操作刷新令牌后重试一次,写操作不重试,记为结果待核验。
  • 钉钉机器人的加签放在查询参数里,飞书机器人的加签并入 JSON 请求体,工具路径写成 /open-apis/bot/v2/hook/{webhook_token},发送时替换成加密保存的令牌。
  • 账号登录换会话适合只能用账号登录、靠 Cookie 维持会话的系统。需要短信、动态口令或验证码的登录不适用,请为联枢单独开一个服务账号。登录成功但没有返回该 Cookie 时按失败处理。
  • 自定义请求头不能是 Host、Content-Length、Cookie、Forwarded 等传输层或逐跳请求头,机密里不能含换行等控制字符。

所有机密、它们的编码形式和当前的访问令牌,都会登记到脱敏表。它们出现在调用结果、日志、审计、修订历史和 Agent 的响应里时,一律替换为 [REDACTED]。

双向 TLS 与 CA 证书(可选)

仅 HTTPS 连接可用,可以叠加在任何认证方式上。「CA 证书(PEM,可选)」设置后,这个连接只信任这些 CA。「客户端证书(PEM)」和「客户端私钥(PEM,未加密)」加密保存,私钥不支持口令。保存时会检查证书和私钥是否匹配、CA 能否解析。

访问权限说明

在「新增连接」侧栏的「访问权限」小节里,这一项必填,最多 2000 字。用一两句话写清这把凭据在上游系统里实际能做什么,例如「只读账号,可查询订单与库存,不能修改或删除数据」。无需认证的连接则写匿名调用者能做什么。上游里真正能做什么由这把凭据决定,Nexus 的授权只决定 Agent 能调用联枢里的哪些工具。这段说明会显示在工具编辑页和授权编辑器里,写操作工具旁还会提示「此工具会使用上游凭据执行写操作,实际影响范围以上游凭据权限为准」。没有填写的连接,不能启用工具,也不能授予调用。

本地 stdio MCP 服务

面板和接口里没有填写启动命令、参数或环境变量的地方,因为那等于远程执行代码。本地 stdio 服务只能由运维在服务端环境变量 ECHOMIND_INTEGRATIONS_STDIO_SERVERS 里登记。它是一个 JSON 对象,名称对应一组设置:

设置说明
command、cwd必须是绝对路径,command 必须是可执行文件。
args、description启动参数和说明。管理员在面板里只能看到名称和说明。
env环境变量名白名单。子进程只得到这里列出的变量,取自联枢自己的环境,连 PATH 和 HOME 也不会默认传入。
timeout_ms、idle_ms、max_processes每个请求的时限(默认 10 秒)、空闲多久后结束进程(默认 30 秒)、同一服务同时运行的进程数(默认 4)。

管理员在连接里选「本地 stdio」,再从已登记的名称里选一个,连接地址保存为 stdio:<名称>。服务端还没登记任何服务时,面板会提示,这时不能保存 stdio 连接。stdio 连接只能选「无需认证」,所需凭据由运维通过环境变量白名单提供。

stdio 子进程运行在联枢之外,出站策略、允许来源和 HTTPS 规则都管不到它的网络和文件访问。命令的来源、运行账号、文件权限和网络隔离由运维自己负责,面板在 stdio 连接上也会显示同样的警告。

测试连接与同步工具

「测试连接」用已保存的认证配置访问上游:MCP 做一次会话握手,HTTP 对连接地址发一次 GET。除 401 和 403 以外的响应都算可达且认证未被拒绝。列表里会显示「测试通过」或「测试未通过」和原因,并提示下一步。MCP 连接在行上「更多」里点「同步工具」,把上游的工具目录取回来。

进一步交流

带一件正在做的事来聊

告诉我们你想让智能体接哪一类系统。我们在演示环境里把这件事走一遍,再一起判断合不合适。