远程设备与网络隧道

远程设备 让 ZAI 在一台已接入的电脑上执行命令、读写文件和操作桌面，适合处理只在这台电脑上的文件、应用和登录状态；这些文件不在 ZAI 自己的沙箱里。网络隧道 安装在企业网络里的一台主机上，只向 Z Tag 建立出站连接，让获得授权的请求到达内网服务。两者都是先在控制台新建资源，再在目标电脑上运行一次性的安装命令完成接入。

远程设备的本机程序叫 Z Tag Device（命令 ztag-device）。网络隧道的本机程序叫 Z Tag Network Connector（命令 ztag-network-connector），它和控制台里的 连接器 是两种不同的资源。

谁可以做：在控制台里，组织的远程设备和网络隧道由组织 Owner 新建、接入、停用、撤销和删除，其他角色看到的这些按钮为禁用，并提示 需要 Owner 角色。成员可以在 我的资源 里新建只供自己使用的设备和隧道，操作与本页相同，见在控制台管理自己的资源。

安装命令

• 安装命令里含有一次性接入凭证，命令只显示一次。对话框下方写着「安装命令仅显示一次，其中的一次性接入凭证有效至……」，命令在这个时间前有效，只能使用一次；重新生成后，之前没用过的命令立即失效。
• 命令只显示给发起操作的人。不要转发、截图或保存到团队文档。

接入远程设备

1. 进入 组织管理 → 远程设备，点 新建。
2. 填写名称。按需填写 使用指令（可选），它会提供给 ZAI，写法与长度上限见怎样写使用指令。在 使用范围 里选一个初始范围，或保持 稍后分配。点 创建。
3. 对话框随即切换为 接入远程设备 并显示安装命令。选择 Windows、macOS 或 Linux，登录这台电脑上准备给 ZAI 使用的系统用户，在这个用户下运行命令：Windows 在 PowerShell 中运行，macOS 和 Linux 在终端中运行，不需要 sudo。没来得及运行的话，之后可以在设备详情点 获取安装命令 重新生成。
4. 等待状态变为 在线，在详情里核对 主机 和 系统（含 CPU 架构）。版本 在设备第一次连接 Z Tag 后显示。
5. 在详情的 使用范围 标签确认授权，再在用得到这台设备的群或私聊里让 ZAI 做一次只读操作，例如列出某个目录，确认设备可用。

设备以运行安装命令的系统用户身份在后台运行，不会自动获得管理员权限，Windows 上也不需要保留命令行窗口。它只在这个用户登录期间工作：用户注销，或电脑重启后还没有登录时，设备显示 离线。需要长期在线的设备，请保持这个用户登录；Linux 也可以由主机管理员为这个用户开启 lingering。

组织设备的 使用范围 可以是 整个组织、Workspace 或 Channel（某一个群），让对应的群使用；也可以是指定成员或 全体成员，让他们在自己和 ZAI 的私聊里使用。各类资源能授权给谁、全体成员与优先级，见范围设置；授权给指定成员和开放申请，见成员授权与审批。

接入后，在这台电脑上用安装设备的用户运行 ztag-device ui，可以打开本机管理界面，查看状态和日志，暂停连接、取消接入或设置防休眠，见维护远程设备。

接入网络隧道

1. 进入 组织管理 → 网络隧道，点 新建。填写名称，使用指令（可选） 可以留空，点 创建。对话框随即显示安装命令。
2. 在目标企业网络里一台稳定运行的主机上执行命令：Windows 以管理员身份打开 PowerShell；macOS 和 Linux 用一个可以使用 sudo 的账号在终端中直接运行，命令会在需要时自己调用 sudo。隧道作为系统服务运行，开机后自动启动，不依赖某个用户登录。
3. 等待状态变为 在线。在线只表示隧道已连到 Z Tag，不代表内网目标可达。
4. 让请求经过这条隧道，有两种做法。一是在连接器里指定：打开连接器，点名称旁的编辑（铅笔）按钮，在 网络隧道 中选择它，见连接器指定隧道。二是添加内网路由：在沙箱配置详情的 内网路由 里点 添加路由，也可以在隧道详情的 内网路由 → 添加路由 中选择沙箱配置后添加，并把协议、地址和端口收窄到需要的范围，见添加内网路由。模型上游 也可以直接指定这条隧道，见经过网络隧道。
5. 在用得到这条隧道的群或私聊里让 ZAI 发起一次最小的请求，确认企业 DNS、目标可达和业务认证都正常。

上面这些用法都要求隧道在线；隧道不可用时请求直接失败，不会改走公网。

一条隧道可以接入多台主机，每台是它的一个 节点，最多 8 台。各节点地位相同：每个请求随机经一台在线节点转发，这台连不上时自动换下一台。要加主机，在隧道详情点 添加节点，在新主机上运行新命令；每条安装命令只能接入一台主机，还没用掉、也没过期的安装命令同样计入 8 台。隧道详情的 节点 列表逐台显示主机、版本、状态和最近在线时间。

