flomesh-io/ztm

GitHub: flomesh-io/ztm

ZTM 是一个隐私优先的开源去中心化端到端加密软件定义网络，基于 HTTP/2 隧道，解决在各类 IP 网络上构建安全、无限连接的网格问题。

Stars: 501 | Forks: 41

# ZTM (零信任网格) ZTM 是一个开源的网络基础设施软件，用于运行一个***去中心化***的网络。它基于 ***HTTP/2 隧道***构建，可以在***任何类型的 IP 网络***上运行，例如局域网、容器化网络和互联网等。 ## 功能 ZTM 使用 **PipyJS** 编写，这是为 [**Pipy**](https://github.com/flomesh-io/pipy) (https://github.com/flomesh-io/pipy) 设计的一种 JavaScript 方言。**Pipy** 是一个开源的可编程代理软件。得益于 **Pipy**，ZTM 在其提供的能力之上拥有许多独特功能： ## 文档 * [架构与概念](docs/Architecture-Concepts.md) * [命令行界面](docs/CLI.md) * [ZT-App](docs/ZT-App.md) * [代理 API](docs/Agent-API.md) * [构建](docs/Build.md) ## 快速开始 ### 下载最简单的入门方式是从我们的 [发布页面](https://github.com/flomesh-io/ztm/releases) 下载 ZTM 的最新二进制发行版。如果您更倾向于从源代码进行自己的构建，可以按照 [构建](docs/Build.md) 中的说明进行操作。 ### 命令行补全要启用 Shell 补全，请运行： ``` mkdir -p ~/.local/share/ztm/completions ztm completion bash > ~/.local/share/ztm/completions/ztm.bash source ~/.local/share/ztm/completions/ztm.bash ``` 对于 zsh 用户： ``` mkdir -p ~/.local/share/ztm/completions ztm completion zsh > ~/.local/share/ztm/completions/_ztm fpath=(~/.local/share/ztm/completions $fpath) autoload -U compinit && compinit ``` ### 设置一个常见的设置由 3 个节点组成：1 个节点运行 *Hub*，另外 2 个节点运行两个希望相互通信的 *Agent*。 ``` Data Center +-------------------------------------------+ | Hub | | (state in ~/.ztm/ztm-hub.db) | +-------------------------------------------+ HTTPS | Port 8888 HTTPS | Port 8888 | | ------------|---------------------------------|-------------- | Firewall | ------------|---------------------------------|-------------- | | | Internet | | | ---------------------------- | ---------------------------- Firewall | Firewall ---------------------------- | ---------------------------- | | | | | | +--------------------------+ | +--------------------------+ | Agent @ Home | | | Agent @ Workplace | | (state in ~/.ztm/ztm.db) | | | (state in ~/.ztm/ztm.db) | +--------------------------+ | +--------------------------+ | ``` #### 设置 Hub 假设您在云中有一台 Linux 主机，其公网 IP 地址为 `1.2.3.4`，公网 TCP 端口为 `8888`。通过键入以下命令启动一个 Hub 服务： ``` ztm start hub --listen 0.0.0.0:8888 --names 1.2.3.4:8888 --permit root.json ``` 现在 Hub 应该已经启动并运行。此外，应该已经生成了一个名为 `root.json` 的文件，以允许 *端点* 加入我们的网格。 #### 设置端点一旦 Hub 在云中启动并运行，我们就可以继续使用生成的许可文件 `root.json` 向网格中添加任意数量的*端点*。首先，在将要加入我们网格的端点计算机上启动一个 Agent： ``` ztm start agent ``` 然后，通过以下命令加入网格： ``` ztm join MESH_NAME --as EP_NAME --permit root.json ``` 其中 `MESH_NAME` 可以是您选择的任何名称，用于在本地标识一个网格（如果您有多个）。`EP_NAME` 是您的当前端点在同一网格中被其他端点所看到的名称。`root.json` 是在我们第一步设置 Hub 时生成的许可文件。如果一切顺利，您现在可以通过键入以下命令检查网格的状态： ``` ztm get mesh ``` 或者查找已加入网格的端点： ``` ztm get ep ``` 有关命令行工具的详细用法，请键入： ``` ztm help ``` 如果您更喜欢图形用户界面，您可以在运行命令 `ztm start agent` 后立即打开浏览器并将其指向 `http://localhost:7777`。您可以加入网格、查找其他端点、使用应用程序等等。ZTM 提供的几乎所有功能都可以通过命令行界面和图形用户界面使用。对您网格中的每个端点重复上述过程。然后，您将能够通过网格中任何端点的终端或浏览器来管理您的网格。 #### 使用您的网格仅仅将一堆端点连接成一个网格并不是非常有用。使您的网格发挥作用的是在其中运行的*应用*。官方的 ZTM 发行版附带了许多内置应用，包括： - 隧道 - 在端点之间建立安全的 TCP/UDP 隧道 - 代理 - 一个 SOCKS/HTTP 转发代理，从一个端点接收流量并通过另一个端点转发出去 - 脚本 - 在端点上远程执行 *PipyJS* 脚本 - 终端 - 远程访问端点上的 Shell 也可以安装第三方应用。此外，由于 [**Pipy**](https://github.com/flomesh-io/pipy) 的 *PipyJS* 脚本能力，开发新应用相当容易。要获取所有已安装应用的列表，请键入： ``` ztm get app ``` 您可以通过浏览器图形用户界面或命令行工具使用应用。在终端上，可以通过类似以下的方式访问应用的命令行界面： ``` ztm APP_NAME ... ``` 要查找有关通过命令行界面使用应用的详细信息，请键入： ``` ztm APP_NAME help ``` ### 插件 ZTM 通过 **OpenClaw** 支持插件，OpenClaw 是一个 AI 原生网关，可将 ZTM 与外部系统集成。插件支持消息传递、自动化和第三方集成。 #### 概览 | 组件 | 用途 | |-----------|---------| | OpenClaw | AI 原生网关，将消息路由到/来自外部系统 | | 插件 | 将 OpenClaw 连接到特定平台的通道适配器 | | ZTM 聊天 | 内置聊天应用，用于去中心化的点对点消息传递 | #### 架构 ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ ZTM User │────▶│ ZTM Network │────▶│ OpenClaw │ │ (Chat App) │ │ (P2P Mesh) │ │ (AI Gateway) │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ ▼ ┌─────────────────┐ │ External │ │ Systems │ │ (ztm-chat, │ │ slack, etc.) │ └─────────────────┘ ``` #### ZTM 聊天插件 ZTM 聊天插件将 OpenClaw 连接到 ZTM 聊天，使您的 AI 代理能够与其他 ZTM 用户发送和接收去中心化的点对点消息。 #### 安装指南按顺序执行以下步骤： #### 步骤 1：启动 ZTM 代理 ``` # 启动 ZTM Agent 服务 ztm start agent ``` #### 步骤 2：安装 ZTM 聊天应用 ``` # 安装 Chat 应用 ztm app install chat # 验证安装 ztm get app ``` #### 步骤 3：创建机器人用户账户 ``` # 为 bot 创建专用用户账户 ztm user add openclaw-bot ``` #### 步骤 4：安装 OpenClaw 如果尚未安装 OpenClaw，请从 [OpenClaw 发布页面](https://github.com/flomesh-io/openclaw/releases) 下载并安装： ``` # 为您的平台下载最新版 OpenClaw # 然后启动 OpenClaw 服务 openclaw start ``` #### 步骤 5：安装 ZTM 聊天插件 ``` # 从本地路径安装（使用 ZTM 源码仓库时） openclaw plugins install -l ./extensions/ztm-chat # 或从 URL 安装（使用已发布包时） openclaw plugins install -u https://github.com/flomesh-io/ztm/plugins/ztm-chat ``` #### 步骤 6：配置插件选择以下方法之一： **选项 A：交互式向导（推荐）** ``` # 运行设置向导 openclaw ztm-chat-wizard # 向导将引导您完成以下步骤： # 1. ZTM Agent URL（默认：https://localhost:7777） # 2. Mesh 名称 # 3. bot 用户名（默认：openclaw-bot） # 4. mTLS 认证（可选） # 5. 安全设置 ``` **选项 B：手动配置** ``` # 创建配置文件 mkdir -p ~/.openclaw/channels cat > ~/.openclaw/channels/ztm-chat.json << 'EOF' { "agentUrl": "https://your-ztm-agent.example.com:7777", "meshName": "your-mesh-name", "username": "openclaw-bot" } EOF ``` 有关所有配置选项，请参阅 [ZTM 聊天插件 README](extensions/ztm-chat/README.md)。 #### 步骤 7：重启 OpenClaw ``` # 应用新配置 openclaw restart ``` #### 步骤 8：验证连接 ``` # 检查频道状态 openclaw channels status ztm-chat # 测试连接 openclaw channels status ztm-chat --probe ``` #### 插件命令 ``` # 设置向导 openclaw ztm-chat-wizard # 自动发现现有 ZTM 配置 openclaw ztm-chat-discover # 检查频道状态 openclaw channels status ztm-chat # 探测连接 openclaw channels status ztm-chat --probe # 列出已连接的对等节点 openclaw channels directory ztm-chat peers # 启用/禁用频道 openclaw channels disable ztm-chat openclaw channels enable ztm-chat ``` #### 故障排除 **连接失败** ``` # 验证 ZTM Agent 正在运行 curl https://your-ztm-agent.example.com:7777/api/meshes # 检查 Mesh 名称 ztm get mesh # 检查插件日志 openclaw logs --level debug --channel ztm-chat ``` **未收到消息** ``` # 验证 Chat 应用已安装 ztm get app # 检查 bot 用户名 ztm user list ``` 有关详细的故障排除，请参阅 [ZTM 聊天插件 README](extensions/ztm-chat/README.md)。 ## 快速链接： * [指南：使用 ZTM 进行安全的远程桌面协议 (RDP) 访问](https://github.com/flomesh-io/ztm/wiki/2.-HOWTO-:-using-ztm-for-secure-RDP-access) * [快速入门：ZTM 隧道](docs/ZT-App.md#zt-tunnel) | [隧道演示](https://github.com/flomesh-io/ztm/wiki/2.-HOWTO-:-using-ztm-for-secure-RDP-access#4-configuring-ztm-tunnel-for-rdp-connection) * [快速入门：ZTM 代理](docs/ZT-App.md#zt-proxy) * [快速入门：ZTM 终端](docs/ZT-App.md#zt-terminal) * [快速入门：ZTM 脚本](docs/ZT-App.md#zt-script) * [快速入门：ZTM 云](docs/ZT-App.md#zt-cloud) | [云演示](https://github.com/flomesh-io/ztm/wiki/4.-HOWTO-:-File-Sharing-between-ZTM-End-Points#sharing-files-on-macos) 以下是您在每个计算机节点上需要执行的命令行界面命令的回顾。 ``` Cloud-hosted VM +---------------------------------------------------------+ | ztm start hub --names x.x.x.x:8888 --permit root.json | ---+ +---------------------------------------------------------+ | | x.x.x.x:8888 | | ------------|--------------------------------|------------- | | Firewall | | ------------|--------------------------------|------------- | | | | | Internet | | root.json | | | -------------------------- | -------------------------- | Firewall | Firewall | -------------------------- | -------------------------- | | | | | | | | | +------------------------+ | +------------------------+ | | ztm start agent | | | ztm start agent | | | ztm join my-mesh \ | | | ztm join my-mesh \ | <--+ | --as home \ | | | --as workplace \ | | --permit root.json | | | --permit root.json | +------------------------+ | +------------------------+ PC @ Home | PC @ Workplace ``` 有关命令行界面的更多信息，请参阅： ``` ztm help ``` ## 快速链接： * [指南：使用 ZTM 进行安全的远程桌面协议 (RDP) 访问](https://github.com/flomesh-io/ztm/wiki/2.-HOWTO-:-using-ztm-for-secure-RDP-access) * [快速入门：ZTM 隧道](https://github.com/flomesh-io/ztm/blob/main/docs/ZT-App.md#zt-tunnel) | [隧道演示](https://github.com/flomesh-io/ztm/wiki/2.-HOWTO-:-using-ztm-for-secure-RDP-access#4-configuring-ztm-tunnel-for-rdp-connection) * [快速入门：ZTM 代理](https://github.com/flomesh-io/ztm/blob/main/docs/ZT-App.md#zt-proxy) * [快速入门：ZTM 终端](https://github.com/flomesh-io/ztm/blob/main/docs/ZT-App.md#zt-terminal) * [快速入门：ZTM 脚本](https://github.com/flomesh-io/ztm/blob/main/docs/ZT-App.md#zt-script) * [快速入门：ZTM 云](https://github.com/flomesh-io/ztm/blob/main/docs/ZT-App.md#zt-cloud) | [云演示](https://github.com/flomesh-io/ztm/wiki/4.-HOWTO-:-File-Sharing-between-ZTM-End-Points#sharing-files-on-macos)

标签：C++, HTTP/2隧道, PipyJS, Rust, Tauri, Vite5, 全球网格, 去中心化网络, 可视化界面, 开源, 数据擦除, 端到端加密, 网格计算, 网络基础设施, 网络流量审计, 自定义脚本, 软件定义网络, 隐私优先, 零信任网络