Skip to content

ZTM App Introduction and QuickStart

Jump to bottom
CaiShu edited this page Oct 2, 2024 · 14 revisions

ZTM App 是可以运行在iOS、MacOS、Windows、Linux、Android上的跨平台终端应用，ZTM App在连接到ZTM Hub后可以实现交互式图形化操作ZTM相关的功能，包括配置管理和应用功能。具体的包括注册到ZTM Hub、查看ZTM Hub上已经注册的End Points清单、查看日志，以及操作ZTM MiniApp。ZTM MiniApp是用于扩展ZTM在应用领域功能的小程序，这些小工具提供远程桌面共享、文件共享、内网web访问等多种功能。

如下演示如何从头构建一个ZTM环境，包括一个运行在aws云端的ZTM Hub，以及运行在iphone上的ZTM App和运行在MacOS上的ZTM App，并从iphone共享视频文件给MacOS。

第一步：部署ZTM Hub

用户可以选择自己部署ZTM Hub，或者从aws marketplace的AMI直接启动运行ZTM Hub。这个演示中，我们采用从aws marketplace的AMI直接运行的方式。

  1. 登陆aws控制台，选择创建EC2

  2. 在创建页面，选择AMI的步骤，输入"ztm" 1

  3. 回车后，选择"ZTM HomeConnect" 2

  4. 选择"Subscribe Now" 3

  5. 保留其他的默认设置不动，点击"Launch Instance"，启动EC2 4

  6. 在EC2启动后，把EC2里边/root/.ztm/ztm-permit.json拷贝到本地，保存到文件中。注意这个文件需要保密，其中包含了连接到ZTM Hub的密钥(想我这样把其中内容贴在wiki的方法是非常危险的)

caishu@caishu-macair4 pipy % ssh -i ~/.ssh/us-ca.pem [email protected]
Welcome to Ubuntu 24.04 LTS (GNU/Linux 6.8.0-1016-aws x86_64)

 * Documentation:  https://help.ubuntu.com
 * Management:     https://landscape.canonical.com
 * Support:        https://ubuntu.com/pro

 System information as of Mon Sep 30 03:58:12 UTC 2024

  System load:  0.0               Temperature:           -273.1 C
  Usage of /:   24.8% of 8.65GB   Processes:             109
  Memory usage: 33%               Users logged in:       0
  Swap usage:   0%                IPv4 address for ens5: 172.31.29.4

 * Ubuntu Pro delivers the most comprehensive open source security and
   compliance features.

   https://ubuntu.com/aws/pro

Expanded Security Maintenance for Applications is not enabled.

111 updates can be applied immediately.
To see these additional updates run: apt list --upgradable

Enable ESM Apps to receive additional future security updates.
See https://ubuntu.com/esm or run: sudo pro status


