跳到主要内容

故障排除

本文提供 XTerminal 常见问题的详细排查步骤和解决方案。

连接超时​

症状​

  • 连接时显示"连接超时"或"Connection timed out"
  • 连接进度条卡住，最终失败

排查步骤​

1. 检查网络连通性

# 测试服务器是否可达
ping 服务器地址

# 测试 SSH 端口是否开放
telnet 服务器地址 22
# 或
nc -zv 服务器地址 22

2. 确认服务器信息

检查项说明
IP 地址/域名确认无拼写错误
端口号默认 22，确认服务器实际端口
SSH 服务状态确认服务器 SSH 服务正在运行

3. 检查防火墙

  • 本地防火墙是否阻止了出站连接
  • 服务器防火墙是否开放了 SSH 端口
  • 云服务器安全组是否放行了 SSH 端口

4. 调整超时设置

如果网络延迟较高，可以增加超时时间：

  1. 编辑连接配置
  2. 进入 连接设置 选项卡
  3. 增加 超时时间（如 30000 毫秒）

5. 使用代理连接

如果需要通过代理访问服务器：

  1. 编辑连接配置
  2. 进入 代理设置 选项卡
  3. 配置代理地址（支持 SOCKS5 和 HTTP 代理）

认证失败​

症状​

  • 提示"Authentication failed"或"认证失败"
  • 密码正确但无法登录
  • 密钥认证不通过

密码认证失败​

1. 核对凭证信息

检查项注意事项
用户名区分大小写，注意空格
密码检查特殊字符，避免复制时带入隐藏字符

2. 检查服务器配置

确认服务器允许密码认证：

# 查看 SSH 配置
cat /etc/ssh/sshd_config | grep PasswordAuthentication

如果显示 PasswordAuthentication no，需要改为 yes 并重启 SSH 服务。

3. 检查账户状态

  • 账户是否被锁定（多次失败后可能触发）
  • 账户是否过期
  • 是否有 IP 白名单限制

密钥认证失败​

1. 确认私钥路径

  • 私钥文件是否存在
  • 路径是否正确（使用绝对路径）
  • 文件是否可读

2. 确认公钥已部署

检查服务器上的 authorized_keys：

cat ~/.ssh/authorized_keys

确认包含对应的公钥内容。

3. 检查文件权限

服务器上的权限要求严格：

# 正确的权限设置
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys
chmod 600 ~/.ssh/私钥文件

4. 检查私钥格式

  • 推荐使用 ED25519 或 RSA 格式
  • 如果使用 PuTTY 格式（.ppk），需要转换为 OpenSSH 格式

5. 私钥密码

如果私钥有密码保护，确保在连接时正确输入私钥密码。

2FA 认证失败​

1. 使用交互认证

将连接的 验证方式 设置为 交互认证。

2. 检查时间同步

TOTP 验证码依赖时间同步，确保：

  • 本地设备时间准确
  • 与服务器时间偏差不超过 30 秒

连接断开​

症状​

  • 连接使用一段时间后自动断开
  • 显示"Connection reset"或"Broken pipe"
  • 终端无响应后断开

排查步骤​

1. 调整心跳设置

在连接的 连接设置 中：

设置项建议值说明
心跳时间5000-10000毫秒，防止空闲断开

2. 检查服务器配置

查看服务器的 SSH 超时设置：

cat /etc/ssh/sshd_config | grep -E "ClientAlive|TCPKeepAlive"

建议服务器配置：

ClientAliveInterval 60
ClientAliveCountMax 3
TCPKeepAlive yes

3. 网络稳定性

  • 检查网络是否稳定
  • 无线网络可能因信号问题断开
  • VPN 连接可能有超时限制

4. 开启自动重连

在 设置 > SSH 服务 中开启自动重连相关选项。

SFTP 无法打开​

症状​

  • 点击文件管理器无响应
  • SFTP 连接失败
  • 文件列表无法加载

排查步骤​

1. 确认 SSH 连接正常

SFTP 依赖 SSH 连接，先确保终端连接正常。

2. 检查服务器 SFTP 子系统

确认服务器启用了 SFTP：

cat /etc/ssh/sshd_config | grep Subsystem

应该有类似配置：

Subsystem sftp /usr/lib/openssh/sftp-server

3. 检查用户权限

  • 用户是否有访问目标目录的权限
  • 是否被 chroot 限制在特定目录

4. 检查磁盘空间

服务器磁盘空间不足可能导致 SFTP 异常：

df -h

上传/下载失败​

症状​

  • 传输过程中断
  • 显示权限错误
  • 传输速度为 0

排查步骤​

1. 检查目标目录权限

# 查看目录权限
ls -la /目标目录

# 检查当前用户
whoami

确保用户对目标目录有写入权限。

2. 检查磁盘空间

位置检查命令
服务器df -h
本地检查本地磁盘剩余空间

