基于 Web 的现代化 SSH 终端应用
🚀 无需安装本地客户端，通过浏览器即可连接远程 SSH 服务器
--- ## 📖 项目简介 LingTerm 是一个基于 Web 的 SSH 终端应用，旨在让用户能够通过浏览器直接连接到远程 SSH 服务器。它结合了 **FastAPI** 的高性能后端和 **Vue3** 的现代化前端，提供了无需安装本地客户端即可进行远程服务器管理的便捷方案。 ### ✨ 核心优势 - 🌐 **随时随地访问** - 只需浏览器，无需安装任何软件 - ⚡ **高性能架构** - FastAPI + WebSocket 确保流畅体验 - 🎨 **现代化界面** - 美观的渐变 UI 设计，支持自定义主题 - 🔧 **功能完善** - SSH 终端 + SFTP 文件传输 + 主机管理 --- ## 🎯 功能特性 | 功能模块 | 特性说明 | |---------|---------| | 🚀 **SSH 连接** | 基于 WebSocket 的实时 SSH 连接，支持密码认证 | | 💻 **终端模拟** | xterm.js 驱动的现代化 Web 终端，支持自适应和链接识别 | | 📁 **文件传输** | 完整的 SFTP 文件管理功能，支持上传下载 | | 🏷️ **会话管理** | 多标签页管理，会话保持，快速切换 | | 🎨 **主题定制** | 多种终端主题配色，个性化你的工作环境 | | 📱 **响应式设计** | 适配不同屏幕尺寸，移动端友好 | | 📋 **主机管理** | 保存常用主机配置，一键快速连接 | --- ## 🏗️ 项目结构 ``` LingTerm/ ├── backend/ # FastAPI 后端 │ ├── main.py # 主应用文件（路由、WebSocket端点） │ ├── pyproject.toml # Python 项目配置及依赖管理 │ ├── requirements.txt # Python 依赖列表 │ ├── uv.lock # UV 包管理器锁文件 │ └── utils/ # 工具模块 │ ├── ssh_utils.py # SSH 连接封装（Paramiko） │ ├── sftp_utils.py # SFTP 文件传输封装 │ └── file_utils.py # 通用文件处理工具 ├── frontend/ # Vue3 前端 │ ├── src/ │ │ ├── App.vue # 根组件（整体布局） │ │ ├── main.js # 入口文件 │ │ ├── api/ # API 请求封装 │ │ │ └── sftp.js # SFTP 相关 API │ │ ├── components/ # Vue 组件 │ │ │ ├── AppHeader.vue # 应用头部组件 │ │ │ ├── TerminalArea.vue # 终端显示区域（xterm.js集成） │ │ │ ├── FileManager.vue # 文件管理器（SFTP交互） │ │ │ ├── HostList.vue # 主机列表管理 │ │ │ ├── ThemeConfig.vue # 主题配置界面 │ │ │ └── themes.js # 终端主题配色定义 │ │ └── utils/ # 工具函数 │ │ └── request.js # HTTP 请求工具封装 │ ├── index.html # HTML 模板 │ ├── vite.config.js # Vite 构建配置（含代理设置） │ ├── package.json # Node 依赖及脚本配置 │ └── pnpm-lock.yaml # PNPM 包管理器锁文件 ├── start.sh # Linux/Mac 一键启动脚本 ├── start.bat # Windows 一键启动脚本 └── README.md # 项目说明文档 ``` --- ## 🚀 快速开始 ### 📋 环境要求 | 依赖项 | 版本要求 | 说明 | |-------|---------|------| | Python | 3.8+ | 后端运行环境 | | Node.js | 16+ | 前端运行环境 | | npm/yarn/pnpm | 最新版 | 前端包管理器 | | **uv** | 最新版 | ⭐ 推荐的 Python 包管理器 | --- ### 🔧 后端安装与启动 #### ⭐ 方式一：使用 uv（强烈推荐） > [uv](https://github.com/astral-sh/uv) 是一个极速的 Python 包安装器和解析器，比 pip 快 **10-100 倍**。 **1️⃣ 安装 uv** ```bash # macOS/Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows (PowerShell) powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` **2️⃣ 进入后端目录** ```bash cd backend ``` **3️⃣ 安装依赖** ```bash uv sync ``` **4️⃣ 启动服务** ```bash # 方式 A: 直接运行 uv run python main.py # 方式 B: 使用 uvicorn（开发模式，支持热重载） uv run uvicorn main:app --reload --host 0.0.0.0 --port 8000 ``` ✅ 后端服务将在 `http://localhost:8000` 启动 --- #### 📦 方式二：使用 pip（传统方式） **1️⃣ 进入后端目录** ```bash cd backend ``` **2️⃣ 安装依赖** ```bash pip install -r requirements.txt ``` **3️⃣ 启动服务** ```bash python main.py ``` ✅ 后端服务将在 `http://localhost:8000` 启动 --- #### 💡 为什么推荐使用 uv？ | 特性 | uv | pip | |-----|----|-----| | 🚀 安装速度 | **快 10-100 倍** | 标准速度 | | 🔒 依赖解析 | 可靠且一致 | 偶尔冲突 | | 📦 虚拟环境 | 自动管理 | 需手动创建 | | 🎯 现代化工具 | ✅ 完美支持 pyproject.toml | ❌ 传统方式 | | 🔄 缓存机制 | 智能缓存，重复安装更快 | 基础缓存 | --- ### 🎨 前端安装与启动 **1️⃣ 进入前端目录** ```bash cd frontend ``` **2️⃣ 安装依赖** ```bash # 使用 pnpm（推荐） pnpm install # 或使用 npm npm install # 或使用 yarn yarn install ``` **3️⃣ 启动开发服务器** ```bash npm run dev ``` ✅ 前端服务将在 `http://localhost:3000` 启动 --- ### 🌐 访问应用 打开浏览器访问 **`http://localhost:3000`**，输入 SSH 连接信息： #### 先在主机列表中右击 "添加主机"，如下图：   #### 🔑 连接信息 添加完主机信息后，双击主机信息后，弹出连接信息填写框，填入登录用户和密码，如下图：   #### 打开文件管理器 当前主机已连接成功后，点击 "打开文件管理器" 按钮，即可打开文件管理器，如下图：  >文件管理器完成文件上传、下载功能和删除的功能。 #### 设置终端的主题 在页面上打开主题设置面板，如下图：  --- ## 🚢 生产部署 ### 🔙 后端部署 #### 使用 Uvicorn ```bash uvicorn main:app --host 0.0.0.0 --port 8000 ``` #### 使用 Gunicorn（⭐ 推荐） ```bash gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000 ``` > 💡 `-w 4` 表示启动 4 个 worker 进程，可根据服务器配置调整 --- ### 🎨 前端构建 ```bash cd frontend npm run build ``` 构建产物位于 `frontend/dist` 目录，可使用 Nginx 或其他静态服务器托管。 --- ### 🌐 Nginx 配置示例 ```nginx server { listen 80; server_name your-domain.com; # 前端静态文件 location / { root /path/to/frontend/dist; try_files $uri $uri/ /index.html; } # WebSocket 代理 location /ws/ { proxy_pass http://localhost:8000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } # API 代理 location /api/ { proxy_pass http://localhost:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } } ``` --- ## 🛠️ 技术栈 ### 🔙 后端技术 | 技术 | 用途 | 版本 | |-----|------|------| | **FastAPI** | 现代、快速的 Web 框架 | Latest | | **Paramiko** | Python SSH 客户端库 | Latest | | **WebSocket** | 实时双向通信协议 | - | | **Uvicorn** | ASGI 服务器 | Latest | | **uv** | 极速 Python 包管理器 | Latest | ### 🎨 前端技术 | 技术 | 用途 | 版本 | |-----|------|------| | **Vue 3** | 渐进式 JavaScript 框架 | 3.x | | **Vite** | 下一代前端构建工具 | Latest | | **xterm.js** | 终端模拟器 | Latest | | **xterm-addon-fit** | 终端自适应大小插件 | Latest | | **xterm-addon-web-links** | 终端链接识别插件 | Latest | | **pnpm** | 高效的包管理器 | Latest | --- ## 🔒 安全建议 > ⚠️ **重要提示：** 生产环境部署时请务必注意以下安全事项 1. **🔐 启用 HTTPS/WSS** - 生产环境必须使用 HTTPS/WSS，防止密码明文传输 - 推荐使用 Let's Encrypt 免费证书 2. **🛡️ 限制访问来源** - 通过防火墙规则限制 SSH 连接来源 IP - 使用 Nginx 白名单机制 3. **🔑 优先使用密钥认证** - SSH 密钥认证比密码更安全 - 禁用密码登录，仅允许密钥认证 4. **⏱️ 设置连接超时** - 配置空闲超时时间，自动断开长时间无操作的连接 - 建议设置为 5-10 分钟 5. **📝 启用日志审计** - 记录所有 SSH 连接操作 - 定期审查日志，发现异常行为 --- ## ❓ 常见问题 ### 1️⃣ 连接失败 **可能原因：** - ❌ 目标服务器 SSH 服务未运行 - ❌ 防火墙阻止了 SSH 端口访问 - ❌ 用户名或密码错误 **解决方案：** ```bash # 检查 SSH 服务状态 sudo systemctl status sshd # 测试 SSH 连接 ssh username@hostname -p 22 ``` --- ### 2️⃣ WebSocket 连接错误 **可能原因：** - ❌ 后端服务未正常运行 - ❌ WebSocket 代理配置错误（生产环境） - ❌ 浏览器控制台有错误信息 **解决方案：** - 检查后端服务是否启动：`curl http://localhost:8000` - 查看浏览器控制台（F12）的错误信息 - 验证 Nginx WebSocket 代理配置 --- ### 3️⃣ 终端显示异常 **可能原因：** - ❌ 浏览器兼容性问题 - ❌ 网络连接不稳定 **解决方案：** - 刷新页面重试 - 推荐使用 **Chrome** 或 **Firefox** 浏览器 - 检查网络连接状态 --- ## 📅 开发计划 ### ✅ 已完成 - [x] 添加会话管理 - [x] 支持多标签页 - [x] 添加文件传输功能（SFTP） - [x] 支持自定义终端主题 ### 🚧 进行中 - [ ] 添加操作日志记录 - [ ] 支持 SSH 密钥认证 ### 💡 未来规划 - [ ] 支持端口转发 - [ ] 添加命令历史记录 - [ ] 支持多人协作会话 - [ ] 集成 AI 助手 --- ## 📄 许可证 本项目采用 **MIT License** - 详见 [LICENSE](LICENSE) 文件 --- ## 🤝 贡献指南 欢迎贡献代码、报告问题或提出建议！ **贡献步骤：** 1. Fork 本仓库 2. 创建特性分支 (`git checkout -b feature/AmazingFeature`) 3. 提交更改 (`git commit -m 'Add some AmazingFeature'`) 4. 推送到分支 (`git push origin feature/AmazingFeature`) 5. 开启 Pull Request --- ## 📬 联系方式 - 📧 Email: 972479352@qq.com - 🐛 Issues: [Gitee Issues](git@gitee.com:didiplus/LingTerm.git) ---Made with ❤️ by LingTerm Team
如果这个项目对你有帮助，请考虑给它一个 ⭐ Star！