Last login: Fri Sep 27 02:16:18 2024 from 18.206.107.29
ubuntu@ip-172-31-29-4:~$ sudo su -
root@ip-172-31-29-4:~# cat ~/.ztm/ztm-
ztm-hub.db       ztm-permit.json
root@ip-172-31-29-4:~# cat ~/.ztm/ztm-permit.json
{"ca":"-----BEGIN CERTIFICATE-----\nMIICoTCCAYkCFHqvFOArK6yQVP3Hp3Hrg0EYGVjDMA0GCSqGSIb3DQEBCwUAMA0x\nCzAJBgNVBAMMAmNhMB4XDTI0MDkzMDAzNDYwNloXDTI1MDkzMDAzNDYwNlowDTEL\nMAkGA1UEAwwCY2EwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCuHp9o\nRC5uxu+R7530bPAlFs16ocA0SSA07pQ2iK5QjtfoaAs/FlEOMX8nUIEXI8QaQkpL\neHfEH9x++XhAmhAZXCloVjaq1Xg7T2XVjqRY6DTh36bRnLUrNcANHUBCAkxtoUdg\nqTMVD3IqMLQdjD3hcyEFmCtVg3+Wx13I35lz6N0HWiumXXGtpWAyC3F25/x2XayC\nCeFTDm7V9mDaFegd4L1S73I1pJxTmMCrFv59/5ncT3qk6fuc3eKlPiEU85Fm70gI\npE6zLMjs7lmtdi4zYE3pNnfh9C8Nr4RgDsiMVWP8bFpPnCQDhKuqIPNc+WS2HYyl\n0b8SsuX0HlSQPchhAgMBAAEwDQYJKoZIhvcNAQELBQADggEBABkFTY6m+soi9Q0/\nCtbvlUYAVj1K6dg41UDjUphItYXLaHYJm/pd5QOYRMJ+QvLC0w85W8nkeqJMKW/u\nwzVXvHhKSwhddTBWMKuxELTaVlykWpym4WP4LP+p5jhOUIZ4A3rZ8g/aCNIPzI1G\npRpqn0Bb1Z71LCZ9LFDEPdcN3axEWEQoCmJoOyaJo89hEKP74aFL1Jm7OAafHojC\neTxY+L3BzDoORjvW7psOm+aOv6a2yhHMfN17lKAoz/8UXybeWF5nEjgjqtoDpV3D\nVKB0wkO85lypgdS/kzBxFNkEf0SbpvkAl+QDWzZ4CN2Xeg/U/sk38JliwqwKr+T7\nVImZ11w=\n-----END CERTIFICATE-----\n","agent":{"certificate":"-----BEGIN CERTIFICATE-----\nMIICozCCAYsCFEXLF43oon7cSdEfb06YhjVBNBfcMA0GCSqGSIb3DQEBCwUAMA0x\nCzAJBgNVBAMMAmNhMB4XDTI0MDkzMDAzNDYwNloXDTI1MDkzMDAzNDYwNlowDzEN\nMAsGA1UEAwwEcm9vdDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALQP\n2T9qjWOjAzRSkkdZRcvhe7M9FLjwzzXRbY5L0V01u1dF1xHQ0HwuOi7zwC+vl6BW\nhjkoWrX0IhE0TUvDLiNDTBhGTofafOdShYbTdyv66V7MfZPmB+gynv5sVOudHuVU\npXx6MNG9DYJln8igRZHijEtMBsEGlXEOdgdHgr3j2XFqfHiTxyyv8abzkpA7xseL\nfXacnZ8o1b3PI8N1L4pxkm9lzNryTpDCyvkEJOuZLw1gro5Hxwl1kjj5sJbN64lm\nm6jU2vpedBZr2mjXhrz+iIiEu7UZXHsx+djnk1S6HMCct7btD9JcwTK2Vo+6Auqv\nflpdzbXZZmB5+j5gnFsCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAozt2IF2OhuCz\nH4IsQ8hF7d3zwrlxDsGTx1cXjEE1/dT1MjadsGcowEI4Fjsxjou0hR6JR+U4xlmG\nCSPCiZVNVmhOqZcHvFVmtqMZAo1eDjDUJlLx9q4YwDBdCKR9ectcgTS8MT6J7DK2\nbZM17rkANgclAC7UwL192roOoPXuokx/9yQH5m9QLJNRlLm1VRPkcwQAeyv6GiI1\n/HYB7G5KISo63blY20ZaoGS5B3JjmLVqFOwX3Iu63KY9VlqQduWSwNFgU4+62788\npNLZSKGRhqKjVBWcX9FG4w39IXBqSFdAos8h225EvBy7SJ671G6vBY/yL0oeMmUR\nCHDrCu9l1Q==\n-----END CERTIFICATE-----\n","privateKey":"-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC0D9k/ao1jowM0\nUpJHWUXL4XuzPRS48M810W2OS9FdNbtXRdcR0NB8Ljou88Avr5egVoY5KFq19CIR\nNE1Lwy4jQ0wYRk6H2nznUoWG03cr+ulezH2T5gfoMp7+bFTrnR7lVKV8ejDRvQ2C\nZZ/IoEWR4oxLTAbBBpVxDnYHR4K949lxanx4k8csr/Gm85KQO8bHi312nJ2fKNW9\nzyPDdS+KcZJvZcza8k6Qwsr5BCTrmS8NYK6OR8cJdZI4+bCWzeuJZpuo1Nr6XnQW\na9po14a8/oiIhLu1GVx7MfnY55NUuhzAnLe27Q/SXMEytlaPugLqr35aXc212WZg\nefo+YJxbAgMBAAECggEAEDBomPdh36EgFaE4PlVRctjtappwStx5KjPlL2kJBDdj\nhko6NwODldargTMwhq5j6eo9m9VRVTtY9huyDhYYsi+dH4WauUOJ/VusXl3plg5e\nKG7RpO2GrSLNVr9eDJJjh7z05VyFwnsb7tW86FM4o2WEtZ8P8GTrehm8aj/MtSPT\nlzXsKC7jPYheE1rFTfP8wZXnbrgp1yWn7fp7wxLO+FXaKsIMwHbHNUZBRBhIRK7D\n1CLG7RHdusu2YwDVgF0SKDPOfVv3VBkvJYNeAXU78hRO89bSBlXiee3nTT30R0G8\nPUzJR061QnemlfNEpnBYGLZlxZhe+fHOgrKtxAD6OQKBgQDidbjw9ftIom3sKMg1\n1hwtgPMKxTjJhen12mVNtC8eqJdvtjzIrTGmT8TM5C9D7sR4JQ0XlS+Y83xpm7YL\ngSaF8ngfDD2B7vI9rSfozjeT6jVXQYQHleX1nGyfoCxu4zzlcO0UBehj7CSqtCwP\nCo35qWw8L3QqVq3hY+ca7nrXjQKBgQDLjL0HHDhFdlyvfuomULl7zwvMEFZv7UzC\ncpgs+LNGBnh2BtjkycYsuCUsC/z2yOHXjfJIJ1SQiQsUXcArQKt4/4mPWCS8UQt5\n2lzcARqqsF2LsnhCW7X+vM7xq0X1qC/52QTIksQHGZOVXD0I5drP0QT+Tgo90va6\nGXjFGUv1hwKBgQCHBK1JbT9u5Pkozn/gKVIPh0xg5YmgDWmanaW8mGtnmhkAD+VZ\nuHlbsT+i8YGEvT0CbQTLRLVmOfW5eY8meNAhGJmp2UBq0a44O58J3LmiRQeciIFR\njHvY3nSdD4CudGmAWr3fLE6MFOUfqeCC70YKzoqrr5dRDvEI6umFUx6GmQKBgQC1\nQxI+F7JAoUOugI2RK0fR6jHuOgpPR/mYGyZKvfoffLmfGT/ilZBl2GI51D8joQYE\nx4IfIO8cev2j2Ey996v7Z0wfm3WzQVS/4WXaAR23LLFRKtAO/86VF5wN9+Cn/2sh\nylGJL7FjRTJ4ypgLqWzurYsNz38tSQWv+ejjVEChVwKBgGO62ZOrHEmIqw8vUMnl\naX2alpyXgfXw6kWzidr6CWmAucymjdPc+sMxpqtByi+zeQUQuDYwb4RQ8ZEhJPs9\nLSbkrMy37BgaJD4XCzbYqVQkZaS1Y/VVGHqGsVpnwP3CvJPRd+sNBsK741bTfUt0\n54XL1tkYa634EGhh5qMnLPkq\n-----END PRIVATE KEY-----\n"},"bootstraps":["54.183.136.214:443"]}

