quick-ssh

v1.1.11

Published

2 months ago

🚀 Quick-SSH - 仿 Docker 命令行风格的 SSH 连接管理工具（原生二进制版本，无需 Node.js）

Downloads

106

0High
0Medium
0Low

cceli

ssh powershell wsl crt quick-ssh qssh connection-manager windows scoop winget apt pacman

Quick-SSH

💡 遇到问题？ 请查阅常见问题 (FAQ)，其中收录了密钥权限、终端恢复、编码错误等常见问题的解决方案。

功能特性 ✨

| 功能 | 说明 | |------|------| | 🔌 SSH 连接 | 一键连接已保存的 SSH 服务器 | | 🖥️ TUI 终端界面 | 可视化键盘操作界面，类 yazi 操作体验 | | ⌨️ Docker 风格 CLI | ps、add、rm 等子命令，上手即用 | | 🏓 Ping 检测 | 列表中实时显示各主机连通状态（在线/离线） | | 📤 拖拽上传 | 连接后可直接把本地文件或目录拖进终端，在新终端窗口中显示进度并上传到远端当前目录 | | 📦 原生二进制 | 预编译可执行文件，无需 Node.js 运行时，即下即用 | | 🎯 全平台包管理 | npm / yarn / Scoop / winget / apt / Pacman(AUR) 全支持 | | 🔄 导入/导出 | JSON 格式批量导入导出主机配置 | | ⏹ Tab 自动补全 | 子命令 + 已保存主机别名自动补全 | | 🌐 跨平台 | Windows / Linux / macOS 统一二进制，无需运行时依赖 |

跨平台支持

Quick-SSH 支持 Windows / Linux / macOS 三大主流操作系统。

架构概览

Quick-SSH 使用 pkg 将 Node.js 源码编译为 原生二进制可执行文件，直接运行，无需解释器。

                        快速开始:
                        ┌─────────────────┐
                        │  下载二进制文件    │
                        │  放入 PATH 目录   │
                        └────────┬────────┘
                                 │
                        ┌────────▼────────┐
                        │  qssh 命令       │
                        │  (原生二进制)      │
                        └────────┬────────┘
                                 │
                    ┌────────────┼────────────┐
                    ▼            ▼            ▼
               Windows       Linux        macOS
               qssh.exe    qssh          qssh
                    │            │            │
                    ▼            ▼            ▼
               ~/.ssh/config (跨平台统一数据存储)
                    │            │            │
                    ▼            ▼            ▼
                SSH / SFTP 连接管理

💡 不再需要 Node.js 运行时：二进制文件内嵌了 Node.js 运行时和应用代码，qssh 直接执行，启动更快、分发更简单。

💡 旧版兼容：如果您更偏好通过 npm 安装源码版本，仍可使用 npm install -g quick-ssh。

安装方式与配置注入

| 安装方式 | 平台 | 运行时 | 配置文件注入 | |----------|------|--------|-------------| | 二进制发布包 | Win/Linux/macOS | 原生可执行文件（内嵌 Node.js） | 自动将二进制路径添加到 PATH 环境变量 | | npm 全局安装 | Win/Linux/macOS | 需要 Node.js 运行时 | postinstall 自动将 dist/ 目录添加到 PATH | | Scoop / winget | Windows | 原生 qssh.exe | Scoop/winget 自动处理 PATH | | apt / Pacman | Linux | 原生 qssh | 安装到 /usr/bin/，自动在 PATH 中 |

二进制版本：通过 @yao-pkg/pkg 将 Node.js 源码 + 运行时编译为单文件可执行程序，启动速度更快，分发更简单。

核心模块

| 文件 | 作用 | |------|------| | scripts/build.js | 构建脚本 — 使用 pkg 将 Node.js 源码编译为原生二进制 | | src/unix/cli.js | 统一 CLI 入口 — 所有平台共用，编译为二进制后直接执行 | | src/lib/index.js | 安装/卸载钩子 — 将二进制路径添加到 PATH 环境变量 | | src/tui/data.js | 共享数据层 — 读写 ~/.ssh/config，路径归一化跨平台兼容 | | src/tui/network.js | getSSHExe() → ssh.exe (Windows) / ssh (Linux/macOS) | | src/tui/index.js | TUI 界面 — blessed 终端 UI，跨平台按键绑定 | | src/tui/modes.js | 模式常量/标签/提示 | | src/lib/session.js | SSH 会话代理（拖拽检测 + scp 上传） | | src/lib/upload_runner.js | 独立上传窗口脚本（scp 进度 + 结果汇总） |

