OpenZiti 多 SDK 宿主实战：双 SDK 应用托管 echo 服务与 zcat 客户端接入指南-平芜编程栈

零信任
网络
后端
认证鉴权

【免费下载链接】ziti

The parent project for OpenZiti. Here you will find the executables for a fully zero-trust, programmable network @OpenZiti

项目地址：https://gitcode.com/gh_mirrors/zi/ziti

点击查看免费下载

导读

本文基于 OpenZiti 仓库内 multi-sdk-hosted.md 脚本说明，完整演示如何在已有控制器（Controller）与边缘路由器（Edge Router）的网络上，搭建一个由两个独立 SDK 应用实例共同托管的 echo 服务，并由第三个 SDK 应用作为客户端访问。读完本文，你将掌握ziti edge系列命令创建服务、身份与三类策略的完整流程，理解@与#角色语法的区别，并能在本机同时运行两个宿主实例验证负载分担场景。

一、场景概述：多宿主 SDK 托管是什么

该脚本的目标很明确：搭建一个echo 服务，它被两个 SDK 应用（echo-host-1、echo-host-2）同时托管，再由另一个 SDK 应用（zcat 客户端）访问。这是与"单 SDK 宿主"（见 single-sdk-hosted.md）相对的进阶场景，其核心价值在于验证：

同一个服务可以被多个身份共同绑定（Bind），形成多宿主拓扑；
控制器会根据宿主 cost、precedence 等策略在多个 terminator 之间选择连接目标；
SDK 客户端无需感知后端宿主数量，仅凭服务名ziti:echo即可访问。

注意：与使用路由器的托管方式不同，这里的宿主程序使用 OpenZiti SDK 直接嵌入网络，身份文件（.json）由注册流程生成，托管能力完全依赖控制器下发的策略授权。

二、前置条件

运行本脚本前，环境中必须已经具备：

至少一个控制器（Controller）：负责身份、服务与策略管理；
至少一个边缘路由器（Edge Router）：负责承载 SDK 与控制器之间的流量通路。

仓库提供了完整的快速启动资源，例如 quickstart/README.md、quickstart/docker 与 quickstart/local 下的脚本，可一键拉起最小可用的控制器 + 边缘路由器组合。若采用本机部署，也可参照 doc/003-local-deploy.md 与 doc/002-local-dev.md 完成搭建。

此外，本脚本依赖zitiCLI 以及ziti demo子命令，需要先构建/安装当前仓库的 CLI 工具（构建方式见 BUILD.md）。

三、登录控制面并保持会话

3.1 登录控制器

所有ziti edge操作都要求先建立会话：

ziti edge login

脚本中以action:ziti-login块执行该命令，并允许重试（allowRetry=true）。运行时它会使用默认控制器地址与凭据；也可以在调用 setup 命令时通过参数显式指定连接信息（详见下文"源码实现解读"）。

3.2 会话保活

如果会话超时，再次执行 ziti edge login 即可。

ziti edge login的会话有时效性。脚本通过keep-session-alive动作块以 1 分钟为间隔维持会话，若中途超时，重跑登录命令即可恢复。

四、清理历史残留实体

为保证可重复执行，脚本会先删除上一次运行可能残留的同名实体。注意删除顺序遵循依赖关系——先删服务，再删配置、身份，最后删策略：

ziti edge delete service echo ziti edge delete config echo-host ziti edge delete identities echo-host-1 echo-host-2 ziti edge delete service-policies echo-bind ziti edge delete edge-router-policies echo ziti edge delete service-edge-router-policies echo

提示：这些删除命令在实体不存在时通常也会正常结束或给出可忽略的报错，脚本的目的是"确保从干净状态开始"。

五、创建 echo 服务

ziti edge create service echo -a echo

echo：服务名，后续宿主与客户端都以该名称绑定/拨号；
-a echo：为该服务打上属性标签echo。这些属性将被后续策略的角色（roles）表达式引用，是实现"按标签授权"的基础。