第二步：安装MacOS ZTM App

安装ZTM App

ZTM提供3种安装介质和模式：

  1. ztm-aio (all-in-one)，这是一个命令行可执行文件。从ztm release 页面就可以现在，比如我下载的是这个 https://github.com/flomesh-io/ztm/releases/download/v0.3.0/ztm-aio-v0.3.0-macos-arm64.tar.gz 。对于熟悉Unix/Linux 命令行操作的用户，这个安装包提供了和Linux一样的操作体验
  2. brew 安装包。MacOS上用户，如果熟悉brew，可以用 brew install flomesh-io/ztm/ztm 命令来安装ztm
  3. ztm-app ，是一个图形界面安装包，在MacOS上熟悉 dmg 安装的可以用这个模式。同样，安装介质也在release的下载页面。我们正在把dmg的安装包上架到App Store，需要一些流程和时间

在这个例子中，我采用的是第二种办法，使用brew 安装，过程非常简单：

caishu@caishu-macair4 ztm % brew search ztm
==> Formulae
flomesh-io/ztm/ztm                    zim                                   mtm                                   dtm

==> Casks
utm
caishu@caishu-macair4 ztm % brew install ztm
==> Downloading https://formulae.brew.sh/api/formula.jws.json
################################################################################################################################################# 100.0%
==> Downloading https://formulae.brew.sh/api/cask.jws.json
################################################################################################################################################# 100.0%
==> Fetching flomesh-io/ztm/ztm
==> Downloading https://github.com/flomesh-io/homebrew-ztm/releases/download/ztm-0.3.0/ztm-0.3.0.arm64_sonoma.bottle.tar.gz
################################################################################################################################################# 100.0%
==> Installing ztm from flomesh-io/ztm
==> Pouring ztm-0.3.0.arm64_sonoma.bottle.tar.gz
🍺  /opt/homebrew/Cellar/ztm/0.3.0: 6 files, 22.7MB
==> Running `brew cleanup ztm`...
Disable this behaviour by setting HOMEBREW_NO_INSTALL_CLEANUP.
Hide these hints with HOMEBREW_NO_ENV_HINTS (see `man brew`).
Removing: /Users/caishu/Library/Caches/Homebrew/ztm--0.2.0.arm64_sonoma.bottle.tar.gz... (9.8MB)