安装前准备 ⚠️

确保已安装 SSH 客户端（Windows 10+ / Linux / macOS 通常自带）
确保 ~/.ssh/ 目录权限正确（Linux/macOS: chmod 700 ~/.ssh）
Windows 二进制版本无需 PowerShell 执行策略修改

安装

Quick-SSH 提供 原生二进制 和 npm 源码 两种安装方式。

🏆 方式一：直接下载二进制（推荐，无需 Node.js）

从 GitHub Releases 下载对应平台的二进制文件：

| 平台 | 文件名 | 操作 | |------|--------|------| | Windows | qssh-win-x64.exe | 放入 PATH 目录（如 C:\Windows\System32\）或任意位置后加到 PATH | | Linux | qssh-linux-x64 | chmod +x qssh-linux-x64 && sudo mv qssh-linux-x64 /usr/local/bin/qssh | | macOS | qssh-macos-x64 | chmod +x qssh-macos-x64 && sudo mv qssh-macos-x64 /usr/local/bin/qssh |

下载完成并放入 PATH 后，打开新终端即可使用 qssh 命令。

qssh  # 启动 TUI 界面

无需安装 Node.js、Python 或任何运行时。单个文件，即下即用。

📦 方式二：npm 全局安装（需要 Node.js）

npm install -g quick-ssh

安装后会自动将二进制所在目录添加到 PATH，重启终端即可使用。

npm 包中同时包含了源码和预编译二进制，postinstall 脚本自动执行 PATH 注册。

🧶 yarn

yarn global add quick-ssh

🪣 Scoop（Windows，原生二进制）

scoop bucket add extras
scoop install quick-ssh

Scoop 安装的是预编译的 qssh.exe，无需 Node.js。

📟 winget（Windows，原生二进制）

winget install CCE-Li.Quick-SSH

winget 安装的是预编译的 qssh.exe，自动处理 PATH。

🐧 apt（Debian / Ubuntu）

# 从 GitHub Releases 下载 .deb 包
wget https://github.com/CCE-Li/Quick-SSH/releases/latest/download/quick-ssh.deb

# 安装
sudo apt install ./quick-ssh.deb

# 注册到 Shell 配置文件
qssh init

或添加 APT 仓库（待支持）：

echo "deb https://apt.fury.io/quick-ssh/ /" | sudo tee /etc/apt/sources.list.d/quick-ssh.list
curl -fsSL https://apt.fury.io/quick-ssh/gpg.key | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/quick-ssh.gpg
sudo apt update
sudo apt install quick-ssh

🏔️ Pacman（Arch Linux / AUR）

# 方式一：通过 AUR helper（如 yay）
yay -S quick-ssh

# 方式二：手动构建
git clone https://aur.archlinux.org/quick-ssh.git
cd quick-ssh
makepkg -si

AUR 包会在安装后自动注册 qssh 到 Shell 配置文件。

快速入门

# 直接输入 qssh 进入 TUI 界面
qssh

# 查看帮助
qssh help

# 添加一个 SSH 连接（Linux/macOS）
qssh add my-server [email protected]:22 --key ~/.ssh/id_rsa

# 添加一个 SSH 连接（Windows）
qssh add my-server [email protected]:22 --key C:\Users\You\.ssh\id_rsa

# 一键连接
qssh my-server

# 连接后可直接把文件拖进终端
# Quick-SSH 会自动识别拖拽路径，并上传到远端当前目录

# 列出所有连接
qssh ps

# 删除连接
qssh rm my-server

TUI 常用键位：

Space 选择/取消当前连接，可用于批量操作
P 批量检测已选连接；未选择时检测当前筛选结果中的全部连接
d 删除当前连接；若已多选则批量删除

配置文件

Quick-SSH 使用 标准 OpenSSH 配置文件 (~/.ssh/config) 存储所有连接数据，Win/Linux/macOS 完全统一，不会在卸载时删除。

~/.ssh/config

你可以直接用文本编辑器编辑该文件，也可以使用 qssh 命令管理。以下是 Quick-SSH 管理的 Host 块示例：

Host my-server
    HostName 192.168.1.100
    User root
    Port 22
    IdentityFile ~/.ssh/id_rsa

除了 Quick-SSH 管理的 Host 块外，~/.ssh/config 中还可以包含全局选项、注释、以及其他 SSH 客户端（如原生 ssh 命令）使用的配置，Quick-SSH 会保留所有非自己管理的内容。

