# workbuddy-web-ssh

**Repository Path**: JabinL/workbuddy-web-ssh

## Basic Information

- **Project Name**: workbuddy-web-ssh
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-22
- **Last Updated**: 2026-05-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WorkBuddy Web SSH

> 基于 Web 的 SSH 终端管理平台 — 浏览器即终端，无需安装任何客户端。

[![Vue](https://img.shields.io/badge/Vue-3.5-4FC08D?logo=vue.js)](https://vuejs.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.115-009688?logo=fastapi)](https://fastapi.tiangolo.com/)
[![TypeScript](https://img.shields.io/badge/TypeScript-6.0-3178C6?logo=typescript)](https://www.typescriptlang.org/)
[![Python](https://img.shields.io/badge/Python-3.12-3776AB?logo=python)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

---

## 功能特性

| 功能 | 说明 |
|------|------|
| Web SSH 终端 | 基于 xterm.js 的全功能终端模拟器，WebSocket 实时通信，新标签页独立打开 |
| 多标签终端 | 同时连接多台服务器，标签页自由切换 |
| SFTP 文件管理 | 终端内嵌 SFTP 面板，支持上传/下载/编辑/权限管理 |
| 主机管理 | 添加/编辑/删除主机，多级分组管理，批量操作 |
| 凭据管理 | 密码或 SSH 密钥认证，AES-256-GCM 加密存储 |
| 快速连接 | 无需预先保存，直接输入地址和凭据立即连接 |
| 会话管理 | 查看历史会话（含用户/主机/IP 信息）、活跃会话、强制终止 |
| 命令记录 | 自动记录 SSH 会话中的命令及输出，支持查询和回溯 |
| 操作审计 | 会话录制与回放 (asciicast v2 格式，自动持久化) |
| 旁路监控 | 管理员实时只读监控任意活跃 SSH 会话 |
| 权限控制 | 三级角色 (user/admin/super_admin) 精细化权限 |
| MobaXterm 风格布局 | 左侧边栏主机分组树 + 会话列表，右侧终端区域 |
| 页面刷新保护 | 活跃终端时刷新页面弹出确认提醒 |
| 多主题 | 11 套预设主题，终端颜色自动跟随 |
| 国际化 | 中文 / English 双语切换，即时生效 |

## 快速开始

### 环境要求

- Node.js 18+ / npm 9+
- Python 3.12+ / pip 24+

### 后端启动

```bash
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

### 前端启动

```bash
cd frontend
npm install
npm run dev
```

### 访问应用

打开浏览器访问 **http://localhost:5173**

**默认管理员账户**: `admin` / `Admin@123`

## 技术栈

| 层面 | 技术 |
|------|------|
| 前端框架 | Vue 3 + TypeScript + Vite |
| UI | Tailwind CSS 4 + 自定义 CSS 变量主题系统 |
| 状态管理 | Pinia |
| 国际化 | vue-i18n v11 |
| 终端 | @xterm/xterm 6 + WebSocket |
| 后端框架 | FastAPI (Python) |
| 数据库 | SQLite (aiosqlite 异步驱动) |
| ORM | SQLAlchemy 2 (async) |
| SSH | Paramiko |
| 认证 | JWT (python-jose) + bcrypt |
| 加密 | AES-256-GCM (cryptography) |

## 项目结构

```
workbuddy-web-ssh/
├── frontend/                 # Vue 3 前端
│   └── src/
│       ├── views/            # 9 个路由页面 (含 TerminalPage, SessionReplay, AdminMonitor)
│       ├── components/       # 布局 + 终端组件
│       ├── stores/           # Pinia 状态 (auth/terminal/theme/locale/hosts)
│       ├── api/              # Axios + API 封装
│       ├── locales/          # 中英文翻译
│       └── assets/styles/    # 全局样式 + 11 套主题
├── backend/                  # FastAPI 后端
│   └── app/
│       ├── api/v1/           # 9 个路由模块 (56+ 接口)
│       ├── models/           # 13 个数据模型
│       ├── schemas/          # Pydantic 请求/响应模型
│       └── services/         # 认证/加密/SSH 服务
└── docs/                     # 项目文档
    ├── PRD.md                # 产品需求文档
    ├── DESIGN.md             # 系统设计文档
    ├── TECH.md               # 技术文档
    └── DEV.md                # 开发文档
```

## API 概览

所有接口前缀: `/api/v1`

| 模块 | 端点 | 接口数 | 说明 |
|------|------|--------|------|
| Auth | `/auth/*` | 6 | 登录/注册/刷新/登出/个人信息 |
| Users | `/users/*` | 6 | 用户 CRUD + 角色管理 |
| Hosts | `/hosts/*` | 12 | 主机 CRUD + 批量操作 + 导入导出 |
| Credentials | `/credentials/*` | 7 | 凭据 CRUD + 密钥生成 |
| Sessions | `/sessions/*` | 7 | 会话列表/统计/终止/录制回放/命令记录 |
| Host Groups | `/hosts/groups/*` | 4 | 主机分组 CRUD (树形结构) |
| Settings | `/settings/*` | 6 | 用户设置 + 配色方案 |
| Terminal | `/ws/terminal`, `/ws/terminal/monitor` | 2 | WebSocket 终端 + 只读监控 |
| Quick Connect | `/quick-connect` | 1 | 快速 SSH 连接 |

> 完整 API 文档: 启动后端后访问 http://localhost:8000/docs

## 文档

| 文档 | 说明 |
|------|------|
| [PRD.md](docs/PRD.md) | 产品需求文档 — 功能需求、用户故事、非功能需求 |
| [DESIGN.md](docs/DESIGN.md) | 系统设计文档 — 架构图、数据库设计、API 设计、安全设计 |
| [TECH.md](docs/TECH.md) | 技术文档 — 技术栈、核心模块实现、配置参考 |
| [DEV.md](docs/DEV.md) | 开发文档 — 环境搭建、开发规范、调试指南、部署建议 |

## 开发

```bash
# 前端类型检查
cd frontend && npx vue-tsc --noEmit

# 前端构建
cd frontend && npm run build

# 后端开发模式
cd backend && uvicorn app.main:app --reload

# 后端 API 文档
# 访问 http://localhost:8000/docs
```

## 安全

- JWT 双 Token 认证 (Access + Refresh)
- 密码 bcrypt 哈希存储
- SSH 凭据 AES-256-GCM 加密存储
- 三级 RBAC 权限控制
- 登录频率限制
- 每用户最大并发会话限制

> 生产部署前请替换 `.env` 中的所有 `dev-*` 占位密钥！

## License

MIT