维护网络隧道

本页只适用于用控制台安装命令完成的标准安装。网络隧道的本机程序叫 Z Tag Network Connector（命令 ztag-network-connector），与控制台里的 连接器 无关。它作为系统级服务运行，开机后自动启动，不依赖用户登录；命令、权限和目录都与用户级的远程设备不同，远程设备请看维护远程设备。

网络隧道的连接身份在使用中自动续期，节点连续 90 天没连上 Z Tag 才失效；到期时间看本机管理界面 概览 页签的「凭证」一行，详见凭证有效期与续期。

先选择操作

停止前先确认没有正在通过这条隧道执行的任务。停止或卸载会中断现有连接，使指定它的连接器、引用它的内网路由和模型上游暂时不可用，不会自动改走公网。仅临时停止时，恢复原服务即可继续使用原有关联和路由，不需要重新获取安装命令。

本地删除文件不能让 Z Tag 服务上的旧凭证失效。 若要让它失效，请有这条隧道管理权限的人在控制台打开隧道详情，选择 更多 → 撤销网络隧道，再清理本机。旧连接身份及其备份会失效，指定它的连接器、引用它的内网路由和模型上游也会不可用；资源不会因此自动删除。

已撤销的网络隧道不能再次接入。之后如需恢复这条接入，应新建网络隧道，并更新连接器、内网路由或模型上游对它的引用；新建的网络隧道可以沿用已撤销隧道的名称。若只是把同一条未撤销的隧道迁到另一台电脑，可以保留资源，用 添加节点 生成新命令，在新电脑上接入后，在隧道详情的 节点 列表里移除原来的主机。

优先使用下一节的本机管理界面；之后各系统的章节是等价的手工命令。

使用本机管理界面

网络隧道程序自带本机管理界面，覆盖本页除卸载以外的全部操作，并显示实时状态和日志。它读取的状态目录只对服务账户开放，因此需要管理员权限运行：

• Linux 与 macOS：sudo ztag-network-connector ui。安装命令会把 ztag-network-connector 放到 /usr/local/bin。
• Windows：以管理员身份打开 PowerShell，运行 ztag-network-connector ui（安装命令已把 %ProgramData%\z-tag\network-connector\bin 加入系统 PATH，新开的窗口才会生效）。
• 找不到 ztag-network-connector 命令时：直接运行安装目录里的程序，即 install/releases/<版本>/bin/ztag-network-connector（Linux 默认 /var/lib/ztag-network-connector，macOS 默认 /Library/Application Support/z-tag/network-connector，Windows 为 %ProgramData%\z-tag\network-connector）。

界面和命令行的提示按主机的系统语言显示：系统语言是中文（含繁体中文）时显示简体中文，其他语言显示英文；系统没有设置语言时（例如 Linux 上只有 LANG=C.UTF-8）显示简体中文。本页按中文界面描述。用 sudo 运行时，按 sudo 之后的环境变量与管理员账户（root）的设置判断，不一定与你终端里的语言一致。要固定语言，设置环境变量 ZTAG_NATIVE_LOCALE，取值 zh-Hans 或 en，例如 sudo env ZTAG_NATIVE_LOCALE=en ztag-network-connector ui；PowerShell 中先运行 $env:ZTAG_NATIVE_LOCALE = 'en'。界面语言与 ZAI 的回复语言设置无关。

界面顶部显示当前状态：本机未接入、连接中、在线、离线、已暂停、凭证失效、凭证过期、服务启动中、停止中或已停止。「在线」表示 Z Tag 会经这台主机转发；本机已取得隧道配置、但 Z Tag 暂时不经它转发时显示「连接中」。本机暂时取不到最新配置时也显示「连接中」，概览 页签的「连接」一行写「配置刷新失败」，程序会自动重试。「服务启动中」表示后台服务已在运行，但程序还没有响应界面。内网目标是否可达还需要实际连接验证。凭证过期时，「连接」一行提示「在控制台“添加节点”后在本机接入」，做法见凭证有效期与续期。连接失败时，「上次失败：」后面是程序给出的英文原因。

界面有四个页签：

• 概览：接入、凭证（含到期时间）、连接、后台服务与自动启动、更新版本、防休眠、Z Tag 服务记录的状态、最近日志。
• 日志：运行时显示实时日志，停止时显示已保存的日志文件；f 切换跟随，g / G 跳到顶部或底部。
• 防休眠：选项见防休眠。
• 操作：接入 / 重新接入、取消接入、暂停连接 / 恢复连接、停止 / 启动后台服务、关闭 / 开启自动启动、运行诊断。

