维护远程设备

本页只适用于用控制台安装命令完成的标准安装。远程设备的本机程序叫 Z Tag Device（命令 ztag-device）；网络隧道使用不同的服务和目录，请看维护网络隧道。

设备只在安装它的用户登录期间运行。安装命令把它装成这个用户的后台服务：Linux 是 systemd 用户服务（systemctl --user），macOS 是 LaunchAgent，Windows 是登录时启动的计划任务。用户注销，或电脑重启后还没有登录时，设备不运行，控制台显示 离线。需要长期在线时，请保持这个用户登录；Linux 也可以由主机管理员为这个用户开启 lingering（loginctl enable-linger <用户名>）。

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

先选择操作

停止前先结束 ZAI 正在这台设备上执行的任务；停止操作可能中断命令、文件传输和桌面操作。关闭安装时的终端窗口不会退出已安装的后台设备服务。

沙箱配置把 ZAI 的命令放到这台设备上执行时（见命令在哪里执行），暂停连接、停止后台服务、设备程序重启或更新，都会结束 ZAI 在设备上启动的全部进程，包括它脱离出去留在后台的程序和它打开的桌面程序；推荐更新只等正在运行的命令结束，不等这些后台程序。设备被移出某个聊天的使用范围、或沙箱配置不再选这台设备时，那个聊天里的进程同样结束。需要长期使用的程序请自己启动，见设备上的进程。

只删除本地文件不能让 Z Tag 服务上的旧凭证失效。 本机管理界面的 取消接入 默认会同时撤销关联；如果只删除了本机凭证，请有这台设备管理权限的人在控制台打开设备详情，选择 更多 → 撤销关联。撤销后设备回到 待接入，资源和使用范围保留，备份中的旧凭证也会失效。仅暂停或临时离线时，不需要撤销关联。

优先使用下一节的本机管理界面；之后各系统的章节是等价的手工命令，供界面不可用时回退。请在安装设备时登录的系统用户下操作；其他用户的用户目录不同，找不到本页所说的路径和服务。

使用本机管理界面

设备程序自带本机管理界面，覆盖本页除卸载外的全部操作，并显示实时状态和日志。它只在本机运行，不需要额外安装，不会把凭证显示在屏幕或写入日志。

界面和命令行的提示按这台电脑的系统语言显示：系统语言是中文（含繁体中文）时显示简体中文，其他语言显示英文；系统没有设置语言时（例如 Linux 上只有 LANG=C.UTF-8）显示简体中文。本页按中文界面描述。要固定语言，打开界面或运行命令前设置环境变量 ZTAG_NATIVE_LOCALE，取值 zh-Hans 或 en，例如 ZTAG_NATIVE_LOCALE=en ztag-device ui；PowerShell 中先运行 $env:ZTAG_NATIVE_LOCALE = 'en'。界面语言与 ZAI 的回复语言设置无关。

打开方式：

• Linux 与 macOS：在安装设备的登录用户下打开终端，运行 ztag-device ui。安装命令会把 ztag-device 放到 ~/.local/bin；该目录不在 PATH 时，运行 ~/.local/bin/ztag-device ui。
• Windows：开始菜单选择“Z Tag Device”，或在原安装账户下打开 PowerShell 运行 ztag-device ui（安装命令已把 %LOCALAPPDATA%\z-tag\device\bin 加入用户 PATH，新开的窗口才会生效）。
• 找不到 ztag-device 命令或开始菜单项时：直接运行安装目录里的程序，即 install/releases/<版本>/bin/ztag-device（Linux 默认 ~/.local/share/ztag/device，macOS 默认 ~/Library/Application Support/z-tag/device，Windows 为 %LOCALAPPDATA%\z-tag\device）。在终端里不带参数直接运行程序，也会打开界面。

界面顶部显示当前状态：本机未接入、连接中、在线、离线、已暂停、凭证失效、凭证过期、服务启动中、停止中、已停止或未配置。「服务启动中」表示后台服务已在运行，但程序还没有响应界面。四个页签：

凭证过期时，概览 页签的「连接」一行提示「在控制台点“重新接入”后在本机接入」，做法见凭证有效期与续期。连接失败时，「上次失败：」后面是程序给出的英文原因。

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

操作与上表的对应关系：

