故障排查

先确认问题发生在哪一层：浏览器/控制面板、节点、实例，还是具体应用或 AI 会话。不要把“界面暂时无法连接”等同于实例已经停止。

节点离线

在“设置 → 节点”查看连接方式和诊断信息。
确认远程主机在线，Node Agent 服务正在运行。
检查防火墙、DNS、TLS 和代理配置。
本机节点缺失时，尝试“添加本地节点”重新同步。
恢复连接后刷新实例状态。

服务器上可检查整体状态：

sh

task-handoff status
task-handoff check

实例无法创建或启动

Docker 检查失败：在目标节点安装并启动 Docker daemon；
镜像拉取失败：展开拉取详情，检查镜像引用、仓库认证和网络；
一直停留在注册中：检查 Node Agent 到实例的回调地址和端口；
实例不健康：查看错误详情，必要时重启实例；
Local Runtime 创建失败：确认同一宿主用户没有另一个本地实例。

节点离线时不要立即删除实例。缓存状态可能不是最新状态，应先恢复节点连接。

AI 会话无法启动

确认实例为“运行中”且连接在线；
检查实例是否分配了与目标 Agent 兼容的模型 Provider；
在“设置 → 模型”测试 Provider 的端点与密钥；
确认工作目录仍然存在且实例用户可以访问；
配置变更后，按界面提示重启实例再创建新会话。

仓库功能不可用

仓库页面需要当前会话具有有效工作目录，并且目录属于 Git worktree。根据错误提示检查：

实例内是否安装 Git；
工作目录是否存在并位于授权范围；
会话是否仍然活跃；
仓库是否存在冲突、脏工作区或过期快照。

复杂冲突、分叉分支、Git hook 或签名问题应在会话终端中处理，完成后刷新仓库页面。

Git 远端认证失败

打开“实例设置 → Git 凭据”。
检查是否存在唯一且匹配 remote 的保留授权。
HTTPS Token 失效时轮换凭据；SSH 模式还需检查固定 host key。
保存后手动重试 Fetch、Pull、Publish 或 Push。

系统不会自动重试失败的远端写操作，也不会尝试 force push。

页面持续重连

确认浏览器可以稳定访问控制面板，并检查反向代理是否支持 WebSocket。刷新页面会重新读取权威快照，不会主动停止实例中的任务。

收集诊断信息

向管理员或维护人员反馈时，请提供：

问题发生时间和时区；
控制面板、节点、实例和会话名称或 ID；
可重复的操作步骤；
页面错误信息和状态截图；
对应节点或服务日志中的相关片段。

不要在截图和日志中包含 API 密钥、Git Token、密码、一次性加入令牌或 SSH 私钥。