EasySSH_

文档中心

用户使用文档与开发指南 · 与仓库文档源（docs-src）保持一致

目录

用户使用文档： 下载与安装 · 首次运行与 SmartScreen · 建立连接与会话 · 终端操作 · SFTP 文件传输 · 快捷命令栏 · 密钥工具 · 设置中心 · config.json 便携说明 · 断线重连 · 常见故障排查
开发指南： 技术栈 · 目录结构 · 本地开发 · 打包与发布 · 参与贡献 · 网站自动同步机制

用户使用文档

EasySSH 是一款 Windows 绿色版 SSH/SFTP 终端，参考 SecureCRT 使用体验设计，免安装、随文件夹携带。

1. 下载与安装

EasySSH 为绿色版软件，无需安装，提供两种形态：

  • exe 单文件绿色版：下载 EasySSH-<版本号>.exe，双击即用。会话与配置均存放在 exe 同目录，整个目录可直接拷贝到 U 盘或其他电脑携带。
  • zip 解压版：下载 EasySSH-<版本号>-win32-x64-portable.zip，解压到任意目录后运行其中的 exe。适合希望将程序与数据放在固定文件夹管理的用户。
提示：建议始终从官网 easyssh.cn 下载，并用下载页提供的 sha256 值校验文件完整性。

2. 首次运行与 SmartScreen 提示

exe 目前未做代码签名，首次在 Windows 上运行时，Windows Defender SmartScreen 会弹出「已保护你的电脑」提示，属于正常现象：

  1. 在 SmartScreen 弹窗中点击「更多信息」；
  2. 点击「仍要运行」。

该提示只在首次运行时出现一次。若从非官方渠道获得的文件报此提示，请先核对 sha256。

3. 建立连接与会话

连接参数：点击新建会话，填写主机地址、端口（默认 22）、用户名，并选择认证方式：

  • 密码认证：直接输入服务器密码。可勾选「保存会话」将密码随会话记录保存（注意：密码为明文保存在本机配置文件中，不可信环境请勿勾选）。
  • 私钥文件认证：选择本地私钥文件（见第 7 节密钥工具）。
  • keyboard-interactive 自动适配：使用 tryKeyboard + keyboard-interactive 标准认证流程，多数开启交互式认证的服务器可自动适配。

会话管理：会话按主机 + 端口 + 用户名去重保存，重复记录启动时自动清理。所有会话与设置自 v2.2.0 起统一保存在 exe 同目录的 config.json 中（旧 sessions.json / settings.json 自动迁移），随文件夹携带。

4. 终端操作

  • 多标签：一个窗口内可同时打开多个 SSH 会话标签。
  • 断线重连：断开后标签保留，在终端中按回车即自动重连，失败可继续按回车重试。
  • 回滚缓冲：支持 5000 行回滚查看历史输出。
  • keepalive：内置 keepalive 保持长时间连接不中断。
  • 窗口自适应：终端随窗口大小自动调整行列数，支持 256 色。
  • 连接状态：连接时状态栏实时倒计时（超时上限 30 秒）；失败时显示错误首行，并按认证失败/超时/拒绝连接给出中文排查建议。

5. SFTP 文件传输

内置 SFTP 文件传输面板：浏览远程目录（支持上级目录与跳转路径）、上传（多选文件）、下载（双击远程文件即可）。

传输模式与编码，传输时可选择：

  • 二进制（原样，推荐）：按字节原样传输，适用于程序、压缩包、图片等一切非文本文件。
  • 文本转换：按设置中心选择的编码执行转换，适合在 Windows 与中文 Linux 服务器之间交换文本/脚本文件：
    • 下载：服务器编码 → UTF-8，换行统一为 CRLF；
    • 上传：UTF-8 → 服务器编码，换行统一为 LF；
    • 转换使用的临时文件会自动清理。
注意：若文本传输后中文乱码，请确认设置中心的编码与服务器实际编码一致（GBK 系编码对中文服务器乱码通常有效）。

6. 快捷命令栏

  • 自定义常用命令为按钮（如 systemctl status nginx、df -h）；
  • 点击按钮即把命令发送到当前终端执行；
  • 支持增加、删除管理，皮肤配色同样覆盖快捷命令栏。

7. 密钥工具

认证方式选「私钥文件」时，界面出现密钥工具区：

  1. 一键生成密钥：在本机生成 Ed25519 密钥对。v2.3.2 起私钥采用标准 OpenSSH 格式（openssh-key-v1，未加密），ssh2 可直接使用；生成后自动填入私钥路径。
  2. 公钥上传：界面显示公钥内容，可复制后手工追加到服务器 ~/.ssh/authorized_keys。
  3. 安装到当前已连服务器：在已用密码连接的会话中一键把公钥写入服务器（幂等，自动设置目录 700 / 文件 600 权限），完成后即可改用私钥登录。
  4. 旧密钥自动兼容：v2.3.2 起连接时检测到旧版本（v2.3.0/2.3.1）生成的 PKCS#8 私钥（Ed25519/RSA/EC）会自动转换为可解析格式，旧密钥无需重新生成。

密钥保存在 exe 同目录的 keys/ 目录下，随文件夹携带，请妥善保管。