六、创建并注册两个宿主身份

ziti edge create identity echo-host-1 -a echo,echo-host -o echo-host-1.jwt ziti edge enroll --rm echo-host-1.jwt ziti edge create identity echo-host-2 -a echo,echo-host -o echo-host-2.jwt ziti edge enroll --rm echo-host-2.jwt

逐项说明：

参数	含义
`create identity echo-host-1`	创建名为`echo-host-1`的身份（默认类型为用户）
`-a echo,echo-host`	给身份打两个属性标签：`echo`与`echo-host`
`-o echo-host-1.jwt`	输出注册令牌（enrollment JWT）到本地文件
`ziti edge enroll --rm`	使用该 JWT 完成注册，`--rm`表示注册完成后删除 JWT 文件

注册完成后，ziti edge enroll会生成对应的JSON 身份文件（echo-host-1.json、echo-host-2.json），其中包含证书与控制器地址，SDK 应用加载该文件即可接入网络。

两个宿主身份共用echo-host标签，这使后续 bind 策略可以用一条规则同时授权两个身份。

七、配置三类策略

这是整个托管链路成立的关键。脚本依次创建三条策略：

ziti edge create service-policy echo-bind Bind --service-roles @echo --identity-roles #echo-host ziti edge create edge-router-policy echo --identity-roles #echo --edge-router-roles #all ziti edge create service-edge-router-policy echo --service-roles @echo --edge-router-roles #all

策略类型	名称	作用
`service-policy`（Bind）	`echo-bind`	授权持有`#echo-host`标签的身份可以绑定（host）服务`@echo`
`edge-router-policy`	`echo`	授权持有`#echo`标签的身份可以使用路由器（这里是`#all`所有路由器）
`service-edge-router-policy`	`echo`	授权服务`@echo`可以被`#all`路由器服务

角色语法的关键约定：

@前缀：直接引用具体实体（此处@echo指服务实体本身）；
#前缀：引用属性标签（#echo-host指所有带echo-host标签的身份，#echo指所有带echo标签的身份，#all是内置的"全部"标签）。

正是这套标签 + 策略的组合，使得：创建身份与创建服务时打的标签，在此处转化为实际的授权关系——两个宿主身份都能 Bind 该服务，客户端身份（同样带echo标签）能通过边缘路由器访问它，而服务本身被授权可经由所有路由器承载。

八、运行双宿主与客户端验证

策略配置完成后，即可启动两个宿主实例：

ziti demo echo-server -i echo-host-1.json ziti demo echo-server -i echo-host-2.json

同时，在另一个终端以客户端身份运行 zcat：

ziti demo zcat -i zcat.json ziti:echo

其中：

echo-server是ziti demo下的演示命令：以指定身份文件加载 SDK 上下文，绑定并托管echo服务（默认服务名即echo，可通过-s修改），随后循环读取客户端数据并原样回写，实现 echo 语义；
zcat是通用网络 cat 工具，ziti:echo表示通过 Ziti 网络拨号名为echo的服务；传入-i zcat.json指定客户端身份文件。运行后从标准输入键入内容，宿主端会原样回显。

两个宿主同时运行时，控制器会根据各宿主 terminator 的 cost 与 precedence 选择目标连接，从而验证多宿主场景下的连接分配行为。

九、源码级原理解读

9.1 setup 脚本如何被驱动执行

该 Markdown 并非普通文档，而是被ziti demo setup echo multi-sdk-hosted命令逐块解释执行的可运行脚本。见 setup-multi-sdk-service.go：

脚本源码通过//go:embed setup-scripts/multi-sdk-hosted.md直接嵌入二进制；
运行时使用runzmd.NewRunner()解析文档，识别action:ziti-login、action:keep-session-alive、action:ziti等动作块并顺序执行；
命令行提供了连接参数：--controller-url、-u/--username、-p/--password，以及--newline-pause（滚动行间停顿，默认 10ms）和--interactive（交互模式，等待用户确认，默认自动确认）。