Quick-SSH 配置

拖拽上传的运行参数暂时从 ~/.qsshrc 读取。

示例：

UploadConcurrency=3

当前支持项：

UploadConcurrency
- 控制拖拽上传时新终端窗口内的并发上传数
- 默认值为 3
- 必须是大于 0 的整数

拖拽上传

当你通过 qssh <alias> 或 TUI 发起 SSH 会话后，Quick-SSH 会自动开启拖拽检测。

把本地文件或目录拖进当前终端
Quick-SSH 会拦截终端粘贴进来的本地路径
然后自动打开一个新的本地终端窗口，用 SFTP 上传到远端当前目录

当前行为说明：

默认目标目录是你当前 shell 所在的远端目录
目录会自动递归上传
新终端窗口中会以固定列表方式显示每个文件的进度条、剩余时间和总进度条
新终端窗口内会按 ~/.qsshrc 中的 UploadConcurrency 设置并发上传，默认 3
传输窗口在你按下 Enter 后会直接关闭
原 SSH 会话不会被上传任务占用，你可以继续操作
该功能依赖本机可用的 ssh，上传窗口内部使用 ssh2/SFTP

近期规划 🗓️

| 功能 | 说明 | |------|------| | 🔔 自动检测更新 | 启动时检查 npm 新版本并提示升级 | | 🔄 批量执行 | 选中多台主机，批量发送同一命令 | | 📋 一键保存 Log | 记录每次连接的时间戳与操作日志 | | 🪟 新窗口打开 | 连接服务器时自动打开新终端窗口 | | 🤖 AI 辅助指令 | 自然语言描述操作意图，AI 生成对应命令 | | 📦 全平台包覆盖 | 已实现 npm / yarn / Scoop / winget / apt / Pacman(AUR) | | 🏪 提交至官方仓库 | Scoop extras bucket、winget-pkgs、AUR、Gemfury APT 仓库 |

卸载

npm / yarn

npm uninstall -g quick-ssh
# 或
yarn global remove quick-ssh

卸载时：

✅ 自动清理 PATH: preuninstall 从 Shell 配置文件中移除二进制路径
✅ 保留 ~/.ssh/config 用户配置数据（不会在卸载时删除）

Scoop

scoop uninstall quick-ssh

winget

winget uninstall CCE-Li.Quick-SSH

apt

sudo apt remove quick-ssh

Pacman

sudo pacman -R quick-ssh

项目文件结构

quick-ssh/
├── src/                          # 源码目录
│   ├── unix/
│   │   └── cli.js              # 统一 CLI 入口（编译为二进制）
│   ├── lib/
│   │   ├── index.js            # npm 生命周期钩子（将二进制路径写入 PATH）
│   │   ├── session.js          # SSH 会话代理（拖拽检测 + scp 上传）
│   │   └── upload_runner.js    # 独立上传窗口脚本（scp 进度 + 结果汇总）
│   └── tui/
│       ├── index.js            # TUI 主入口（Blessed 界面 + 键位绑定）
│       ├── modes.js            # 模式常量/标签/提示
│       ├── data.js             # 数据层（配置读写，CLI 和 TUI 共用）
│       └── network.js          # 网络层（SSH 连接 + 在线检测）
├── scripts/
│   └── build.js                # 构建脚本（pkg 编译为原生二进制）
├── packaging/                   # 多包管理器配置文件
│   ├── scoop/
│   │   └── quick-ssh.json      # Scoop 清单（分发 .exe）
│   ├── winget/
│   │   └── CCE-Li.Quick-SSH.*.yaml  # winget 清单（分发 .exe）
│   ├── apt/
│   │   ├── DEBIAN/control      # Debian 包控制文件
│   │   └── Makefile            # .deb 构建脚本
│   └── pacman/
│       └── PKGBUILD            # Arch Linux 构建脚本
├── .github/
│   └── workflows/
│       └── release.yml         # CI/CD：构建二进制 → 发布 Release + npm
├── dist/                        # 编译产物（gitignored）
├── doc/                         # 文档
├── package.json                 # npm 包配置 + pkg 构建配置
├── README.md
├── LICENSE
└── .gitignore

如果 Quick-SSH 帮你节省了时间，欢迎请开发者喝杯咖啡 ☕

感谢每一位支持 Quick-SSH 的朋友 ❤️

License

MIT