放行来源与上游连接
部署侧先放行上游来源,再登记连接、认证方式和访问权限说明。
先放行来源
联枢的所有出站请求都经过同一个出口,来源白名单、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 Token | Bearer Token | Authorization: Bearer … |
| X-API-Key | API 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 连接只能选「无需认证」,所需凭据由运维通过环境变量白名单提供。
测试连接与同步工具
「测试连接」用已保存的认证配置访问上游:MCP 做一次会话握手,HTTP 对连接地址发一次 GET。除 401 和 403 以外的响应都算可达且认证未被拒绝。列表里会显示「测试通过」或「测试未通过」和原因,并提示下一步。MCP 连接在行上「更多」里点「同步工具」,把上游的工具目录取回来。