• 暂停连接（临时退出）：可选 30 分钟、2 小时、到明天 08:00 或直到手动恢复。进程保留并继续接收自动更新，到期或选择 恢复连接 后自动重连。
• 停止 / 启动后台服务、关闭 / 开启自动启动：调用系统的服务管理器（systemd、launchd 或计划任务），与下文各系统的手工命令等价。
• 运行诊断：逐项检查状态目录、本机配置、本机凭证与私钥及其权限、网关公钥、Z Tag 服务、关联、凭证到期时间与状态，以及 Z Tag 服务记录的连接，按界面语言显示检查项和结果，与命令行 ztag-device doctor 是同一组检查。
• 接入 / 重新接入：在设备详情点 获取安装命令（设备已接入或已停用时按钮是 重新接入），把整条命令粘贴到输入框。命令里的一次性接入凭证在输入时被遮盖，只用于本次接入。设备已接入时，接入完成后原来的连接身份失效。本机已接入时，界面会先说明旧凭证的处理方式。
• 取消接入：按提示输入设备 ID 的前 4 位确认（提示中会显示完整 ID）。默认勾选「同时撤销关联（推荐）」：设备在控制台回到 待接入，使用范围保留，之后可以直接 获取安装命令 重新接入。取消勾选时只删除本机凭证，Z Tag 服务上的旧凭证仍然有效。有两种例外：
  • 本机凭证已过期时，关联仍在，本机撤销不了。「撤销关联」一步会失败并提示「本机凭证已过期，关联仍在；请在控制台打开资源详情执行“撤销关联”」，下方提示「只清除本机时，取消勾选“同时撤销关联”后重试。」，本机凭证不会被删除。请按提示在控制台撤销关联。
  • 设备已被停用或关联已撤销时，Z Tag 服务已不接受本机凭证。「撤销关联」一步显示「已跳过：Z Tag 服务已不接受本机凭证」，然后继续清除本机。已停用的设备在控制台仍保持关联，要重新接入时先在控制台撤销关联。
• 卸载：界面不执行卸载，请按下文各系统的章节操作。

命令行等价操作：ztag-device status --json 输出界面使用的完整状态；ztag-device pause --for 2h、ztag-device resume、ztag-device unpair --yes 分别对应暂停、恢复和取消接入，unpair 加 --keep-remote 表示只清除本机。按控制台安装命令安装的机器不需要加 --state-dir 参数。ztag-device help 列出全部命令，ztag-device <命令> -h 列出该命令的选项。

unpair 每一步结束时输出一行：行首是固定的英文步骤名，后接 =ok、=skipped (原因) 或 =failed (错误)。括号里的原因按系统语言显示，脚本只按步骤名与 ok、skipped、failed 判断结果，不要匹配括号里的文字。步骤名有 revoke_remote（撤销关联）、stop_service（停止后台服务）和 delete_identity（删除本机凭证与私钥），例如中文系统上 Z Tag 服务已不接受本机凭证时输出 revoke_remote=skipped (Z Tag 服务已不接受本机凭证)，本机凭证已过期时输出 revoke_remote=failed (本机凭证已过期，关联仍在；请在控制台打开资源详情执行“撤销关联”；只清除本机时加 --keep-remote)。没有执行的步骤不输出：加 --keep-remote 时没有 revoke_remote 一行，后台服务没有运行时没有 stop_service 一行。某一步失败后，命令不再执行后面的步骤，并以非零退出码结束，脚本要同时检查退出码。ztag-device doctor 也是每项检查一行（检查名=ok、检查名=failed (错误) 或 检查名=值），同样只有括号里的错误说明随系统语言变化。

进程未运行时，界面仍能读取接入信息、服务状态和日志文件；此时对暂停和防休眠的修改会先保存，下次启动生效。

防休眠与防锁屏

设备执行终端、文件和桌面操作时，系统休眠会中断任务；桌面锁定后无法操作界面。防休眠 页签提供三种模式：

• 关闭：不干预系统电源策略。
• 有任务时（默认）：任务开始时阻止系统休眠，最后一个任务结束一分钟后不再阻止。
• 始终：只要进程在运行就阻止系统休眠。

「同时阻止显示器关闭与空闲锁屏」默认关闭。开启后，空闲不再触发屏保和锁屏，这会削弱物理安全；只在需要远程操作桌面时开启，离开工位时请手动锁屏。「使用电池时也保持」默认关闭，即电池供电时不阻止休眠；需要时可单独开启。

该功能只使用操作系统提供的电源接口，不模拟键鼠输入，也不会解锁屏幕。组织通过组策略或 MDM 强制的锁屏与休眠策略优先生效；被策略覆盖或被系统拒绝时，页签显示「未能持有：显示器与锁屏」这样的提示，下面是系统给出的英文原因，此时请联系负责这台电脑的 IT 管理员调整策略。