按键：数字 1 到 4 或 tab 切换页签，↑ ↓ 选择，enter 执行，space 切换选项，esc 返回，r 刷新，q 退出界面。退出界面不影响后台服务。

操作与上表的对应关系：

• 暂停连接（临时退出）：可选 30 分钟、2 小时、到明天 08:00 或直到手动恢复。进程保留并继续接收自动更新，但断开与 Z Tag 服务的连接并拒绝新连接；到期或选择 恢复连接 后自动重连。依赖这条隧道的连接器、内网路由和模型上游在此期间不可用。
• 停止 / 启动后台服务、关闭 / 开启自动启动：与下文各系统章节的手工命令等价。
• 运行诊断：逐项检查本机连接身份、中继 CA 证书、Z Tag 服务、Z Tag 服务下发的配置、凭证到期时间与状态，以及 Z Tag 服务记录的连接，按界面语言显示检查项和结果，与命令行 ztag-network-connector doctor 是同一组检查。
• 接入 / 重新接入：在控制台的隧道详情选择 获取安装命令 或 添加节点，把整条命令粘贴到输入框。命令里的一次性接入凭证在输入时被遮盖，只用于本次接入；接入成功即替换本机的连接身份，这台主机成为隧道的一个新节点，后台服务未运行时会随之启动。本机原来的节点在控制台显示离线，不再使用时在 节点 列表里移除。
• 取消接入：需要按提示输入界面显示的隧道 ID 前 4 位确认，只停止服务并删除本机连接身份与中继 CA 证书。要让旧凭证失效，仍需在控制台撤销这条网络隧道；界面会提示「在 Z Tag 服务上撤销网络隧道不可逆，会让指定它的连接器、内网路由和模型上游不可用，请在控制台操作。」
• 卸载：界面不执行卸载，请按下文各系统的章节操作。

命令行等价操作：ztag-network-connector status 输出接入、凭证到期和连接状态，加 --json 输出界面使用的完整状态；ztag-network-connector doctor 额外检查本机文件和与 Z Tag 服务的连通性。pause --for 30m、resume、unpair --yes 分别对应暂停、恢复和取消接入。标准安装可以省略 --state-file。ztag-network-connector help 列出全部命令，ztag-network-connector <命令> -h 列出该命令的选项。

unpair 每一步结束时输出一行：行首是固定的英文步骤名，后接 =ok、=skipped (原因) 或 =failed (错误)。括号里的原因按系统语言显示，脚本只按步骤名与 ok、skipped、failed 判断结果，不要匹配括号里的文字。步骤名有 stop_service（停止后台服务）和 delete_identity（删除本机连接身份与中继 CA 证书）。没有执行的步骤不输出，例如后台服务没有运行时没有 stop_service 一行。某一步失败后，命令不再执行后面的步骤，并以非零退出码结束，脚本要同时检查退出码。doctor 也是每项检查一行（检查名=ok、检查名=failed (错误) 或 检查名=值），同样只有括号里的错误说明随系统语言变化。

防休眠

网络隧道所在主机进入休眠后，隧道连接会中断。防休眠 页签默认关闭，只能阻止系统休眠，没有显示器和锁屏选项。选 有任务时，有连接经过隧道时阻止休眠，最后一个连接结束一分钟后不再阻止；选 始终，进程运行期间一直阻止休眠。「使用电池时也保持」默认关闭，即电池供电时不阻止休眠；需要时可单独开启。该功能只使用操作系统提供的电源接口，不修改系统电源策略。

Linux 上服务以专用系统账户 ztag-network-connector 运行，需要主机管理员通过 polkit 为这个账户授予 org.freedesktop.login1.inhibit-block-sleep 权限后才能阻止休眠；未授权时页签显示「未能持有：系统休眠」和系统给出的英文原因，主机沿用自己的电源策略。

Windows

在管理员 PowerShell 中执行。数据目录为 %ProgramData%\z-tag\network-connector，计划任务名称为 z-tag Network Connector，由系统账户运行，使用电池供电时也会启动并保持运行。

安装被拒绝

