# QN-SSH **Repository Path**: YuYao-Gith/QN-SSH ## Basic Information - **Project Name**: QN-SSH - **Description**: 一个使用Go编写的SSH软件，其SFTP等文件传输功能使用Java编写，进程间采用HTTP/管道方式沟通 - **Primary Language**: Go - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-20 - **Last Updated**: 2026-08-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # QN-SSH — 浏览器 / 终端 SSH 连接器（Go × Java 跨语言融合版） > **许可证**：QN-SSH 项目整体（含内嵌的 `qftp/` 融合组件）以 **木兰宽松许可证第2版 > （MuLanPSL-2.0）** 开源（见 `LICENSE`）。`qftp/` 源自作者自有项目 QN-FTP > （尚未公开发布，版权人已就其授权本仓库使用）。 在本地用 **Go + Web + Java(QN-FTP)** 实现的 SSH 连接器，提供 **浏览器 GUI 版** 与 **终端 CLI 版** 两个形态：浏览器中像普通终端一样使用 SSH——支持全屏交互程序 （vim / top / htop）、终端自适应、中键粘贴、断线自动重连，整合 **SFTP 文件管理** （由内嵌的 QN-FTP Java 客户端承载）、**SSH 本地端口转发**，并新增 **FinalShell 式系统负载监控** 与 **账户加密保存**（CLI / Web 共享）。 ## 架构 ``` ┌──────────────┐ WebSocket ┌──────────────────────┐ SSH/PTY ┌──────────┐ │ 浏览器 │ ───────────▶ │ Go 后端 (qn-ssh) │ ──────────▶ │ 远程主机 │ │ xterm.js │ ◀─────────── │ 终端桥 + known_hosts │ ◀────────── │ bash │ │ 多标签/文件 │ HTTP │ + 隧道管理 │ └──────────┘ │ 面板/隧道面板 │ ──/ws────── └──────────┬───────────┘ │ │ HTTP ┌──────────▼───────────┐ │ │ ──/sftp/*──▶ │ Java sidecar(子进程) │ ── SFTP ──▶ 同一远程主机 └──────────────┘ 反向代理 │ QN-FTP MINA SSHD 客户端│ └──────────────────────┘ ``` - **Go 后端**：`golang.org/x/crypto/ssh` 建立 SSH 会话并请求 `xterm-256color` PTY； WebSocket（`github.com/coder/websocket`）双向桥接，30 秒 keepalive 保活 - **主机密钥校验**：连接前校验 `~/.ssh/known_hosts`；首次连接弹出指纹确认，确认后写入， 密钥变更会明确报错（不再无脑信任） - **Java sidecar**：把内嵌的 QN-FTP 项目（`qftp/`）编译出 SFTP HTTP 服务进程， Go 通过 `/sftp/*` 反向代理；首次启动自动 `javac` 编译，无 Java 环境时可用 `-no-java` 禁用 - **端口转发**：`/tunnel` API 建立本地端口转发（独立 SSH 连接，127.0.0.1 监听） - **系统监控**：单条 POSIX shell（`sh + awk + /proc`）经 SSH 执行，两次采样（间隔 1s） 计算 CPU 使用率与网络速率，一次返回 CPU/内存/Swap/磁盘/负载/进程等快照； CLI 渲染终端面板，Web 渲染进度条 + 趋势图（最近 60 点） - **账户库**：`~/.qn-ssh/accounts.json`，密码/私钥/口令 AES-256-GCM 加密 （密钥 `~/.qn-ssh/key` 随机生成，0600）；CLI 与 Web 共享同一库 ## 环境要求 - Go ≥ 1.22（开发时使用 1.26） - JDK 21+（`javac`/`java`，SFTP 文件管理需要；终端功能不依赖） - 现代浏览器（Chrome / Edge / Firefox / Safari） ## 构建与运行 ```bash # Web 版 go build -o qn-ssh . ./qn-ssh # 默认监听 127.0.0.1:8080 ./qn-ssh -addr 127.0.0.1:9000 # 自定义端口 ./qn-ssh -no-java # 禁用 SFTP（无 Java 环境时） # CLI 版 go build -o qn-ssh-cli ./cmd/qn-ssh-cli ./qn-ssh-cli --help ``` 启动后浏览器访问 **http://127.0.0.1:8080**。 ## CLI 用法 ```bash # 交互式 SSH 终端（raw 模式，支持 vim/top，窗口尺寸自动同步） qn-ssh-cli ssh 10.0.0.5 -u root -password xxx # 实时负载监控面板（ANSI 重绘，Ctrl+C 退出） qn-ssh-cli monitor 10.0.0.5 -u root -interval 2 # 本地端口转发（等价 ssh -L，可多条） qn-ssh-cli tunnel 10.0.0.5 -u root -L 3306:127.0.0.1:3306 -L 8080:10.0.1.2:80 # 账户管理（加密存储，与 Web 版共享） qn-ssh-cli account add -name prod -host 10.0.0.5 -u root -password xxx qn-ssh-cli account list qn-ssh-cli account del prod qn-ssh-cli account update prod -password newpw ``` 通用连接选项：`-a <账户ID或名称>` 复用已存账户（未显式给的参数自动从账户读取）、 `-hostkey SHA256:...` 预信任指纹（跳过交互确认）、`-timeout <秒>`。 参数可写在主机前后任意位置（如 `qn-ssh-cli monitor 10.0.0.5 -a prod -interval 3`）。 ## 使用 1. 填写主机地址、端口（默认 22）、用户名 2. 认证方式二选一：**密码** 或 **私钥**（PEM 内容/文件路径，可选口令） 3. 点击「连接」进入终端界面： - 回车执行命令，支持 vim / top 等全屏程序；窗口缩放自动适配（PTY 同步 resize） - 输入命令时底部弹出常用命令补全提示（点击自动补全） - 网络中断自动重连（最多 3 次），`exit` 或点「断开」结束会话 4. **多标签**：顶部 `+ 新连接` 可同时打开多个会话；连接配置保存在浏览器 localStorage 5. **📁 文件面板**（右侧）：连接后可「连接」SFTP，进行目录浏览、上传、下载、 新建目录、重命名、chmod、递归删除 6. **🔀 端口转发面板**：填写本地端口 → 远程目标，建立 SSH 隧道，列表可随时删除 7. 首次连接新主机时弹出 **主机密钥指纹确认**，核对无误后信任并写入 known_hosts 8. **📊 监控面板**：填写连接参数（默认取当前会话）点击「开始」， 实时显示 CPU / 内存 / Swap 进度条、CPU·内存·网络速率趋势图（最近 60 点）、 磁盘与网络接口明细；间隔 1~5 秒可调 9. **账户保存**：登录页「💾 保存当前表单」把账户（含密码/私钥）加密存入服务端 `~/.qn-ssh/accounts.json`；点击账户标签一键填入（自动读取明文凭据）， 右键标签删除——与 CLI `qn-ssh-cli account` 共享同一账户库 ## 测试 ```bash go test ./... ``` - `TestEndToEnd` / `TestBadPassword`：进程内 SSH 服务器 + 真实 PTY + bash 集成测试 - `TestJavaSftpBridge`：**跨语言链路冒烟** —— 测试 SSH 服务器(SFTP 子系统) ← Java sidecar(QN-FTP MINA SSHD) ← Go HTTP，覆盖连接/上传/下载/重命名/chmod/删除/断开 - `TestLocalTunnel`：端口转发隧道端到端验证（经隧道完成 SSH 握手与保活往返） - `TestCollectIntegration`：监控脚本在真实 PTY bash 环境执行并解析（真实 /proc） - `TestAccountsAPI` / `TestMonitorAPI*`：账户 CRUD（加密落盘验证）、监控接口 （含首次连接 409 + 指纹确认重试、错误密码 502） - `TestCLIMonitorEndToEnd`：CLI 完整链路（参数解析 → 采集 → 面板渲染） - known_hosts 校验/确认/密钥变更回归测试（含 ConfirmHost 后缓存失效） - 测试用临时 known_hosts 与账户目录，不污染 `~/.ssh/known_hosts`、`~/.qn-ssh` ## 目录结构 ``` ├── main.go # Web 版入口：HTTP 服务 + 优雅退出 ├── cmd/qn-ssh-cli/ # CLI 版：ssh / monitor / tunnel / account ├── internal/ │ ├── accounts/ # 账户加密存储（AES-256-GCM） │ ├── monitor/ # 系统负载采集（SSH 脚本 + 解析） │ ├── sshclient/ # SSH 拨号、PTY 会话、keepalive、known_hosts 校验、端口转发 │ ├── sftp/ # Java sidecar 生命周期管理 + /sftp 反向代理 │ ├── server/ # 静态服务 + WebSocket 桥接 + tunnel/accounts/monitor API │ └── testsshd/ # 测试用 SSH 服务器（真实 PTY + SFTP 子系统 + direct-tcpip） ├── qftp/ # QN-FTP 副本（Java 工程，仅取 SFTP 客户端能力） │ ├── lib/sshd/ # Apache MINA SSHD 依赖 │ └── src/com/qn/sftpapi/ # sidecar：SFTP HTTP 服务（本融合项目新增） ├── static/ │ ├── index.html # 多标签 + 终端 + 文件/隧道/监控面板 + 账户 │ └── app.js # WebSocket 客户端、xterm、SFTP、补全、监控图表 └── README.md ``` ## 安全说明 > 本项目定位为**本地个人工具**，默认仅监听 `127.0.0.1`，请勿将端口暴露到公网。 - **主机密钥校验**：使用 `~/.ssh/known_hosts` 校验；首次连接需确认指纹，密钥变更会告警 ✅（已修复 v1 的 `InsecureIgnoreHostKey` 问题） - **账户库**：密码/私钥/口令 AES-256-GCM 加密存储（密钥 `~/.qn-ssh/key` 0600）； 列表接口不返回明文，明文凭据仅经 `GET /api/accounts/{id}/plain` 回环获取 - **凭据传输**：连接参数（含密码）经 WebSocket / 本地回环 HTTP 明文传输，仅限本机场景； Sidecar 以随机令牌鉴权，仅监听 127.0.0.1 - 生产化建议：接入 TLS（wss）+ 登录鉴权、会话级密码输入而非表单提交、隧道监听默认仅回环 ## 许可证与第三方组件 - 本项目（含 `qftp/` 融合组件）：**木兰宽松许可证第2版（MuLanPSL-2.0）**，见根目录 `LICENSE`。 `qftp/` 源自作者自有项目 QN-FTP（未公开发布），版权人已授权本仓库以 MuLanPSL-2.0 使用与修改 - `qftp/lib/sshd/*.jar`：Apache MINA SSHD 系列（Apache-2.0） - Go 依赖：`golang.org/x/crypto`（BSD-3）、`github.com/coder/websocket`（MIT）