跳到正文

故障排查

排障时先保护正在运行的任务。不要因为客户端显示异常就立即删除 terminal、history、endpoint 或 credential；先确认问题属于客户端显示、daemon 状态、授权还是网络 route。

快速诊断

按顺序执行，并从第一条失败的命令开始处理：

anytty --version
anytty config validate
anytty config paths
anytty daemon doctor
anytty daemon status
anytty endpoint list

远程 endpoint 再逐条测试 route：

anytty endpoint show ENDPOINT
anytty endpoint test ENDPOINT --route ROUTE

endpoint list 只读本地 registry，不会拨号；endpoint test 才会建立连接并验证 AnyTTY protocol 可达性。

安装后找不到命令

  1. 重新打开 terminal，让 shell 重新读取 PATH。
  2. 检查安装脚本输出的目标目录是否在 PATH 中。
  3. 在 Windows 上重新打开 PowerShell，再用 Get-Command anytty 检查解析结果。
  4. 不要跳过 release checksum；校验失败时重新下载，并确认代理没有替换响应。
  5. 用绝对路径运行 anytty --version，区分安装失败与 PATH 问题。

daemon 无法启动或连接

anytty daemon doctor
anytty daemon status
anytty daemon logs --lines 200
  • doctor 报路径或 ownership 错误时，先检查当前用户、runtime 目录和 socket；不要用 root 启动来绕过权限问题。
  • 配置解析失败时执行 anytty config validate，修复未知字段、类型或范围。
  • 后台服务状态不清晰时，先停止后台实例，再用 anytty daemon run 前台观察错误；不要同时运行两个实例。
  • 升级后异常时核对 anytty --version、实际二进制路径和 changelog，避免 CLI 与服务版本混用。

TUI 显示或输入异常

  • 先扩大宿主 terminal，确认不是过小 viewport 导致 panel 收起。
  • 检查宿主的 UTF-8、颜色和鼠标支持；必要时切换 tui.theme.palette 或暂时关闭鼠标。
  • 快捷键无响应时检查自定义 tui.shortcuts。显式配置一个 scene 会替换该 scene 的默认 bindings。
  • terminal 尺寸不同步时使用 anytty terminal resize，并检查是否有另一个客户端正在持有 resize ownership。
  • 在另一个 AnyTTY terminal 内启动 TUI 默认会被 nested guard 拦截。只有明确理解递归交互影响时才设置 ANYTTY_ALLOW_NESTED=1。
  • Live 画面异常不等于 history 丢失。用 anytty terminal capture 或 anytty history search 单独验证权威历史。

配对失败

  • claim 默认 10 分钟过期且只能兑换一次；重新生成，不要重复使用旧字符串。
  • 检查两台设备的系统时间。明显时钟偏差会让有效期判断失败。
  • 用 anytty pair inspect CLAIM 查看 claim metadata，但不要把输出公开分享。
  • 如果新请求的 scope 比本地已有授权更宽，pair import 会拒绝静默扩权；只有确认后才使用 --allow-scope-expansion。
  • 配对成功但无法访问某个 terminal 或 file 时，检查 grant scope，而不是重复注册 route。
  • 遗失设备用 anytty access list 找到 grant，再执行 anytty access revoke GRANT。

Route 连接失败

Local

Local 依赖当前用户 daemon socket。检查 daemon status 和 config paths，并确认 CLI 与 daemon 属于同一个系统用户。

SSH

先用系统 ssh 命令确认账号、密钥、代理跳板和 host key。AnyTTY 默认通过远端 loopback signaling 127.0.0.1:41120 和 ICE-TCP 127.0.0.1:41121 建立 SSH route；端口可配置。host key pin 不匹配时先确认服务器是否真的更换密钥，不能直接关闭验证。

Direct

确认 daemon 正在预期的 HOST:PORT 监听，并检查主机防火墙、NAT 和企业网络。通配监听会扩大局域网暴露范围；不要为了排障直接把端口开放到公网。

Cloud

anytty cloud status
anytty cloud edge list

先区分 daemon 未 enrollment、Cloud 被 disable、P2P 不可达和 Relay 用量/订阅限制。P2P 失败并不自动说明 daemon 授权失败；Relay 成功也不会扩大 grant。

文件操作失败

  • file list、stat 或 cat 失败时先确认 endpoint 和完整路径，路径必须落在 daemon 允许的文件范围内。
  • 上传、移动、重命名遇到目标已存在时，先核对目标；不要为了通过命令而默认覆盖。
  • 下载完成但 checksum 失败时保留本地临时结果用于诊断，不要把它当作可信文件使用。
  • 预览失败不代表文件不可下载。先看 stat 与文件类型，再下载到受信任的本地工具打开。
  • 大文件和不稳定网络可能超过默认 2 分钟 operation timeout；在确认传输仍健康后显式增加 file --timeout。

收集脱敏信息

支持请求通常需要：

  • anytty --version 与操作系统/CPU 架构
  • 复现步骤、预期结果、实际结果和发生时间
  • 失败命令的退出状态和完整错误文本
  • daemon status、daemon doctor 与相关日志片段
  • endpoint 类型和失败的 route 类型

提交前删除私钥、claim、grant、Cloud token、IP、主机名、用户名、真实路径、terminal 内容和文件内容。不要上传整个配置目录或 history 目录。

一般性产品疑问见常见问题。仍无法定位故障时，按版本、支持与参与项目提供最小、脱敏的复现。