安装命令会把 %ProgramData%\z-tag 设为只有管理员和系统可以修改，普通用户只能读取和执行。安装报错 ztag-install: untrusted-root，说明这个目录不是之前的安装建立的；报错 ztag-install: reparse-point，说明其中有联接点或符号链接，提示会给出路径。删除提示中的联接点，或删除 %ProgramData%\z-tag 后重新执行安装命令；这台主机已经装有网络隧道时，先按完整卸载清理。其他失败代码见安装失败。

查看状态

Get-ScheduledTask -TaskPath '\' -TaskName 'z-tag Network Connector' |
  Select-Object TaskName, State

Running 只说明后台任务正在运行。是否已连接以及内网目标是否可达，还需查看控制台状态并发起实际连接验证。

停止后台服务

停止计划任务后，结束属于此安装目录的残留进程树：

& {
  $ErrorActionPreference = 'Stop'
  $connectorRoot = Join-Path $env:ProgramData 'z-tag\network-connector'
  Stop-ScheduledTask -TaskPath '\' -TaskName 'z-tag Network Connector' -ErrorAction SilentlyContinue
  $owned = @(Get-CimInstance Win32_Process | Where-Object {
    $_.ExecutablePath -and $_.ExecutablePath.StartsWith(
      $connectorRoot + '\', [StringComparison]::OrdinalIgnoreCase
    )
  })
  $ownedIds = @($owned.ProcessId)
  $owned | Where-Object { $_.ParentProcessId -notin $ownedIds } |
    ForEach-Object { taskkill.exe /PID $_.ProcessId /T /F }
  Start-Sleep -Seconds 1
  $remaining = @(Get-CimInstance Win32_Process | Where-Object {
    $_.ExecutablePath -and $_.ExecutablePath.StartsWith(
      $connectorRoot + '\', [StringComparison]::OrdinalIgnoreCase
    )
  })
  if ($remaining.Count) { throw '仍有网络隧道进程，请先处理停止失败' }
}

该命令保留程序，本机仍已接入。计划任务仍启用时，下次开机可能恢复运行。

关闭自动启动与恢复运行

若希望一直保持停止，先关闭自动启动，再执行上面的“停止后台服务”：

Disable-ScheduledTask -TaskPath '\' -TaskName 'z-tag Network Connector'

恢复时启用并启动任务：

Enable-ScheduledTask -TaskPath '\' -TaskName 'z-tag Network Connector'
Start-ScheduledTask -TaskPath '\' -TaskName 'z-tag Network Connector'

取消接入

先关闭自动启动并完成“停止后台服务”，再删除本地连接身份及中继 CA 证书：

& {
  $ErrorActionPreference = 'Stop'
  $stateDir = Join-Path $env:ProgramData 'z-tag\network-connector\state'
  foreach ($name in @('state.json', 'relay-ca.pem')) {
    $path = Join-Path $stateDir $name
    if (Test-Path -LiteralPath $path) {
      Remove-Item -LiteralPath $path -Force
    }
  }
}

程序仍在，但已经没有本机连接身份，只恢复计划任务不能恢复连接。要重新接入这条隧道或改接另一条隧道，在控制台的目标隧道详情选择 获取安装命令 或 添加节点；在本机管理界面的 操作 页签先选择 开启自动启动，再在 接入 / 重新接入 中粘贴，后台服务会随之启动。只有要用完整安装命令重装时，才需要先按下一节完成“完整卸载”。

完整卸载

先关闭自动启动并完成“停止后台服务”。以下命令删除计划任务、程序、所有版本和本地状态； 也会删除放在该数据目录内的安装备份：

& {
  $ErrorActionPreference = 'Stop'
  $task = Get-ScheduledTask -TaskPath '\' -TaskName 'z-tag Network Connector' -ErrorAction SilentlyContinue
  if ($task -and $task.State -eq 'Running') { throw '请先停止后台服务' }
  if ($task) {
    Unregister-ScheduledTask -InputObject $task -Confirm:$false
  }
  $connectorRoot = Join-Path $env:ProgramData 'z-tag\network-connector'
  if (Test-Path -LiteralPath $connectorRoot) {
    takeown.exe /F $connectorRoot /R /A /D Y | Out-Null
    if ($LASTEXITCODE -ne 0) { throw '取得目录所有权失败' }
    icacls.exe $connectorRoot /grant:r '*S-1-5-32-544:F' /T /Q
    if ($LASTEXITCODE -ne 0) { throw '恢复删除权限失败' }
    Remove-Item -LiteralPath $connectorRoot -Recurse -Force
  }
  Test-Path -LiteralPath $connectorRoot
}

