# SSH工具箱

**Repository Path**: quxian/sshtool

## Basic Information

- **Project Name**: SSH工具箱
- **Description**: 一个不用装 Python 的 SSH 管理小工具：主机登记、密钥管理、隧道转发、环境体检，一个 exe 全搞定。
- **Primary Language**: Python
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-09
- **Last Updated**: 2026-10-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SSH 工具箱

一个**本地运行**的 SSH 主机与隧道管理器。把「登记主机 → 免密接入 → 建隧道」这条链路，从一连串命令行拼装变成点几下。

无服务端、无账号体系、不联网上报 —— 它在你自己电脑上跑一个小小的本地服务，界面用浏览器打开，所有数据留在本机。

> **使用前提**：你需要对目标服务器拥有合法的管理权限。本工具是为管理**你自己拥有或已获授权**的服务器而设计的。

---

## 它解决什么问题

用命令行管几台服务器，日常最烦的是这几件事：

| 场景 | 传统做法 | 本工具 |
|---|---|---|
| 新买一台机器，配免密登录 | 敲 `ssh-copy-id`、手写 `~/.ssh/config` 的 Host 段、对齐缩进 | 填 IP + 密码，一步推公钥并写好别名 |
| 有 5 台机器，钥匙分不清谁是谁 | 挨个 `ssh -i` 试，或翻 config | 列出所有密钥，标出「在用 / 未使用 / 缺私钥」和各自归属 |
| 开一条隧道 | 拼 `ssh -L 8080:127.0.0.1:80 -N -f user@host`，关的时候找 PID | 表单填四项，后台常驻，一键停 |
| 想撤销某台机器对本机的信任 | 登上去手改 `authorized_keys`，改错就锁死自己 | 精确匹配公钥主体后按行删，带干跑预览 |
| 换了台电脑，环境缺东西 | 报错了才知道缺什么 | 启动即体检，缺什么、怎么装，直接给命令 |

---

## 功能

**主机管理**
- 登记主机（别名 / 地址 / 端口 / 用户 / 私钥），可选同步写入 `~/.ssh/config`
- 别名冲突检测：别名已指向**另一台机器**时会拦下来，避免悄悄改写你手写的全局配置
- 密码冷启动接入：用一次性密码连接 → 推公钥进 `authorized_keys` → 用密钥回连验证 → 写好别名。**密码不落盘**
- 撤销授权：从目标机 `authorized_keys` 中精确移除指定公钥，支持先预览再执行

**密钥管理**
- 扫描本机 `~/.ssh`，识别五种状态：在用 / 默认备用 / 外部用途 / 未使用 / 缺私钥
- 生成新密钥对（默认 ed25519）
- 删除密钥：未使用、缺私钥可直接删；默认备用、外部用途需显式确认；**「在用」的钥匙不提供删除**——它会直接弄坏在跑的机器，正确做法是先解绑再删
- 「检测实际部署」：连上已登记主机读回 `authorized_keys`，告诉你每把钥匙**实际**在哪几台机器上（本机的 config 只是"我以为"）

**隧道管理**
- 支持 `-L` 本地转发、`-R` 远程转发、`-D` 动态 SOCKS
- 后台常驻，转发表格化展示，随时启停

**环境体检**
- 启动自动检查：`ssh` 客户端、`ssh-keygen`、Python 版本、`~/.ssh` 可写性、密钥对、paramiko
- 缺什么直接给安装命令（按操作系统区分），可一键复制

---

## 快速开始

### 方式一：用打包好的绿色版（推荐给最终用户）

1. 下载 `sshtool-win64.zip` 并解压到任意目录
2. 双击 `sshtool.exe`
3. 浏览器会自动打开 `http://127.0.0.1:7788`

**不需要安装 Python，也不需要单独安装 OpenSSH** —— 依赖已全部内置在包里。

### 方式二：从源码运行

```bash
# 需要 Python 3.10 或更高
pip install paramiko          # 可选，仅「密码接入」功能需要
python run.py                 # 或双击 启动.bat
```

关闭：`python run.py --stop`，或双击 `停止.bat`。

---

## 安全与隐私

这个工具要接触你的服务器凭据，所以把边界写清楚：

- **没有服务端。** HTTP 服务只监听 `127.0.0.1`，不对局域网或公网开放。
- **没有账号体系，不联网上报。** 没有埋点、没有遥测、没有"检查更新"。
- **密码只用一次，不写盘。** 冷启动接入时的密码仅用于当次连接，用完即丢，不进入任何配置文件。
- **私钥不出本机。** 工具只读取 `~/.ssh` 下的密钥文件用于本机的 `ssh` 调用；私钥内容不会被读取、复制或上传。
- **删除密钥默认进隔离区。** 删掉的密钥文件移动到 `~/.sshtool/key-trash/` 而非直接抹除，除非你明确选择"彻底删除"。