成员通过已指定这条隧道的组织连接器使用时，不需要另外授权。成员要在自己的连接器、沙箱配置或模型上游里引用这条隧道，需要先在隧道详情的 使用范围 标签里把它授予这位成员或 全体成员，见引用组织的网络隧道。

接入后，在主机上以管理员权限运行 ztag-network-connector ui，可以打开本机管理界面，查看状态和日志，暂停连接或重新接入，见维护网络隧道。

安装失败

安装命令失败时会输出一行 ztag-install: <代码>: <说明>：macOS 和 Linux 上是最后一行，Windows 上在红色的错误信息里。说明是英文，可能随版本调整，请按代码判断；在它之前输出的几行是失败的那一步自己的报错，例如本机程序按系统语言给出的原因。安装命令里的接入凭证到接入那一步才使用，接入那一步及之后的失败都可能已经用掉它，其中也包括这些步骤里报的 interrupted 和 unexpected-error。各代码的处理见下表。

凭证有效期与续期

接入成功后，设备和隧道的每个节点各自持有一份凭证。凭证在使用中自动续期：只要还在连接 Z Tag，凭证就一直有效，续期不更换凭证，也不中断连接；连续一段时间没有连上 Z Tag，凭证才会失效：

• 这两个时长是默认值，Z Tag 管理员可以调整。设备停用期间连不上 Z Tag，同样计入。
• 本机管理界面 概览 页签的「凭证」一行显示到期时间，连上 Z Tag 后随续期更新；剩不到 7 天时注明「连上 Z Tag 后自动续期」。控制台不显示到期时间。
• 失效后，本机管理界面显示「凭证过期」。设备不再接收任务，在控制台显示 离线；隧道断开，指定它的连接器、引用它的内网路由和模型上游都会失败。
• 设备凭证过期后，本机的 取消接入 无法撤销关联，请在控制台设备详情点 重新接入，见维护远程设备。

停用、撤销与删除

远程设备：

• 更多 → 停用：临时禁止使用。关联和使用范围都保留，设备不再接受新操作，本机显示「凭证失效」。恢复时选 更多 → 启用，凭证没到期的话，设备约一分钟内自动重连，不需要重新接入。
• 更多 → 撤销关联：对话框说明「原设备的连接身份将失效，使用范围保留。」设备回到 待接入，详情里的主机信息和版本清空，备份里的旧凭证也一并失效。之后点 获取安装命令 就能重新接入，也可以换一台电脑接入；换了电脑时，在这台设备上执行命令的 Session 在新电脑上的空工作目录里继续，见工作目录与文件。在本机管理界面 取消接入 时保留勾选「同时撤销关联（推荐）」，效果相同。
• 重新接入：已接入或已停用的设备，详情里的按钮显示为 重新接入，用于换电脑、重装或凭证过期后恢复。在要用的电脑上粘贴新命令完成接入前，原来的电脑照常工作；接入后原电脑的连接身份失效，详情里的主机信息换成新电脑的，使用范围保留，停用的设备接入后仍是停用。换了电脑时，在这台设备上执行命令的 Session 在新电脑上的空工作目录里继续，见工作目录与文件。
• 删除资源：删除设备和它的使用范围，删除对话框会写明影响几个使用范围。电脑上的程序不会自动卸载。
• 沙箱配置选了这台设备来执行命令时（见命令在哪里执行），设备详情的 在此设备上执行命令的沙箱配置 一节列出这些配置，成员的个人配置只显示成员名、不能打开。对它们的影响：
  • 停用或撤销关联：这些配置下在设备上进行的一轮失败，ZAI 在设备上启动的进程随之结束；设备恢复后，Session 在原来的工作目录继续。停用前会先确认，撤销关联的确认框会列出这些配置。
  • 删除：组织的沙箱配置还选着这台设备时不能删除，删除对话框会列出它们，先为它们改选运行方式或其他设备。成员的个人配置不阻止删除：删除时这些配置改为 在沙箱中执行，它的所有者会在私聊里收到一条说明。成员自己的设备被他自己的沙箱配置选着时，同样要先改选才能删除。

网络隧道：