Windows

在原来安装设备的账户下打开 PowerShell。设备的数据位于 %LOCALAPPDATA%\z-tag\device，计划任务名称为 z-tag Device。

查看状态

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

Running 表示后台任务正在运行，设备是否已连接仍以控制台的在线状态为准。正常后台运行不需要保留命令行窗口。

停止后台服务

下面的命令先停止计划任务，再结束仍在运行的设备进程；结束进程时只按安装目录定位，不会误伤其他同名程序：

& {
  $ErrorActionPreference = 'Stop'
  $deviceRoot = Join-Path $env:LOCALAPPDATA 'z-tag\device'
  Stop-ScheduledTask -TaskPath '\' -TaskName 'z-tag Device' -ErrorAction SilentlyContinue
  $owned = @(Get-CimInstance Win32_Process | Where-Object {
    $_.ExecutablePath -and $_.ExecutablePath.StartsWith(
      $deviceRoot + '\', [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(
      $deviceRoot + '\', [StringComparison]::OrdinalIgnoreCase
    )
  })
  if ($remaining.Count) { throw '仍有 Device 进程，请先处理停止失败' }
}

本机仍已接入，文件也会保留。计划任务仍启用时，下次登录可能再次启动设备。

关闭自动启动与恢复运行

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

Disable-ScheduledTask -TaskPath '\' -TaskName 'z-tag Device'

恢复时启用并启动任务，无需重新接入：

Enable-ScheduledTask -TaskPath '\' -TaskName 'z-tag Device'
Start-ScheduledTask -TaskPath '\' -TaskName 'z-tag Device'

取消接入

先关闭自动启动并执行“停止后台服务”，确认后台进程已经结束，再删除凭证和设备私钥：

& {
  $ErrorActionPreference = 'Stop'
  $stateDir = Join-Path $env:LOCALAPPDATA 'z-tag\device\state'
  foreach ($name in @('identity.json', 'host_key.pem')) {
    $path = Join-Path $stateDir $name
    if (Test-Path -LiteralPath $path) {
      Remove-Item -LiteralPath $path -Force
    }
  }
}

程序和原设备配置仍在，但本机已没有可用的凭证，只启动服务不能恢复接入。手工删除文件不会撤销关联，要重新接入同一设备：在控制台设备详情点 重新接入（设备显示 待接入 时是 获取安装命令）；在本机管理界面的 操作 页签先选择 开启自动启动，再在 接入 / 重新接入 中粘贴。要用控制台的完整安装命令重新接入，需先按下一节清理旧安装。

完整卸载

先关闭自动启动并完成“停止后台服务”。以下命令会删除计划任务、开始菜单的“Z Tag Device”和整个设备数据目录，包括安装包、各版本程序、ztag-device 命令、本地身份、日志及放在该目录内的备份：

& {
  $ErrorActionPreference = 'Stop'
  $task = Get-ScheduledTask -TaskPath '\' -TaskName 'z-tag Device' -ErrorAction SilentlyContinue
  if ($task -and $task.State -eq 'Running') { throw '请先停止后台服务' }
  if ($task) {
    Unregister-ScheduledTask -InputObject $task -Confirm:$false
  }
  $deviceRoot = Join-Path $env:LOCALAPPDATA 'z-tag\device'
  if (Test-Path -LiteralPath $deviceRoot) {
    $sid = [Security.Principal.WindowsIdentity]::GetCurrent().User.Value
    icacls.exe $deviceRoot /grant:r "*${sid}:F" /T /Q
    if ($LASTEXITCODE -ne 0) { throw '恢复删除权限失败，请查看下方排障说明' }
    Remove-Item -LiteralPath $deviceRoot -Recurse -Force
  }
  Remove-Item -LiteralPath (Join-Path $env:APPDATA 'Microsoft\Windows\Start Menu\Programs\Z Tag Device.lnk') -Force -ErrorAction SilentlyContinue
  Test-Path -LiteralPath $deviceRoot
}

最后应返回 False。安装时加入用户 PATH 的 %LOCALAPPDATA%\z-tag\device\bin 条目不会被删除；目录已不存在，留着不影响使用，也可以在“编辑账户的环境变量”中手动删掉这一项。

如果旧文件的所有者或权限导致删除失败，请在同一安装账户的管理员 PowerShell 中，仅对该目录执行以下操作，再重试卸载：

