# webiterm

**Repository Path**: aopmin/webiterm

## Basic Information

- **Project Name**: webiterm
- **Description**: Webiterm 是一款web终端管理工具，支持本地 Shell、SSH 远程连接和 SFTP/FTP 文件浏览管理。内置 15+ 精美主题、多种背景特效、命令自动补全等特性，同时提供 Electron 桌面应用打包，跨平台运行。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-06
- **Last Updated**: 2026-06-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
  <img src="https://raw.githubusercontent.com/twitter/twemoji/master/assets/svg/1f5a5.svg" width="80" height="80" alt="Webiterm" />
</p>

<h1 align="center">Webiterm</h1>

<p align="center">
  <strong>🖥️ 现代化网页终端 & 远程文件管理 &nbsp;|&nbsp; A Modern Web-Based Terminal & Remote File Manager</strong>
</p>

<p align="center">
  <a href="#-功能特性"><strong>功能</strong></a> ·
  <a href="#-快速开始">快速开始</a> ·
  <a href="#-快捷键">快捷键</a> ·
  <a href="#-打包">打包</a> ·
  <a href="#-项目结构">结构</a> ·
  <a href="#-技术栈">技术栈</a>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-brightgreen" alt="Platform" />
  <img src="https://img.shields.io/badge/node-%3E%3D18.0-blue" alt="Node" />
  <img src="https://img.shields.io/badge/electron-%5E29.0-blue" alt="Electron" />
  <img src="https://img.shields.io/badge/license-MIT-green" alt="License" />
</p>

---

## 📖 简介

**Webiterm**  是一款web终端管理工具，支持本地 Shell、SSH 远程连接和 SFTP/FTP 文件浏览管理。内置 15+ 精美主题、多种背景特效、命令自动补全、多标签拖拽排序等特性，同时提供 Electron 桌面应用打包，跨平台运行。

![img.png](./doc/img/img.png)
---

## ✨ 功能特性

### 🖥️ 终端核心
- **本地终端** — node-pty 本地 Shell 访问
- **SSH 远程连接** — 密码/私钥认证，支持会话恢复
- **多标签页** — 创建、切换、拖拽排序、双击改名
- **WebSocket 通信** — 低延迟双向实时通信
- **WebGL 渲染** — GPU 加速终端渲染

### 📁 远程文件管理
- **SFTP 文件浏览器** — SSH 连接后一键进入，树形目录结构
- **FTP 支持** — 同样支持传统 FTP 协议
- **本地上传** — 从本地电脑选文件直接上传到远程目录
- **远程下载** — 流式分块下载 + 实时进度条
- **文件操作** — 新建文件夹、重命名、删除
- **免登连接** — SSH 连接成功后点 FTP 按钮自动复用凭据

### 🎨 主题定制
- **15+ 预设主题** — 一键切换（Dracula、Nord、Monokai、Tokyo Night 等）
- **纯色背景** — 自定义颜色背景
- **渐变背景** — 双色/三色渐变，自定义角度
- **图片/视频背景** — 支持 URL 或本地文件选择
- **粒子特效** — 动态粒子连线动画
- **Unsplash 集成** — 关键词搜索随机高清壁纸
- **终端透明度** — 可调节

### ⚡ 效率工具
- **智能命令补全** — Tab 键触发，历史记录感知
- **终端内搜索** — 全文搜索 (Ctrl+Shift+F)
- **会话持久化** — 自动保存/恢复标签页和连接信息
- **窗口状态记忆** — 记住窗口位置和大小

---

## ⌨️ 快捷键

| 快捷键 | 功能 |
|---|---|
| `Ctrl+Shift+N` | 新建本地终端 |
| `Ctrl+Shift+H` | SSH 远程连接 |
| `Ctrl+Shift+E` | 远程文件管理 (SFTP/FTP) |
| `Ctrl+Shift+T` | 主题与背景设置 |
| `Ctrl+Shift+F` | 终端内搜索 |
| `Ctrl+Shift+,` | 终端设置 |
| `Ctrl+Shift+W` | 关闭当前标签 |
| `Ctrl+Tab` | 下一标签 |
| `Ctrl+Shift+Tab` | 上一标签 |
| `Ctrl+1~9` | 切换到第 N 个标签 |
| `Ctrl+C/V` | 复制/粘贴 |

> macOS 用 `⌘ Command` 替代 `Ctrl`

---

## 🚀 快速开始

### 环境要求
- **Node.js** ≥ 18.0
- **npm** ≥ 9.0
- （可选）**Electron** ≥ 29.0（桌面打包）

### 安装运行

```bash
# 1. 安装依赖
npm install

# 2. 启动服务（浏览器访问）
npm start
# → 打开 http://localhost:3000

# 3. 或启动 Electron 桌面应用
npm run electron
```

### 使用 SFTP 文件管理

1. 先 SSH 连接到服务器（`Ctrl+Shift+H`）
2. 点击工具栏 **FTP** 按钮（或 `Ctrl+Shift+E`）
3. 自动复用 SSH 凭据连接 SFTP
4. 树形目录浏览、点击 ▶ 展开、双击文件下载
5. 点击 **上传** 选择本地文件上传到当前远程目录

---

## 📦 打包

```bash
npm run pack:mac      # macOS (dmg + zip)
npm run pack:win      # Windows (nsis + portable)
npm run pack:linux    # Linux (AppImage + deb)
npm run pack:all      # 全平台
```

### ⚠️ macOS 用户安装须知

由于应用**未经过 Apple 公证**（需要付费的 Apple Developer 账号），macOS Gatekeeper 会阻止打开，提示「已损坏，无法打开」。请执行以下命令绕过验证：

```bash
# 1. 将 Webiterm.app 拖入 /Applications 文件夹
# 2. 在终端执行以下命令（只需执行一次）
xattr -cr /Applications/Webiterm.app

# 3. 双击打开即可正常使用
```

> 💡 这条命令清除了 macOS 对应用的隔离标记，不会影响应用功能，也不会影响系统安全设置。执行一次即可永久生效。

---

## 📁 项目结构

```
webiterm/
├── server.js                  # Express + WebSocket 后端
├── electron-main.js           # Electron 主进程
├── electron-preload.js        # Electron 预加载脚本
├── package.json
├── public/
│   ├── index.html             # 主页面
│   ├── css/
│   │   └── style.css          # 全局样式
│   └── js/
│       ├── main.js            # 主入口：初始化、快捷键、事件绑定
│       ├── terminal.js        # 终端管理器：多标签、xterm 封装
│       ├── theme.js           # 主题管理器：15+ 主题 + 背景特效
│       ├── ftp.js             # 远程文件管理器：SFTP/FTP + 树形结构
│       ├── connection.js      # WebSocket 连接管理
│       └── autocomplete.js    # 命令自动补全引擎
└── dist-electron/             # 打包产物
```

---

## 🏗️ 技术栈

| 层级 | 技术 |
|---|---|
| **Terminal Engine** | xterm.js 5.3 |
| **Terminal Backend** | node-pty (local), ssh2 (remote + SFTP) |
| **FTP Client** | basic-ftp |
| **Communication** | WebSocket (ws) |
| **Web Server** | Express 4 |
| **Desktop Shell** | Electron 29 |
| **Build & Package** | electron-builder 24 |
| **Font Icons** | Font Awesome 6 |