最稳妥的入门方式是用预编译二进制包加sudo ztm start hub启动；需校验SHA256、解压至PATH目录、chmod +x、sudo运行并明确--listen和--names参数，Agent须用正确root.json和一致MESH_NAME连接。
ztm 在 Linux 上安装不复杂，但容易卡在权限、路径或端口上。直接上结论：**用预编译二进制包 + sudo ztm start hub 启动是最稳妥的入门方式，别急着编译源码**。
下载和校验二进制包
官方 Release 页面（https://gitcode.com/flomesh-io/ztm）提供 ztm-x.x.x-linux.tar.gz 包，不是.deb 或.rpm —— 别用包管理器搜，也别用 apt install ztm，那不存在。
- 下载后务必用
sha256sum校验哈希值，官网 Release 页会附带 SHA256 签名；不校验可能加载被篡改的二进制 - 解压到
/usr/local/bin/或用户目录下（如~/bin），然后加执行权限：chmod +x ztm - 确认能运行：
ztm version应输出版本号，否则 PATH 没配对 —— 别跳过这步
ztm start hub 权限和监听地址必须明确
Hub 必须用 sudo 运行，因为要绑定 0.0.0.0:8888 并注册 systemd 服务。常见错误是只输 ztm start hub，结果报错 permission denied 或静默退出。
- 完整命令示例：
sudo ztm start hub --listen 0.0.0.0:8888 --names 1.2.3.4:8888（1.2.3.4换成你的公网 IP） -
--listen决定谁可以连进来，0.0.0.0表示接受所有网卡请求；若只想本机测试，用127.0.0.1:8888 - 命令成功后会生成
root.json文件，默认在当前目录 —— 这个文件必须安全分发给 Agent 节点，权限应为600
Agent 节点启动失败的三个高频原因
Agent 不需要 sudo，但常因环境差异失败。最典型的是：找不到 root.json、MESH_NAME 不一致、或防火墙拦了出站连接。
- 确保
root.json和 Agent 在同一目录，或用绝对路径传参：ztm join my-mesh --as pc-01 --permit /home/user/root.json -
my-mesh必须和 Hub 启动时隐含的 mesh 名一致（Hub 不显式指定时默认用default，但建议显式统一） - Linux 默认 firewall-cmd 或 ufw 可能阻断出站：检查
sudo ufw status，临时关掉或放行8888端口 - 如果 Agent 启动后立刻退出，加
--debug参数看日志：ztm start agent --debug
systemd 服务没生效？别信自动生成的描述
ztm start hub 声称“注册为 systemd 服务”，但实际是否启用、是否开机自启，得手动确认。
- 检查服务状态：
sudo systemctl status ztm-hub—— 若显示inactive (dead)，说明注册失败或没启动 - 手动启用：
sudo systemctl enable --now ztm-hub - 日志查看：
sudo journalctl -u ztm-hub -f，重点看是否报bind: address already in use或证书加载失败 - 注意：systemd 单元文件由
ztm自动生成，但路径可能不在标准位置（比如写入/etc/systemd/system/以外），建议用systemctl list-unit-files | grep ztm定位
root.json 是信任根，Agent 的 --permit 是唯一入场券，这两者一旦不匹配，整个网格就断联——它不像 token 那样能刷新重试，必须重新生成并同步分发。 