启动ZTM App(Aka 'ztm agent')

caishu@caishu-macair4 ztm % ztm run agent
2024-10-02 10:26:21.786 [INF] [listener] Listening on TCP port 7777 at 127.0.0.1

打开GUI控制台

在浏览器打开 http://127.0.0.1:7777/ 就可以使用GUI访问ZTM App了： 6

在ZTM App里边，所有的操作都可以通过GUI方式或者CLI方式进行，喜欢CLI模式的用户可以尝试在另一个term窗口中执行如下命令：

caishu@caishu-macair4 ztm % ztm get mesh
NAME      JOINED AS   USER  HUBS                STATUS

在这个教程里，我们会为每一个通过GUI进行的操作，介绍对等的CLI命令。但是对于用户来说，只要使用GUI或者CLI中的一种操作就可以

连接到ZTM Hub

在浏览器的控制台中点击"Join Mesh"，然后输入mesh的名字和当前agent的名字（这两个名字都可以用随意起的名字），在"Permit"的地方点击铅笔图标输入在部署ZTM Hub时记录的permit的json内容就可以。 7

点击"OK"，点击"保存"后，就可以在控制台看到已经连接到了ZTM Hub。

8

使用CLI可以用如下命令连接到一个ZTM Hub，和如上的GUI操作是等效的

ztm join ztm-demo --as cai-macair --permit ztm-permit.json

在MacOS共享文件

ZTM App里边内置了若干的Mini-App，其中一个叫做Cloud的Mini-App可以在ZTM的设备之间共享文件。

在浏览器的Web控制台中，点击左侧的"App"菜单，然后点击"Cloud"：

9

拷贝一个文件到 *~/ztmCloud/users/root/ 目录中，然后在浏览器控制台中以此点击"users"和"root"，就可以看到拷贝进去的文件：

10

11

12

可以看到拷贝过去的 sample.mp4 文件状态显示是"New"。鼠标右键点击 sample.mp4 文件，然后选择"Upload"。需要注意的是，文件本身并没有被上传，仍然在MacOS本地；但是文件的元数据，比如文件名、尺寸、hash值等被上传到ZTM Hub，这样其他的ZTM客户端才能"看到"这个文件。Upload 完成后，可以看到状态已经不再是"New"了。

13

到这里，文件 sample.mp4 就完成了"共享"，稍后演示在iphone上下载这个文件。刚才的这些操作，在CLI模式可以按照如下方式操作，和GUI操作是等效的：