最后应返回 False。若仍提示文件占用，先核对“停止后台服务”的结果，不要仅结束一个隧道子进程。

ztag-network-connector 命令随数据目录一起删除；安装时加入系统 PATH 的 %ProgramData%\z-tag\network-connector\bin 条目不会被删除，留着不影响使用，也可以在系统环境变量中手动删掉这一项。

macOS

网络隧道安装为系统 LaunchDaemon，以下管理命令需要 sudo。数据目录为 /Library/Application Support/z-tag/network-connector，启动项为 /Library/LaunchDaemons/com.ztag.network-connector.plist。

查看状态与停止后台服务

查看服务：

sudo launchctl print system/com.ztag.network-connector

停止后台服务：

sudo launchctl bootout system/com.ztag.network-connector

该操作保留启动项，本机仍已接入；下次开机仍可能自动运行。此服务会自动重启子进程，因此仅使用进程管理器结束隧道进程，不能可靠地保持退出。如果提示找不到服务，说明它已不在系统中加载；权限或其他错误需要先处理。

关闭自动启动与恢复运行

关闭自动启动，再按上一节停止后台服务：

sudo launchctl disable system/com.ztag.network-connector

恢复时重新启用，并在尚未加载时加载启动项：

sudo launchctl enable system/com.ztag.network-connector
if ! sudo launchctl print system/com.ztag.network-connector >/dev/null 2>&1; then
  sudo launchctl bootstrap system /Library/LaunchDaemons/com.ztag.network-connector.plist
fi
sudo launchctl kickstart system/com.ztag.network-connector

取消接入

先关闭自动启动并停止后台服务，再删除本地连接身份及中继 CA 证书：

sudo rm -f -- \
  "/Library/Application Support/z-tag/network-connector/state/state.json" \
  "/Library/Application Support/z-tag/network-connector/state/relay-ca.pem"

要重新接入这条隧道或改接另一条隧道，在控制台的目标隧道详情选择 获取安装命令 或 添加节点；在本机管理界面的 操作 页签先选择 开启自动启动，再在 接入 / 重新接入 中粘贴，后台服务会随之启动。只有要用完整安装命令重装时，才需要先按下一节完成“完整卸载”。

完整卸载

先完成“停止后台服务”，确认服务已不再加载，再删除启动项、ztag-network-connector 命令和全部数据：

sudo rm -f -- /Library/LaunchDaemons/com.ztag.network-connector.plist
sudo rm -f -- /usr/local/bin/ztag-network-connector
sudo rm -rf -- "/Library/Application Support/z-tag/network-connector"

卸载后 sudo launchctl print system/com.ztag.network-connector 应找不到服务，数据目录也应不存在，新开的终端中 command -v ztag-network-connector 应无输出。如果此前执行过 launchctl disable，将来重新安装前先执行对应的 launchctl enable，清除保留的禁用状态。

Linux

网络隧道使用系统级 systemd 服务 ztag-network-connector.service，管理命令需要 sudo。不要使用远程设备的 systemctl --user 命令。

标准安装使用以下路径：

查看状态与停止后台服务

sudo systemctl status --no-pager ztag-network-connector.service

停止服务及其子进程：

sudo systemctl stop ztag-network-connector.service

inactive 表示已停止。本机仍已接入，已启用的服务下次开机仍可能恢复；控制台可能稍后才显示为离线。

关闭自动启动与恢复运行

关闭自动启动并立即停止：

sudo systemctl disable --now ztag-network-connector.service

恢复自动启动并立即运行：

sudo systemctl enable --now ztag-network-connector.service

取消接入

先关闭自动启动并停止服务，再删除本机连接身份。Linux 的程序目录也放在 /var/lib/ztag-network-connector 下面；只想取消接入时，不要删除整个目录。

(
  set -eu
  sudo systemctl disable --now ztag-network-connector.service
  sudo rm -f -- \
    /var/lib/ztag-network-connector/state.json \
    /var/lib/ztag-network-connector/relay-ca.pem \
    /var/lib/ztag-network-connector/enrollment-token
)

