最稳妥的入门方式是用预编译二进制包加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 或静默退出。

Zynq Linux Hardware Debug

Zynq‑7000 / Zynq UltraScale+ 硬件调试技能。适用于 Xilinx Zynq（Cortex‑A9/A53 + FPGA）Linux 环境，调试 I2C、I2S、UART、GPIO 等外设。包括设备树配置、内核驱动、用户空间调试工具、交叉编译和常见问题排查，支持 PetaLinux 开发。

下载

• 完整命令示例：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 定位

Hub 的 root.json 是信任根，Agent 的 --permit 是唯一入场券，这两者一旦不匹配，整个网格就断联——它不像 token 那样能刷新重试，必须重新生成并同步分发。