故障排查
后端状态横条
Termia 的终端、主机与文件功能都由本机的一个后台进程提供服务。一旦这个进程没有完全连上,窗口的 标签条与内容区之间就会出现一条状态横条;一切正常时,这条横条不占任何空间,也什么都不显示。它有 两种状态:
- 正在重新连接 —— 一个转圈图标加"正在重新连接后端…"。这是自动发生的(比如 Mac 睡眠又唤醒 之后),不需要你做任何事。
- 后端已停止 —— 一个警告图标加一句"后端已停止(
<reason>),终端不再接受输入",配两颗按钮: 重启后端(原地重启本机进程并重新连上你打开的窗口,不会关掉它们)和退出应用。
横条显示这两种状态期间,终端看起来仍然有焦点、仍然能敲字,但每一次按键都会被丢弃——不会攒起来 等连接恢复后补发。断线期间第一次往任意终端里敲键,会弹出一条通知——"后端未连接,按键已丢弃"—— 把这件事说清楚,免得你对着一个已经死掉的终端敲了半天字却不知道为什么。同一轮断线里这条通知只提示 一次,不会因为你继续敲字而反复弹出;下一轮新的断线开始时才会再提示一次。
所有打开的窗口都在看同一条后端连接,所以会同时显示同一种状态。
通知
标签条上有一个铃铛图标;一旦有未读内容就会带上角标。点开它会出现通知中心——一个可以滚动的列表, 带一颗清除已读按钮;每一条通知自己还带一个关闭按钮,有时还有一颗动作按钮(重试、在访达中显示、 登录……视通知内容而定)。
同样的事件也会在发生的那个窗口右上角弹出一只气泡,停留大约五秒后并入列表。少数通知会标成"待处理", 不会自己消失——它们代表一件还等着你处理的事,比如登录已经过期。如果你关掉了某只气泡而同一个问题 又发生了一次,它会再弹一次,即便底层是"同一条"通知——这是故意的,不是 bug:重点是告诉你这件事 还在发生,而不只是发生过一次。窗口非常窄时,气泡会整体让位,只剩铃铛角标更新。
不管是什么通知的正文——包括直接从一次失败的连接或命令原样带过来的错误文字——只要其中有看起来像
密码、API key、bearer token、JWT 或长十六进制串的内容,展示或复制之前都会先被替换成 •••。
连接失败或断开
SSH 连接失败或断开时会显示一句大白话的原因(被拒绝、主机名无法解析、超时、认证失败等),下面 附着原始错误文字,并给出重试或不必重新输入就能改地址的入口——每种提示的确切含义,以及"重连" 「修改地址」两颗按钮各自带你去哪里,见主机库的完整说明。
唯一一个在主机库页面之外的相关开关是:从上次会话恢复出来的远端标签页要不要自动重连,这一项在
设置 的通用 → 启动一节里。无论开关如何,断开的远端连接都不会让远端进程继续活着
——重连总是开一个全新的 shell,除非你在那台主机上用了 tmux 或 screen。
终端退出
敲 exit,或者 shell 自己结束,都会关掉那个面板;如果它是所在标签页里唯一的面板,标签页也会
跟着关闭。默认情况下这个动作立即发生、不会询问,除非「关闭运行中会话前确认」是开着的(默认就是开
的)且这个面板里还有东西在跑——命令、SSH 连接、TT Agent,或未保存的全屏程序——这时关闭这个面板、
它的标签页、窗口,或退出应用都会先问一句。空闲的终端永远直接关闭、不弹窗。这个开关见
设置 的窗口 → 开关窗口一节。
配置文件无法读取或格式有误
settings.json 存在应用的配置目录里,与 connections.json、termthemes.json、presets.json
放在一起——目录具体在哪见快速上手,或者直接打开
设置 → 高级 → 打开 settings.json…,用它的在访达中显示按钮直接定位。
如果你(或别的工具)在 Termia 之外改了这个文件,改出了语法错误,后端会因为解析不了而整份忽略它 ——所有设置都会静默退回默认值,而不是启动时崩溃或报错。修复的办法还是同一个内置编辑器:从高级页 重新打开它,它的语法检查会先指出到底是哪一行哪一列出了问题,再允许你重新保存。这个编辑器本身不 可能写出一份坏文件——每次保存都会先检查一遍,语法有问题就会拦住保存,把光标移过去,而不是把内容 写下去。它还会提醒你(但不会拦住保存)某个键写了两遍(只有最后一次生效)、或者某个键 Termia 不认识(会被保存下来,但读回来时静默忽略)。
如果设置窗口本身完全读不到你的配置——多半是因为后端连不上——每一页都会显示"读取配置失败"和一颗 重试按钮,而不是悄悄退回默认值。这是故意的:把看起来像默认值的东西显示出来,再让你保存覆盖 掉真实配置,比老实告诉你"读取失败"要糟糕得多。
生成用于反馈的诊断包

帮助 → 导出诊断包… 会先问你存到哪里,然后写出一个名为 termia-diagnostics-<时间戳>.zip
的压缩包,内含:
summary.txt—— 应用与系统版本、架构、配置与数据目录路径、内存占用,以及后端版本。settings.json、connections.json、termthemes.json、presets.json,其中每一处看起来敏感 的值都已遮盖。recent.log—— 应用自己最近的内部日志。- 在
~/Library/Logs/DiagnosticReports下找到的、属于这个应用的最近三份崩溃报告。
密码、token、API key、Vaults 内容与终端正文永远不会被打进包里:只要在上面这些文件里出现了看起来 像这些东西的内容,都会按通知同一套规则遮盖。导出完成后会弹出一条带在访达中显示按钮的通知, 方便你把这个 zip 附到反馈里;导出失败则会弹出一条不会自动消失的错误通知。
恢复到干净的状态
- 应用完全启动不起来 —— 会弹出一个标题为"Termia 无法启动"的提示框,说明原因(核心程序缺失 或不可执行、安装可能已损坏、或者恢复上次会话失败),并给出重试(重跑一遍同样的启动步骤) 与退出两个选项。你永远不会被晾在一个"应用在跑、但没有窗口、也没有任何可做的事"的状态里。
- 后端在跑但卡住了 —— 先试试状态横条上的重启后端,再考虑退出应用;它会原地重启本机进程 并重新连上你打开的窗口,不会把它们关掉。
- 设置看起来不对但说不清哪里错了 —— 打开设置 → 高级 → 打开 settings.json…, 在编辑器里全选、删除、保存。空文件是合法的,所有设置会在这一步里一并重置为默认值。
- 需要看看磁盘上到底有什么 —— 设置 → 关于 → 诊断 → 打开数据目录,会在访达里直接打开你的 本地数据库、Vaults 资料库与日志所在的文件夹。