# x-shell

**Repository Path**: lanjf2000/x-shell

## Basic Information

- **Project Name**: x-shell
- **Description**: 因为公司不允许使用未授权的开发工具，包括xshell都被禁用了，就用AI仿造xshell，生成了一套平时用于远程运维的工具。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-16
- **Last Updated**: 2026-04-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# X-Shell

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)

> 一个现代化的 Web 端 SSH/SFTP 客户端，支持多标签页、文件管理、会话管理等功能。
> 
> 🆕 **新增**: 支持自定义数据存储路径，随时迁移配置到任意目录！
> 🆕 **新增**: 支持自定义后端服务端口，解决端口冲突问题！

![X-Shell Screenshot](./docs/screenshot.png)

## ✨ 功能特性

- **🖥️ SSH 终端**: 基于 WebSocket 的实时 SSH 连接，支持多标签页
- **📁 SFTP 文件管理**: 可视化的文件浏览器，支持上传/下载/删除/重命名/新建文件夹
- **💾 会话管理**: 树形结构的连接管理，支持无限层级文件夹分类
- **🔐 多种认证方式**: 支持密码认证和私钥认证（RSA/ED25519）
- **📤 文件传输**: 支持拖拽上传、批量下载、实时进度显示、传输队列管理
- **📝 配置导入导出**: 支持 Xshell、FinalShell、JSON 格式的会话导入
- **📋 终端复制粘贴**: 支持 `Ctrl+Shift+C/V/A` 快捷键和右键菜单
- **🎨 深色主题**: 舒适的深色界面，适合长时间使用
- **📱 响应式布局**: 支持文件管理器在右侧或底部切换
- **🔄 数据迁移**: 支持随时修改数据存储路径，自动迁移配置
- **🔌 端口配置**: 支持自定义后端服务端口（1025-65535），自动处理端口冲突
- **💻 桌面版**: 基于 Electron 的独立应用，双击即用

## 🚀 快速开始

### 环境要求

- Node.js >= 18.0.0
- npm >= 9.0.0

### 安装运行

```bash
# 克隆项目
git clone https://github.com/yourusername/x-shell.git
cd x-shell

# 安装依赖
npm run install:all

# 开发模式运行
npm run dev

# 生产构建
npm run build
npm start
```

访问 http://localhost:3001 即可使用

## 📁 项目结构

```
x-shell/
├── client/                 # Vue3 前端
│   ├── src/
│   │   ├── components/    # 组件
│   │   ├── views/         # 页面
│   │   ├── api/           # API 接口
│   │   └── stores/        # Pinia 状态管理
│   └── package.json
├── server/                # Node.js 后端
│   ├── src/
│   │   ├── routes/        # API 路由
│   │   ├── services/      # 业务逻辑
│   │   └── index.ts       # 入口
│   └── package.json
├── desktop/               # Electron 桌面版
│   ├── main/              # 主进程
│   ├── preload/           # 预加载脚本
│   └── build/             # 打包配置
├── docs/                  # 文档
├── data/                  # 用户数据（Git 忽略）
├── uploads/               # 临时上传目录（Git 忽略）
└── package.json
```

## 🔧 配置说明

### 数据存储路径配置

**Web 版**:
- 通过 **设置 → 数据存储** 修改存储路径
- 支持验证路径有效性（绝对路径 + 写入权限）
- 可选择是否迁移现有数据
- 修改后自动刷新生效

**桌面版**:
- 默认使用系统用户数据目录
- Windows: `%APPDATA%/X-Shell/data/`
- Linux: `~/.config/X-Shell/data/`
- macOS: `~/Library/Application Support/X-Shell/data/`

### 后端服务端口配置（桌面版）

**功能说明**:
- 支持自定义后端服务起始端口（默认 30000，范围 1025-65535）
- 端口被占用时自动尝试下一个可用端口
- 保存配置后需重启应用生效
- 支持健康检查后自动重启

**配置路径**: 设置 → 常规 → 后端服务端口

**配置流程**:
1. 修改"服务起始端口号"（如 30001）
2. 点击"保存"（显示"已保存，重启后生效"提示）
3. 点击"重启后端服务"（应用自动重启）
4. 重启后新端口生效

**注意事项**:
- Web 版不支持此功能（由部署环境决定端口）
- 修改端口后所有现有连接将断开
- 建议选择 30000 以上的端口避免冲突

### 用户数据文件

- `connections.json` - SSH 连接配置（支持嵌套文件夹结构）
- `config.json` - 应用设置（主题、布局、数据路径、服务端口等）

**安全提示**: 数据目录已被 `.gitignore` 排除，SSH 密码和密钥不会泄露到 Git。

### 环境变量

创建 `server/.env` 文件：

```env
PORT=3001                    # 服务端口（Web 版）
DATA_DIR=./data             # 数据存储路径（可选，默认可通过 UI 配置）
CLIENT_URL=http://localhost:5173  # 开发模式前端地址
```

## 🛠️ 技术栈

### 前端
- **Vue 3** + **TypeScript** - 渐进式 JavaScript 框架
- **Vite** - 构建工具
- **Pinia** - 状态管理
- **xterm.js** - 终端模拟器
- **SCSS** - 样式预处理器

### 后端
- **Node.js** + **Express** - Web 框架
- **ssh2** - SSH 连接库
- **ssh2-sftp-client** - SFTP 客户端
- **multer** - 文件上传处理
- **WebSocket** - 实时通信