3. 文件名特殊字符

某些特殊字符可能导致传输失败：

  • 中文文件名（编码问题）
  • 特殊符号（*, ?, <, > 等）

尝试重命名文件后再传输。

4. 网络问题

  • 大文件传输对网络稳定性要求高
  • 检查是否有带宽限制
  • 尝试分批传输或压缩后传输

5. 检查传输队列

点击底部状态栏的传输图标，查看：

  • 是否有任务卡住
  • 错误信息详情
  • 尝试取消后重新传输

端口转发不生效​

症状​

  • 端口转发显示成功但无法访问
  • 本地端口无响应
  • 连接转发的端口被拒绝

本地转发（-L）排查​

1. 确认转发规则

参数说明
本地端口本地监听端口，确保未被占用
远程地址从 SSH 服务器角度可访问的地址
远程端口目标服务端口

2. 检查本地端口占用

# macOS/Linux
lsof -i :本地端口

# Windows
netstat -ano | findstr :本地端口

3. 确认远程服务可达

在 SSH 服务器上测试：

telnet 远程地址 远程端口
# 或
curl -v telnet://远程地址:远程端口

远程转发（-R）排查​

1. 检查服务器配置

远程转发需要服务器允许：

cat /etc/ssh/sshd_config | grep GatewayPorts

如需外部访问，设置为 GatewayPorts yes。

2. 检查服务器防火墙

确保服务器防火墙允许转发端口的入站连接。

动态转发（-D）排查​

1. 确认 SOCKS 代理配置

  • 本地监听端口是否正确
  • 客户端代理设置是否指向正确的端口
  • 代理协议选择 SOCKS5

2. 测试代理

curl --socks5 127.0.0.1:本地端口 https://httpbin.org/ip

应用卡顿​

症状​

  • 应用启动慢
  • 操作响应延迟
  • 界面无响应

解决方案​

1. 禁用硬件加速

路径：设置 > 系统配置 > 禁用硬件加速

某些显卡驱动可能导致兼容性问题。

2. 切换渲染模式

路径：设置 > 通用终端 > 高级配置 > 渲染模式

选择 最佳兼容（DOM） 模式。

3. 减少资源占用

操作路径
减少保存行数设置 > 通用终端 > 基础配置 > 保存行数
关闭会话录制设置 > 通用终端 > 会话记录
关闭命令补全设置 > 通用终端 > 命令提示
关闭服务器监控设置 > SSH 服务 > 列表监控

4. 清理连接

  • 关闭不使用的连接标签页
  • 减少同时打开的分屏数量

5. 重启应用

如果出现内存泄漏，重启应用可以释放资源。

数据丢失恢复​

症状​

  • 连接配置丢失
  • 设置被重置
  • 快速命令消失

恢复方法​

1. 从自动备份恢复

XTerminal 默认开启每日自动备份：

  1. 打开 设置 > 备份恢复
  2. 点击 打开备份目录
  3. 找到最近的备份文件
  4. 点击 导入备份 选择备份文件

2. 从手动备份恢复

如果之前手动导出过数据，可以直接导入。

3. 从云端恢复

如果启用了云端同步：

  1. 确保登录相同账户
  2. 切换到 云端仓库
  3. 数据会自动同步

预防措施​

1. 开启自动备份

路径：设置 > 备份恢复 > 每日自动备份

2. 定期手动备份

重要配置更改后，手动点击 立即备份。

3. 使用云端同步

登录账户并设置同步密码，数据会加密同步到云端。

日志查看方法​

当遇到难以解决的问题时，查看日志可以帮助定位原因。

方法一：调试台（开发者工具）​

  1. 打开 设置 > 系统配置
  2. 点击 打开调试台
  3. 切换到 Console 标签查看日志
  4. 切换到 Network 标签查看网络请求

方法二：日志文件​

  1. 打开 设置 > 系统配置
  2. 点击 打开日志目录
  3. 查看日志文件

日志文件位置：

系统路径
macOS~/Library/Logs/XTerminal/
Windows%USERPROFILE%\AppData\Roaming\XTerminal\logs\
Linux~/.config/XTerminal/logs/

日志信息说明​

级别含义
INFO正常信息
WARN警告，可能有问题
ERROR错误，需要关注

反馈问题​

如果以上方法都无法解决问题，请通过以下渠道反馈：

官方反馈论坛：https://host.terminal.icu/

反馈时请提供​

  1. 环境信息

    • 操作系统及版本
    • XTerminal 版本号
    • 硬件配置（如有性能问题）

  2. 问题描述

    • 详细的操作步骤
    • 期望的结果
    • 实际的结果
    • 错误提示信息

  3. 相关日志

    • 控制台日志截图
    • 日志文件（脱敏后）

  4. 截图或录屏

    • 问题现象截图
    • 操作过程录屏（如有必要）

相关文档​