命令注册结构见 root.go：demo→setup→echo下挂载了client、single-sdk-hosted、multi-sdk-hosted、multi-tunneler-hosted、update-config-addressable等多个场景，本主题对应newMultiSdkHostedCmd。

9.2 echo-server 命令的实现

echo_server.go 展示了 SDK 托管的标准流程，与本脚本直接对应：

ziti.NewConfigFromFile(identityJson)加载身份文件；
ziti.NewContext(config)建立 SDK 上下文并连接控制器；
查询当前身份与服务，组装ziti.DefaultListenOptions()（包含Cost、Precedence、MaxTerminators、BindUsingEdgeIdentity等字段，默认最大 terminator 数为 3）；
zitiContext.ListenWithOptions(service, listenOptions)在 Ziti 网络上托管服务；
循环Accept()并回写数据，实现 echo；close-after-write可选在写回后关闭连接。

此外它还支持--port（额外开启 TCP 监听）、--health-check-addr（健康检查端点）、--cli-agent（默认开启的 CLI Agent 管理通道，可动态调整 terminator 的 cost/precedence）等参数，便于在生产式调试中灵活使用。

9.3 zcat 客户端的实现

zcat.go 演示了 SDK 拨号（dial）侧的标准流程：

目标格式为network:address，合法 network 为ziti、tcp、udp；
当 network 为ziti时：ziti.NewConfigFromFile加载客户端身份 →ziti.NewContext建立上下文 →zitiContext.DialWithOptions(addr, dialOptions)拨号（默认 5 秒连接超时，可通过address@service语法指定拨号身份）；
支持--verbose（调试日志）、--log-formatter（json/pretty/text）、--sdk-flow-control（启用 SDK 流控）、--redial-on-close（断线自动重拨）等选项；
连接建立后可取得底层edge.Conn的GetCircuitId()，用于观测本次连接在 Ziti 网络中创建的电路。

9.4 与单 SDK 宿主脚本的差异

对比 single-sdk-hosted.md 可以发现：单宿主版只创建一个echo-host-1身份、只运行一个echo-server实例；其余服务创建、策略配置与 zcat 客户端用法完全一致。因此本脚本可以看作单宿主方案的直接横向扩展——新增宿主只需"再建一个身份 + 再启一个实例"，策略无需改动（得益于#echo-host标签的批量匹配），这体现了 Ziti 按标签授权的扩展性。

十、验证要点与排错建议

登录失败/会话过期：重跑ziti edge login，或使用 setup 命令的--controller-url/-u/-p显式指定；
宿主启动报"unable to lookup service"：检查 bind 策略echo-bind是否存在、--service-roles @echo与身份标签#echo-host是否匹配；
zcat 拨号失败：确认edge-router-policy与service-edge-router-policy已生效，且目标路由器在线；使用ziti edge list terminators观察echo服务下是否已出现两个宿主注册的 terminator；
多宿主负载分配：可在echo-server实例日志中观察 circuitId 的分配情况，结合控制器指标（见 doc/2.0-metrics-and-config-changes.md）分析连接走向。

结语

通过本脚本，你已完整掌握 OpenZiti 上"双 SDK 宿主 + SDK 客户端"的端到端托管搭建：从登录、清理、创建服务与身份、配置 bind/edge-router/service-edge-router 三类策略，到同时运行两个 echo-server 并以 zcat 访问。其背后的ziti demo命令体系（root.go）与 SDK 托管/拨号实现（echo_server.go、zcat.go）为理解生产级 SDK 嵌入提供了可直接阅读的范本；multi-router-tunneler-hosted.md 等其余 setup 脚本则展示了由路由器托管、隧道路由器（tunneler）接入等更多部署形态，可作为后续进阶参考。