### 桌面版
- **Electron** - 跨平台桌面应用框架
- **electron-builder** - 打包工具

## 🖥️ 桌面版使用

X-Shell 桌面版基于 Electron 构建，提供独立的跨平台应用体验。

### 桌面版特性

- **零配置启动**: 内嵌服务器，双击即用，无需手动启动后端
- **端口自定义**: 支持自定义后端服务端口，自动处理冲突
- **系统集成**: 支持系统托盘、原生右键菜单、全局快捷键
- **数据隔离**: 独立的数据存储路径，与 Web 版互不干扰
- **自动更新**: 支持自动检测和下载新版本

### 桌面版快捷键

| 快捷键 | 功能 |
|--------|------|
| `Ctrl+Shift+C` | 终端复制 |
| `Ctrl+Shift+V` | 终端粘贴 |
| `Ctrl+Shift+A` | 终端全选 |
| `Ctrl+T` | 新建标签页 |
| `Ctrl+W` | 关闭当前标签页 |
| `Ctrl+Tab` | 切换下一个标签页 |
| `Ctrl+Shift+Tab` | 切换上一个标签页 |

### 桌面版目录结构

```
# Windows
%APPDATA%/X-Shell/data/
├── connections.json      # SSH 连接配置
├── config.json          # 应用设置（含服务端口配置）
└── logs/               # 运行日志

# Linux
~/.config/X-Shell/data/
├── connections.json
├── config.json
└── logs/

# macOS
~/Library/Application Support/X-Shell/data/
├── connections.json
├── config.json
└── logs/
```

## 📦 打包部署

### Web 版 - Docker 部署

```bash
docker build -t x-shell .
docker run -d -p 3001:3001 -v $(pwd)/data:/app/data x-shell
```

### Web 版 - PM2 部署

```bash
npm run build
pm2 start ecosystem.config.js
```

### 桌面版 - 本地构建

**Linux (AppImage + deb):**

```bash
# 1. 构建前端
cd client && npm run build && cd ..

# 2. 构建后端
cd server && npm run build && cd ..

# 3. 构建桌面版
cd desktop

# 准备资源（复制 node 可执行文件和 server 代码）
bash scripts/prepare-resources.sh

# 编译 TypeScript
npm run build

# 打包（使用国内镜像加速下载 Electron）
ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npx electron-builder --linux

# 输出文件
cd release
# X-Shell-1.0.0.AppImage      - Linux 通用包（无需安装）
# x-shell-desktop_1.0.0_amd64.deb  - Debian/Ubuntu 安装包
```

**Windows (exe):**

```bash
# 前两步同上（构建 client 和 server）
cd desktop
bash scripts/prepare-resources.sh
npm run build

# Windows 打包（需在 Windows 环境或使用 Wine）
npx electron-builder --win

# 输出文件
cd release
# X-Shell-1.0.0.exe          - Windows 安装包
# X-Shell-1.0.0-portable.exe  - Windows 绿色版
```

**macOS (dmg):**

```bash
# 前两步同上
cd desktop
bash scripts/prepare-resources.sh
npm run build
npx electron-builder --mac

# 输出文件
cd release
# X-Shell-1.0.0.dmg  - macOS 安装包
```

### 桌面版目录结构

```
desktop/
├── src/
│   ├── main/              # 主进程源码
│   │   ├── index.ts       # 入口
│   │   ├── server.ts      # 服务器管理（含端口配置）
│   │   └── storage.ts     # 数据存储
│   ├── preload/           # 预加载脚本
│   │   └── index.ts       # 暴露 IPC API
│   ├── build/             # 打包配置
│   └── package.json
├── scripts/               # 构建脚本
└── release/               # 最终安装包输出
```

## 📚 文档

- [桌面版架构设计](./docs/desktop-architecture.md) - Electron 桌面版详细设计
- [开发指南](./docs/development.md) - 开发规范与贡献指南
- [故障排查](./docs/troubleshooting.md) - 常见问题与解决方案

## 🗺️ 路线图

- [x] SSH 终端连接
- [x] SFTP 文件管理
- [x] 多标签页支持
- [x] 会话管理器（无限层级文件夹）
- [x] 私钥认证
- [x] 文件传输进度显示
- [x] 可拖拽调整区域宽度
- [x] 数据存储路径配置
- [x] **桌面版应用** (Electron) ✅ 已完成 (Linux AppImage/deb)
- [x] 配置导入导出 (Xshell/FinalShell/JSON)
- [x] 终端复制粘贴功能
- [x] **后端服务端口配置** ✅ 已完成（自定义端口 + 自动冲突处理）
- [ ] SFTP 文件编辑功能
- [ ] 会话搜索功能
- [ ] 多语言支持

## 🤝 贡献指南

欢迎提交 Issue 和 PR！

1. Fork 本项目
2. 创建你的特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开一个 Pull Request

## 📄 许可证

[MIT](LICENSE) © 2024 X-Shell Contributors

## 🙏 鸣谢

- [xterm.js](https://xtermjs.org/) - 强大的终端组件
- [ssh2](https://github.com/mscdex/ssh2) - Node.js SSH2 客户端
- [Vue.js](https://vuejs.org/) - 渐进式前端框架
- [Electron](https://www.electronjs.org/) - 跨平台桌面应用框架