程序仍保留，但重新启动服务不会自动接入。要重新接入这条隧道或改接另一条隧道，在控制台的目标隧道详情选择 获取安装命令 或 添加节点；在本机管理界面的 操作 页签先选择 开启自动启动，再在 接入 / 重新接入 中粘贴，后台服务会随之启动。只有要用完整安装命令重装时，才需要先按下一节完成“完整卸载”。

完整卸载

(
  set -eu
  sudo systemctl disable --now ztag-network-connector.service
  sudo rm -f -- /etc/systemd/system/ztag-network-connector.service
  sudo systemctl daemon-reload
  sudo rm -f -- /usr/local/bin/ztag-network-connector
  sudo rm -rf -- \
    /var/lib/ztag-network-connector \
    /etc/ztag-network-connector \
    /usr/local/lib/ztag-network-connector
)

如果服务文件已经不存在，先确认隧道进程已停止，再继续删除目录。卸载后 sudo systemctl status ztag-network-connector.service 应显示找不到该服务，新开的终端中 command -v ztag-network-connector 应无输出。

安装器创建的专用系统账户可以保留；服务移除后它不会自动启动隧道。如果确认 ztag-network-connector 账户仅用于此安装，也可以删除它：

sudo userdel ztag-network-connector

重新接入与常见问题

• 只暂停或停止了服务：在本机管理界面选择 恢复连接 或 启动后台服务，或按对应系统的章节恢复服务；控制台里已撤销的隧道不能靠启动服务恢复。
• 界面显示「凭证失效」或「凭证过期」：先在控制台查看这条隧道。
  • 显示 已撤销：不能再接入，按下面「原网络隧道已在控制台撤销」一条新建。
  • 这台主机已从 节点 列表移除（例如隧道已迁到另一台电脑）：本机按卸载步骤清理即可；要继续使用这台主机，在隧道详情选择 添加节点 重新接入。
  • 凭证到期，或要让这台电脑继续使用：在隧道详情选择 添加节点，在本机 接入 / 重新接入 中粘贴新命令，再在 节点 列表里移除这台主机原来的节点。有效期见凭证有效期与续期。
• 本机已取消接入，或要改接另一条隧道：在控制台的目标隧道详情选择 获取安装命令 或 添加节点，把整条命令粘贴到本机管理界面的 接入 / 重新接入 中，后台服务未运行时会随之启动。改接其他隧道后，原隧道上这台主机的节点不会自动移除，不再使用时在原隧道的 节点 列表里移除。只有要用完整安装命令重装时，才需要先完整卸载。新命令需要在有效期内完成接入。
• 新版本用不了本机保存的连接身份或安装记录：自动更新到这样的版本时启动失败，隧道恢复上一版继续运行，控制台详情里的 版本 不变；连接身份用不了时，直接运行这样的版本会提示「本机连接身份 … 无法使用；请重新接入」。要用新版本，按对应系统的「完整卸载」清理，再在控制台的隧道详情选择 添加节点，运行新命令，并移除原节点。只在上一版的本机管理界面里重新接入，下次自动更新仍会失败。
• 节点列表里有离线的旧主机：每次接入都新增一个节点，重装、换主机或续期后原节点不会自动移除，一直显示离线。确认不再使用后，在隧道详情的 节点 列表里移除。一台主机上只运行一套服务。
• 添加节点提示已达上限：一条隧道最多 8 台节点，还没用掉、也没过期的安装命令同样计入。移除不用的节点，或等安装命令过期后再添加。
• 原网络隧道已在控制台撤销：新建网络隧道再接入，并修改原有连接器、内网路由或模型上游的引用；新建的网络隧道可以沿用已撤销隧道的名称。已撤销的隧道不能通过重装恢复。
• 提示已有安装或已有 launcher：安装记录或进程还在。先停止服务并完整卸载，不要只删除个别文件后直接覆盖程序。
• 卸载后控制台还有隧道：本地卸载不删除控制台里的隧道。要删除控制台里已接入的隧道，先 撤销网络隧道，再处理引用它的连接器、内网路由或模型上游，仍有引用时删除会被拒绝，见停用、撤销与删除。
• 安装曾被强制中断：程序目录内的残留版本随完整卸载删除。安装器通常会清理系统临时下载；手工清理时只删除已确认属于本次安装的临时目录，不要清空系统临时目录。

手工前台运行时可用 Ctrl+C 退出。无论采用哪种运行方式，要让旧凭证失效，都应在控制台撤销对应的网络隧道。