$deviceRoot = Join-Path $env:LOCALAPPDATA 'z-tag\device'
takeown.exe /F $deviceRoot /R /A /D Y
icacls.exe $deviceRoot /grant:r '*S-1-5-32-544:F' /T /Q

macOS

在安装设备的桌面登录用户下打开“终端”，这些命令都不使用 sudo。数据目录为 ~/Library/Application Support/z-tag/device，启动项为 ~/Library/LaunchAgents/com.ztag.device.plist。

查看状态与停止后台服务

查看服务：

launchctl print "gui/$(id -u)/com.ztag.device"

停止后台服务要用下面的命令让当前登录会话不再加载该启动项，而不是只结束设备子进程：

launchctl bootout "gui/$(id -u)/com.ztag.device"

启动项文件保留，本机仍已接入；下次登录仍可能自动运行。如果提示找不到服务，说明该登录会话中已经没有加载它；遇到权限或其他错误时先处理，再继续后面的清除或卸载步骤。

关闭自动启动与恢复运行

关闭后续登录时的自动启动，再按上一节停止后台服务：

launchctl disable "gui/$(id -u)/com.ztag.device"

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

launchctl enable "gui/$(id -u)/com.ztag.device"
if ! launchctl print "gui/$(id -u)/com.ztag.device" >/dev/null 2>&1; then
  launchctl bootstrap "gui/$(id -u)" "$HOME/Library/LaunchAgents/com.ztag.device.plist"
fi
launchctl kickstart "gui/$(id -u)/com.ztag.device"

取消接入

先关闭自动启动并停止后台服务，再删除凭证和设备私钥：

rm -f -- \
  "$HOME/Library/Application Support/z-tag/device/state/identity.json" \
  "$HOME/Library/Application Support/z-tag/device/state/host_key.pem"

程序、配置和启动项仍在，但只恢复服务不能重新接入。手工删除文件不会撤销关联，要重新接入同一设备：在控制台设备详情点 重新接入（设备显示 待接入 时是 获取安装命令）；在本机管理界面的 操作 页签先选择 开启自动启动，再在 接入 / 重新接入 中粘贴。要用控制台的完整安装命令重新接入，需先按下一节清理旧安装。

完整卸载

先完成“停止后台服务”，确认当前登录会话已不再加载该服务，再删除启动项、ztag-device 命令和全部本地数据：

rm -f -- "$HOME/Library/LaunchAgents/com.ztag.device.plist"
rm -f -- "$HOME/.local/bin/ztag-device"
rm -rf -- "$HOME/Library/Application Support/z-tag/device"

卸载后 launchctl print "gui/$(id -u)/com.ztag.device" 应找不到服务，数据目录也应不存在，新开的终端中 command -v ztag-device 应无输出。如果此前执行过 launchctl disable，将来重新安装前先运行本页的 launchctl enable 命令，清除保留的禁用状态。

完整卸载不删除 ZAI 在设备上执行命令用的工作目录 ~/ZTag/sessions。在同一台电脑上为这台设备重新接入后，原来的 Session 在原目录继续、文件都在，之前留在后台的程序已经结束，需要时让 ZAI 重新启动；不再需要这些文件时，可以手动删除这个目录。

Linux

在安装设备的用户下执行 systemctl --user，不要替换成系统级 sudo systemctl。下面的路径跟随安装时的 XDG_DATA_HOME、XDG_STATE_HOME、XDG_CONFIG_HOME；若修改过这些环境变量，先用 systemctl --user cat ztag-device.service 确认实际目录。

查看状态与停止后台服务

systemctl --user status --no-pager ztag-device.service

停止服务及其子进程，保留程序，本机仍已接入：

systemctl --user stop ztag-device.service

inactive 表示已停止。服务仍处于启用状态时，下次登录后仍可能自动启动；控制台的在线状态可能稍后才更新为离线。

关闭自动启动与恢复运行

一直保持停止，直到手动恢复：

systemctl --user disable --now ztag-device.service

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

systemctl --user enable --now ztag-device.service

取消接入

先关闭自动启动并停止服务，再删除凭证和设备私钥：

(
  set -eu
  systemctl --user disable --now ztag-device.service
  device_state_dir="${XDG_STATE_HOME:-$HOME/.local/state}/ztag/device"
  rm -f -- "$device_state_dir/identity.json" "$device_state_dir/host_key.pem"
)