数据存储位置：

| 路径 | 内容 |
|---|---|
| `~/.sshtool/hosts.json` | 主机库（地址、用户、私钥**路径**） |
| `~/.sshtool/key-trash/` | 删除密钥时的隔离区 |
| `~/.ssh/config` | 仅在勾选"同步"时写入 |

---

## 自己打包一个绿色版

```bash
pip install pyinstaller
python build.py
```

产物：

- `dist/sshtool/` —— 可直接运行的目录（含 Python 运行时）
- `dist/sshtool-win64.zip` —— 发给别人的压缩包

打包脚本会自动处理这些事：

- 收集 paramiko / bcrypt / nacl / cryptography 的全部子模块
- 从系统 `System32\OpenSSH` 补齐 `ssh.exe` / `ssh-keygen.exe` / `libcrypto.dll` 到 `_internal/bin/openssh/`
- 跑一次自检 + 冒烟测试（真的启动一次服务、真的跑一次 `ssh -V`）
- 打成 zip

**关于随包的 OpenSSH**：工具优先使用包内那份，但判断方式是**真的执行一次 `ssh -V`**，而不是看文件在不在。如果包内的跑不起来（解压不全、被杀软隔离），会自动回退到系统自带的 ssh，并在体检里给出提示。

不想随包分发二进制？删掉 `vendor/openssh/` 再打包即可，工具会自动退回到"依赖系统 ssh"的模式。

---

## 项目结构

```
ssh-tool/
├── run.py           启动入口（环境预检 → 拉起服务 → 打开浏览器）
├── stop.py          停止入口（通过退出接口优雅关闭）
├── server.py        HTTP 路由层（Python 标准库 http.server，无框架）
├── sshkit.py        SSH 底层：密钥、config 解析、连接、公钥部署
├── hosts.py         主机库（~/.sshtool/hosts.json）
├── tunnels.py       隧道进程管理
├── purge.py         撤销远端授权
├── checkup.py       环境体检（唯一事实源，终端与接口共用）
├── paths.py         路径解析（兼容源码运行与 PyInstaller 冻结）
├── build.py         打包脚本
├── ssh-tool.spec    PyInstaller 配置
├── web/             前端（原生 JS，无构建步骤）
└── vendor/openssh/  随包分发的 OpenSSH 客户端
```

技术选型上刻意保守：**后端只用 Python 标准库**（唯一可选依赖 paramiko），**前端不用任何框架和构建工具**。目的是让这个工具在任何一台机器上 clone 下来就能跑，也方便想审计它的人一眼看完。

---

## 常见问题

**Q：启动后浏览器没自动打开？**
手动访问 `http://127.0.0.1:7788`。如果端口被占用，服务会自动往后找（7788–7827），控制台会打印实际端口。

**Q：提示找不到 ssh？**
Windows 10 1803+ / Windows 11 一般自带。没装的话，用管理员 PowerShell 执行：
```powershell
Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0
```
装了 OpenSSH 服务端不等于装了客户端——本工具只需要**客户端**。绿色包里已内置，通常不会有这个问题。

**Q：为什么删不掉某个密钥？**
状态是「在用」的钥匙不提供删除。它正在被某台登记主机使用，删掉会立刻断掉那台机器的免密登录。正确顺序是：先在主机页解除绑定（或从 `~/.ssh/config` 删掉别名），它会变成「未使用」，那时再删。

**Q：命令行敲 ssh 和工具里用的是同一个吗？**
不一定。如果 PATH 上还有 Git 自带的 MSYS 版 ssh，命令行会先命中它。工具**刻意优先使用系统版**，行为更可预测。体检里的「ssh 版本唯一」会告诉你这件事。

---

## 许可证

本项目采用 **GNU General Public License v3.0** 许可，全文见 [LICENSE](LICENSE)。

```
Copyright (C) 2026 曲线天涯
```

这意味着你可以自由地使用、修改和分发本软件；但**如果你分发修改后的版本，必须同样以 GPL-3.0 开源**。这能防止有人拿走源码做一个闭源版本去卖。

## 作者

- 曲线天涯
- dongjietao@126.com

---

## 免责声明

本工具通过调用系统 `ssh` 命令操作 SSH 连接与密钥，属于对标准工具的封装。使用者应确保：

1. 你对自己操作的服务器拥有合法的管理权限，或已获得明确授权；
2. 你对因使用本工具产生的任何配置变更、连接中断、密钥操作后果负责。

作者不对因使用本工具造成的任何直接或间接损失承担责任。