• 添加节点：生成新命令，在一台主机上运行后，这台主机成为隧道的又一个节点。用于增加主机、迁移主机或续期凭证，资源、使用范围和引用都保留。
• 节点 → 移除：这台主机的连接身份立即失效，不再接入这条隧道，其余节点继续工作；移除最后一台节点后隧道离线，直到再添加节点。迁移、重装或续期后，原节点不会自动移除，一直显示离线，要在这里移除。
• 更多 → 撤销网络隧道：对话框说明「原连接身份失效，指定它的连接器、引用它的内网路由和模型上游不可用；资源不会自动删除。」撤销不能恢复：隧道显示 已撤销，不能再接入，也不能添加路由。需要时新建一条隧道（可以沿用原来的名称）并接入，再把连接器、内网路由和模型上游改为指定新隧道。
• 删除资源：已接入的隧道要先撤销，否则菜单里提示「请先撤销网络隧道」。仍有连接器、内网路由或模型上游引用它时，删除会被拒绝，删除对话框和隧道详情的 相关资源 会列出这些配置。从未接入的隧道可以直接删除。
• 组织隧道也可能被成员自己的连接器、沙箱配置的内网路由或模型上游引用。这些配置标注为该成员的个人配置，只能由他本人删除或改用其他隧道；收回成员的引用权不会删除这些配置。

状态

远程设备没有「已撤销」状态，撤销关联后回到 待接入。

控制台的状态可能比本机晚一些更新。

远程设备能做什么

• 执行命令或打开终端。
• 读取、写入和管理设备上的文件。
• 截图、查看窗口和操作桌面应用。

设备每次连上 Z Tag 时报告当前能用的能力，例如没有图形桌面的电脑不提供桌面操作。所有操作都以安装设备的系统用户身份执行，不会自动获得管理员权限。

上面这些是 ZAI 在云端沙箱里工作时对设备逐项发起的操作。沙箱配置还可以把 ZAI 执行命令、读写文件的地方整个放到一台 Linux 或 macOS 设备上：这样的聊天里命令直接在那台设备上执行，本节的终端、文件传输、截图和桌面操作都不能用，见在远程设备上执行时。

Windows 设备不支持需要在终端里边运行边应答的命令行程序，例如逐步提问的命令行向导、全屏终端工具；普通命令、脚本、文件操作和桌面操作（包括图形界面的安装程序）都可以用。

macOS 设备第一次截图或操作桌面时，系统会提示为 CuaDriver（设备附带的桌面操作组件）授权。请这台电脑的用户在 系统设置 → 隐私与安全性 中为 CuaDriver 打开 辅助功能 和 录屏与系统录音。授权跟随 CuaDriver 的签名，重新安装或更新设备后仍然有效。

电脑休眠会中断进行中的操作，屏幕锁定后无法操作桌面，设置方法见防休眠与防锁屏。成员使用设备时怎样说明目标，见使用远程设备时说明目标。

文件传输

• ZAI 在设备确认文件已完整写入后，才报告上传成功。
• 传输连续 60 秒没有进展就会失败，不会断点续传。设备断线或操作取消后，等设备恢复再重新传输。
• 单个文件的大小上限见下一节。

限制

下面三项是默认上限，Z Tag 管理员可能调低：

• 单个命令或操作最长运行 1 小时。
• 同一台设备同时最多处理 8 个操作，超出时请稍后重试。
• 单个文件最大 256 MiB。

一个目录超过 1024 项时无法直接列出，可以让 ZAI 改用命令按条件筛选。使用指令的长度上限见怎样写使用指令。

沙箱配置把命令放到设备上执行时（见命令在哪里执行），另有一项名额，与上面的 8 个操作分开计算：一台设备同时最多为 15 个 ZAI 的沙箱执行命令（默认上限，Z Tag 管理员可能调低）。每个在设备上工作的话题用一个自己的沙箱，各占一个名额；沙箱闲置一会儿后不再占用名额。名额满时，后到的一轮等待片刻仍没有空位就失败，提示「执行命令的远程设备同时执行的任务已达上限，请稍后重试。」

自动更新

用安装命令接入的设备和隧道会自动检查 Z Tag 发布的新版本。推荐更新先在后台下载，等持续空闲后静默安装；只要有命令、终端、文件传输或隧道连接正在进行，更新就会延后。隧道的长连接即使没有流量，也算正在使用。

强制更新会停止接收新任务，并给已有任务留出结束时间。到时仍未结束的任务或连接会被中断，升级期间设备或隧道可能短暂不可用。更新保留关联和使用范围，不需要重新获取安装命令。

新版本启动失败时会恢复上一版，并且不再反复安装同一个失败的版本。新版本用不了本机保存的配置、连接身份或安装记录时同样启动失败，这时要完整卸载后用新的安装命令重新接入，见维护远程设备与维护网络隧道。如果要求升级的截止时间已过、当前版本仍然过低，设备会暂停接收任务，隧道不再接受新连接，直到成功安装要求的版本。

资源详情里的 版本 是程序最近一次上报的运行版本，自动更新后随之变化；网络隧道在 节点 列表里逐台显示，升级后下方另注接入时的版本。远程设备撤销关联后版本清空，重新接入并连接后再显示。各节点各自更新，互不等待。