caishu@caishu-macair4 ztm % cp ~/Downloads/sample.mp4 ~/ztmCloud/users/root/
caishu@caishu-macair4 ztm % ztm cloud ls /users/root
NAME        STATE   SIZE     DATE                      SOURCES  SHARED
sample.MP4  new     2186317  Sun Sep 29 06:56:32 2024  1        -
caishu@caishu-macair4 ztm % ztm cloud upload /users/root/sample.mp4
File uploaded: /users/root/sample.mp4
caishu@caishu-macair4 ztm % ztm cloud ls /users/root
NAME        STATE   SIZE     DATE                      SOURCES  SHARED
sample.MP4  synced  2186317  Sun Sep 29 06:56:32 2024  1        -

第三步：安装 ios ZTM App 并从MacOS 下载sample.mp4

目前的iOS版本ZTM App还是在TestFlight上进行内测，很快就会在App Store正式上架。如下我们演示从TestFlight上安装ZTM App、连接到ZTM Hub并从MacOS下载文件。

  1. 打开TestFlight，可以看到 ZTM App 的安装选项，点击"安装"即可:

14

  1. 安装后打开ZTM App。第一次运行的时候会申请权限，其中的"定位"权限并不实际使用位置信息，而是为了保持应用后台运行。和MacOS版本的ZTM App类似，第一步是"Join Mesh":

15

16

17

  1. 在确认连接到ZTM Hub后，从底部菜单"Apps"选择"Cloud"。并依次点击 users 和 root 目录，最后我们可以看到 samples.mp4 并且状态是 missing ，表示这个文件在iPhone上还没有下载：

18

19

20

21

  1. 点击 sample.mp4 文件，在弹出菜单中选择"Download"，可以看到 download 的进度条；很快下载完毕，可以看到 sample.mp4 状态已经不再是 missing 了，表示这个文件已经下载到本地了：

22

23

  1. 在 iPhone 的文件浏览器里，可以在"My iPhone"中看到"ztm"文件夹，在其中的 ztmCloud/users/root 目录中可以看到从MacOS下载的 sample.mp4 文件：

24

使用CLI下载文件

ios没有提供term，所以我们使用一个Linux节点连接到ZTM Hub上，并使用CLI下载共享的这个 sample.mp4，参考过程如下：

root@ip-172-31-17-110:~# ztm cloud ls /users/root
NAME        STATE    SIZE     DATE                      SOURCES  SHARED
sample.MP4  missing  2186317  Sat Sep 28 22:56:32 2024  2        -
root@ip-172-31-17-110:~# ztm cloud download /users/root/sample.MP4
root@ip-172-31-17-110:~# ztm cloud download --list
PATH                    SIZE     SPEED        PROGRESS  ERROR
/users/root/sample.MP4  2186317  221.125KB/s  50%       -
root@ip-172-31-17-110:~# ztm cloud ls /users/root/
NAME        STATE   SIZE     DATE                      SOURCES  SHARED
sample.MP4  synced  2186317  Sat Sep 28 22:56:32 2024  3        -

在最后的输出中可以看到 SOURCES 是 "3"，这表示 sample.mp4 文件在三个节点上有拷贝，分别是MacOS 、iPhone/iOS 、Linux。

总结

在这个例子中，我们完整的涵盖了从aws marketplace运行一个ZTM Hub的云主机；然后在MacOS和iPhone分别安装了ZTM App，并加入ZTM Hub；最后从MacOS上使用Cloud Mini-App共享文件，并在iPhone上下载了该文件。

ZTM 提供了基础的去中心化网络能力，在这个网络之上，开发者可以通过Mini-App实现应用层的功能。ZTM App内置了若干个Mini-App，其中的Cloud Mini-App实现了在不同的终端上共享文件的能力。ZTM App可以运行在几乎所有的终端平台上，包括ios、macos、Linux、Windows、Andriod等，因此开发者可以快速的在ZTM之上构建自己的去中心化、适配各种终端的应用，而无需依赖特定的网络条件，ZTM提供了所有必要的基础设施，包括去中心化网络。

Clone this wiki locally