8. 设置中心

  • 字体：5 种可选；字号：自定义终端字号。
  • 编码：UTF-8 / GBK / GB18030 / Big5。GBK 系编码对中文服务器乱码有效。
  • 皮肤：Dracula / 纯黑 / Solarized / 浅色 / Matrix 共 5 款配色。v2.2.0 起皮肤覆盖整个应用界面（侧栏、工具栏、弹窗、状态栏、快捷命令栏），自绘标题栏配色亦随皮肤变化。
注意：编码设置对新建立的连接生效，已连接的会话不随设置变化。

9. config.json 便携说明

  • 会话与设置统一存放在 exe 同目录的 config.json；旧文件自动迁移，无需手动处理。
  • 密钥存放在同目录 keys/ 下。
  • 迁移/备份：把 exe 所在文件夹整体拷贝即可带走全部配置、会话与密钥。
  • 安全提示：config.json 中的会话密码为明文保存，请在可信环境中使用。

10. 断线重连

  • 会话被服务器 exit 或因网络中断后，标签不会关闭。
  • 在终端窗口中按回车即发起自动重连；重连失败可继续按回车重试。
  • 连接超时上限 30 秒，状态栏实时显示剩余秒数，失败时显示错误首行并给出排查建议。

11. 常见故障排查

现象排查建议
SmartScreen 提示已保护你的电脑未签名的正常提示，点「更多信息」→「仍要运行」；请先校验 sha256
中文显示乱码设置中心把编码改为 GBK 或 GB18030（与服务器编码一致），对新建连接生效
Cannot parse privateKey: Unsupported key format升级到 v2.3.2+；旧版生成的 PKCS#8 私钥会被自动转换，无需重新生成
认证失败按提示重新输入密码；若勾选过「保存会话」，保存的密码会在下次连接时覆盖输入
连接超时检查主机地址、端口、防火墙与服务器 sshd 状态；超时上限 30 秒
提示文件被占用v1.4.1 起已有单实例锁；若旧版本出现，检查任务管理器残留 EasySSH 进程
密码忘了/想改保存的密码编辑或删除会话记录后重新连接并勾选保存

更多问题请查阅 FAQ 页面；调试日志位于 %TEMP%\easyssh-debug.log。

开发指南

本文面向希望参与 EasySSH 开发的贡献者。完整内容见仓库文档源 docs-src/develop.md 与 CONTRIBUTING.md。

技术栈

全部基于开源组件构建：Electron ^33（桌面应用框架，Windows x64）、@xterm/xterm ^5.5 + addon-fit ^0.10（终端渲染与自适应）、ssh2 ^1.16（SSH/SFTP 协议实现）、iconv-lite ^0.7（编码转换）。构建工具：electron-builder ^25（portable 单文件 exe）、@electron/packager ^18（备用文件夹版）。

目录结构

EasySSH/
  main.js          # Electron 主进程：窗口管理、SSH/SFTP 连接、config.json 读写、单实例锁
  preload.js       # 预加载脚本：向渲染进程安全暴露 IPC 接口
  renderer.js      # 渲染进程：界面逻辑、xterm 终端、标签页、设置中心、SFTP 面板
  index.html       # 应用页面结构
  style.css        # 应用样式（含 5 款皮肤配色，自绘标题栏）
  assets/          # 应用内静态资源（xterm 库由 assets/ 加载，保证 asar 打包后可用）
  package.json     # 依赖与构建配置
  release/         # electron-builder 输出：EasySSH-<version>.exe
  dist/            # electron-packager 输出：文件夹版

运行时数据（随 exe 目录携带）：config.json（会话与设置）、keys/（密钥）。

本地开发

环境要求：Node.js ≥ 18，Windows（产物为 Windows 绿色版）。

npm install
npm start            # 本机调试运行
  • 界面报错会以红字显示在应用内（v1.5.1 起全局脚本错误显示）；
  • SSH 连接问题可查看调试日志 %TEMP%\easyssh-debug.log；
  • 修改主进程代码后需重启 npm start。

打包与发布

npm run build:exe    # electron-builder --win portable，输出 release/EasySSH-<version>.exe
npm run package:win  # 备用：electron-packager 文件夹版输出到 dist/

发布新版本务必：① 更新 package.json 的 version；② 在 README「版本更新历史记录」新增 ### v<版本号> (<日期>) 条目（README 为权威源）；③ 产物命名 EasySSH-<version>.exe 与 EasySSH-<version>-win32-x64-portable.zip。详见 贡献指南。

参与贡献

阅读 CONTRIBUTING；遵守行为准则；安全漏洞请勿公开提交，走安全策略渠道（security@easyssh.cn）。

网站自动同步机制

官网与仓库开发产物自动同步：同步脚本 tools/sync.js（零依赖 Node ≥18，幂等）每 5 分钟定时运行——解析 README 提取简介/功能/历史条目；扫描 release/ 与 dist/ 产物并读流计算 sha256；拷贝产物到站点 downloads/ 并生成 SHA256SUMS；重新生成 site-data.json（站点唯一数据源）。因此开发者只要规范地更新 README 历史并按命名约定产出文件，官网即自动展示新版本与下载。