上面的命令只删除本机凭证和设备私钥，程序目录不受影响。手工删除文件不会撤销关联，要重新接入同一设备：在控制台设备详情点 重新接入（设备显示 待接入 时是 获取安装命令）；在本机管理界面的 操作 页签先选择 开启自动启动，再在 接入 / 重新接入 中粘贴。要用控制台的完整安装命令重新接入，需先按下一节清理旧安装。

完整卸载

停止并停用服务，然后删除服务文件、ztag-device 命令、各版本程序和状态目录：

(
  set -eu
  systemctl --user disable --now ztag-device.service
  rm -f -- "${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user/ztag-device.service"
  systemctl --user daemon-reload
  rm -f -- "$HOME/.local/bin/ztag-device"
  rm -rf -- \
    "${XDG_DATA_HOME:-$HOME/.local/share}/ztag/device" \
    "${XDG_STATE_HOME:-$HOME/.local/state}/ztag/device"
)

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

完整卸载不删除 ZAI 在设备上执行命令用的工作目录 ~/ZTag/sessions。在同一台电脑上为这台设备重新接入后，原来的 Session 在原目录继续、文件都在，之前留在后台的程序已经结束，需要时让 ZAI 重新启动；不再需要这些文件时，可以手动删除这个目录。

重新接入与常见问题

• 只暂停或停止了服务，没有取消接入：在本机管理界面选择 恢复连接 或 启动后台服务，或按对应系统的章节恢复服务，不需要新的安装命令。
• 界面显示「凭证失效」或「凭证过期」：先看控制台里这台设备的状态，按情况处理。
  • 控制台显示 已停用：在设备详情选择 更多 → 启用。凭证没到期的话，设备约一分钟内自动重连，不需要新的安装命令。
  • 控制台显示 待接入（关联已撤销）：点 获取安装命令，在本机管理界面的 接入 / 重新接入 中粘贴。
  • 本机显示「凭证过期」，控制台里设备仍是已接入（通常显示 离线）：这台电脑连续 90 天没连上 Z Tag，见凭证有效期与续期。在控制台设备详情点 重新接入，在本机 接入 / 重新接入 中粘贴。这时本机的 取消接入 撤销不了关联。
• 本机已取消接入，或要改为另一台远程设备：设备在控制台仍是已接入时，先在控制台撤销关联。要改为另一台设备，先在本机 取消接入（默认同时撤销原设备的关联），再从目标设备的详情点 获取安装命令，在本机 接入 / 重新接入 中粘贴；也可以完整卸载后执行目标设备的完整安装命令。安装命令有有效期，过期后需要重新生成。
• 新版本读不了本机保存的设备配置：自动更新到这样的版本时启动失败，设备恢复上一版继续运行，控制台详情里的 版本 不变；直接运行这样的版本时，本机管理界面显示「未配置」，概览 页签的「本机配置」一行和 ztag-device status 提示「本机配置 … 无法使用；请重新接入」。要用新版本，设备在控制台仍是已接入时先在设备详情选择 更多 → 撤销关联，再按对应系统的「完整卸载」清理，然后点 获取安装命令 运行新命令。只在上一版的本机管理界面里重新接入，下次自动更新仍会失败。
• 安装命令报错 ztag-install: already-installed：旧安装记录或进程仍存在。先停止服务并按卸载步骤清理，不要只删除安装目录里的个别文件后重装。其他失败代码见安装失败。
• 接入时提示本机身份仍关联 Z Tag 服务上的另一个资源：这台电脑上次接入的身份仍关联着另一个远程设备，它可能属于其他组织。先在控制台打开原设备详情执行 撤销关联，或在本机执行 取消接入，再重试同一条安装命令。这次的安装命令没有被使用，有效期内可以直接重试。
• 同一用户执行另一台远程设备的完整安装命令：安装会被拒绝，原来的接入保留，新的安装命令不会被使用，也不会出现第二个本地实例（标准安装使用固定的目录和任务名）。要改为另一台设备，按上面「改为另一台远程设备」一条操作。
• 卸载后控制台中还有设备：本地卸载不会删除控制台里的设备。有这台设备管理权限的人可以在控制台撤销关联或删除资源，见停用、撤销与删除。
• 安装曾被强制中断：程序目录内的残留版本随完整卸载删除。安装器通常会清理系统临时下载目录；如需手工处理残留，只删除已确认属于这次安装的临时目录，不要清空整个系统临时目录。

手工在前台运行的进程可以用 Ctrl+C 退出；若由后台服务启动，应停止对应服务，否则程序可能被自动重新启动。