# web-ssh
**Repository Path**: lan-shuai/web-ssh
## Basic Information
- **Project Name**: web-ssh
- **Description**: npm搭建的web ssh新平台
- **Primary Language**: Unknown
- **License**: WTFPL
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-15
- **Last Updated**: 2026-07-15
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
Web SSH
浏览器里的 SSH 终端 — 本机网关 · xterm.js · 远程文件 · 可换主题
快速开始 ·
特点 ·
能力 ·
主题 ·
架构 ·
安全
---
面向 **本机或局域网** 的浏览器 SSH 工具：把 WebSocket 网关、xterm.js 终端与远程文件浏览组织在一起，在浏览器完成登录、命令交互和常见文件操作，**无需外网 CDN**。
适合管理 Linux 主机、OpenWrt / BusyBox 路由器、内网设备调试，以及希望统一用浏览器操作远程 Shell 的个人 / 团队场景。
> 
---
## 核心特点
| | |
| :--- | :--- |
| **浏览器可用** | 页面 + Node 本地服务即可运行，终端基于 xterm.js |
| **本机转发架构** | 浏览器不直连 SSH，由本地 Node 经 `ssh2` 转发，降低协议与兼容负担 |
| **终端体验完整** | 密码登录、窗口自适应、清屏、断开、连接历史回填 |
| **远程文件面板** | 右侧可折叠；列目录、快捷路径跳转、文件下载 |
| **跟随终端目录** | 可开关；提示符路径识别 + `cd` 解析（兼容 BusyBox ash，不注入脚本） |
| **主题可替换** | 独立主题包，支持预览与热切换 |
| **离线友好** | `postinstall` 将 xterm 拷入 `public/vendor/`，启动不依赖 CDN |
---
## 能力概览
| 能力 | 说明 |
| :--- | :--- |
| SSH 终端 | 密码登录、resize、清屏、断开；WebSocket **二进制**传输降低开销 |
| 连接历史 | 主机 / 端口 / 用户名 / 密码保存在浏览器 `localStorage`（最多 20 条） |
| 远程文件 | SFTP 优先；无 SFTP 时自动回退为 shell 列目录与下载 |
| 跟随终端 | 「跟随终端」开关；识别 `user@host:/path#` 与输入的 `cd` |
| 主题系统 | `pine` · `dusk` · `ember` · `dawn` · `phosphor` · `arctic` |
| 复制粘贴 | 连按 3 次 `Ctrl` 后，使用 `Ctrl+C` / `Ctrl+V`（避开浏览器冲突快捷键） |
---
## 环境要求
- **Node.js** 18+（推荐 LTS）
- **系统** Windows / macOS / Linux
- **浏览器** 较新的 Chrome / Edge / Firefox 等
| 环境变量 | 说明 | 默认 |
| :--- | :--- | ---: |
| `PORT` | HTTP 服务端口 | `4000` |
---
## 快速开始
### 安装
```bash
git clone <你的仓库地址>
cd web-ssh
npm install
```
`npm install` 会执行 `postinstall`，将 xterm 与 fit 插件复制到 `public/vendor/`。
### 启动
```bash
npm start
```
浏览器打开 [`http://localhost:4000`](http://localhost:4000)
开发模式（文件变更后自动重启）：
```bash
npm run dev
```
### 使用步骤
1. 左侧填写主机、端口、用户名、密码，点击 **连接**
2. 中间区域显示远程 Shell
3. 顶部点击 **文件**，打开右侧远程文件面板
4. 需要时开启 **跟随终端**，让文件路径随 `cd` 变化
---
## 远程文件与跟随终端
远程文件面板默认在右侧，可随时折叠 / 展开。
- **有 SFTP** — 直接使用 SFTP 列目录与下载
- **无 SFTP**（常见于路由器）— 自动改用 shell 命令浏览与下载
- **快捷路径** — `/` · `tmp` · `etc` · `www` · `overlay` · `mnt` · `var` · `root`
- **跟随终端** — 开启后文件列表尽量跟随当前工作目录；关闭后可自由浏览
**BusyBox / OpenWrt 提示**
- 家目录经常为空，请优先从 `/`、`/tmp`、`/etc` 等路径查看
- 跟随能力依赖常见提示符（如 `root@host:/tmp#`）以及你输入的 `cd`，**不会**往终端注入钩子脚本
---
## 主题
主题包位于 `public/themes//`：
```text
public/themes/
├── index.json # 主题列表
├── pine/
│ ├── theme.json # 名称、预览色、终端配色
│ └── theme.css # 页面变量与视觉差异
├── dusk/
├── ember/
├── dawn/
├── phosphor/
└── arctic/
```
新增主题：创建目录 → 编写 `theme.json` / `theme.css` → 将主题 id 加入 `index.json`。
---
## 架构说明
```text
┌─────────────────────┐
│ 浏览器 (xterm.js) │
└──────────┬──────────┘
│ WebSocket /ssh
┌──────────▼──────────┐
│ Node.js │
│ Express + ws + ssh2 │
└──────────┬──────────┘
│ SSH / SFTP（或 shell 兜底）
┌──────────▼──────────┐
│ 远程主机 │
└─────────────────────┘
```
**协议约定**
| 类型 | 约定 |
| :--- | :--- |
| 终端原始数据 | 二进制帧（首字节 `0` + payload） |
| 控制消息 | JSON（连接、缩放、列目录、cwd 同步等） |
| 文件下载 | `GET /sftp/download?sid=...&path=...` |
---
## 仓库结构
```text
web-ssh/
├── server.js # HTTP + WebSocket + SSH/SFTP 桥接
├── package.json # 依赖与脚本
├── scripts/
│ └── copy-vendor.js # 安装后拷贝 xterm → 本地 vendor
├── public/
│ ├── index.html # 页面结构
│ ├── app.js # 终端 · 历史 · 主题 · 文件面板
│ ├── style.css # 公共布局
│ ├── favicon.svg
│ ├── vendor/ # 本地 xterm（postinstall 生成）
│ └── themes/ # 主题包
├── LICENSE
└── README.md
```
| 提交 | 勿提交 |
| :--- | :--- |
| `server.js` · `public/` · `package.json` · `package-lock.json` · `scripts/` · `.gitignore` · `README.md` · `LICENSE` | `node_modules/` · 本地密钥 · `.env` |
---
## 发布标签
```bash
git push -u origin master
git push origin v1.1.0
```
---
## 安全说明
> **请勿将本服务直接暴露到公网。** 仅建议本机或受信局域网使用。
- 连接密码只保存在当前浏览器本地历史，服务端不落盘
- 文件下载依赖当前 SSH 会话令牌，断开连接后失效
---
## 许可证
[WTFPL](./LICENSE) — Do What The Fuck You Want To Public License.