yinjianm
f2f9c754f8
Rework the default /workspace layout into a three-column view with a left-side Workbench, centered terminal, and right-side status monitor. Add a new Workbench pane that groups file manager, command history, and editor into tabs while preserving panel state. Extend server status data to expose cumulative network upload and download totals since boot, and show them in the monitor. Include a lightweight migration for the old default layout and update related locale strings, pane metadata, and knowledge base records.
104 lines
4.2 KiB
Markdown
104 lines
4.2 KiB
Markdown
# 项目上下文
|
||
|
||
## 1. 基本信息
|
||
|
||
```yaml
|
||
名称: Nexus Terminal
|
||
描述: 基于 npm workspaces 的远程连接终端平台，提供 Web SSH、SFTP、RDP、VNC 与桌面端相关能力。
|
||
类型: Web应用
|
||
状态: 维护中
|
||
```
|
||
|
||
## 2. 技术上下文
|
||
|
||
```yaml
|
||
语言: TypeScript, Vue, Node.js
|
||
框架: Vue 3, Vite, Express 5
|
||
包管理器: npm workspaces
|
||
构建工具: Vite（frontend）, TypeScript 编译（backend/remote-gateway）, GitHub Actions + GHCR（镜像发布）, Docker Compose（部署）
|
||
```
|
||
|
||
### 主要依赖
|
||
| 依赖 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| vue | ^3.3.0 | 前端应用框架 |
|
||
| vite | >=5.4.19 | 前端开发与构建 |
|
||
| pinia | ^3.0.2 | 前端状态管理 |
|
||
| element-plus | ^2.9.11 | 前端组件库 |
|
||
| xterm | ^5.3.0 | Web 终端渲染 |
|
||
| monaco-editor | ^0.52.2 | 在线文件编辑器 |
|
||
| express | ^5.1.0 | 后端 REST 服务 |
|
||
| express-session | ^1.18.1 | 登录会话管理 |
|
||
| sqlite3 | ^5.1.7 | 本地数据持久化 |
|
||
| ssh2 | ^1.16.0 | SSH/SFTP 连接能力 |
|
||
| guacamole-lite | ^0.7.3 | RDP/VNC 网关封装 |
|
||
| ws | ^8.18.1 | WebSocket 通信 |
|
||
|
||
## 3. 项目概述
|
||
|
||
### 核心功能
|
||
- 统一管理 SSH、SFTP、RDP、VNC 远程连接。
|
||
- 提供基于 Vue 3 的工作区、布局配置、主题定制和命令输入体验。
|
||
- `/workspace` 默认采用“三栏工作台”：左侧 Workbench tab 容器、中央终端、右侧状态监控。
|
||
- 提供认证、2FA、Passkey、Captcha、IP 白名单/黑名单、通知和审计能力。
|
||
- 支持远程文件管理、在线编辑、快速命令、命令历史和 SSH 挂起会话。
|
||
- 使用独立 `remote-gateway` 服务为远程桌面连接生成加密令牌并对接 `guacd`。
|
||
|
||
### 项目边界
|
||
```yaml
|
||
范围内:
|
||
- Web 前端、Node.js 后端、远程桌面网关三部分代码
|
||
- Docker Compose 部署编排和运行时环境变量
|
||
- 基于 SQLite/data 目录的本地持久化
|
||
范围外:
|
||
- 自动化数据备份能力
|
||
- 仓库内未出现的桌面端打包代码
|
||
- 完整自动化测试体系（当前仓库未建立）
|
||
```
|
||
|
||
## 4. 开发约定
|
||
|
||
### 代码规范
|
||
```yaml
|
||
命名风格: TypeScript/JavaScript 代码以 camelCase 为主；Vue 组件使用 PascalCase；目录多为 kebab-case
|
||
文件命名: 后端常见 *.controller.ts / *.service.ts / *.repository.ts；前端 composable 使用 use*.ts；Pinia 使用 *.store.ts
|
||
目录组织: 根目录以 packages/* 划分应用；frontend 按 views/components/composables/stores 划分；backend 按业务域拆分子目录
|
||
```
|
||
|
||
### 错误处理
|
||
```yaml
|
||
错误码格式: 后端与 remote-gateway 主要返回 HTTP 状态码 + JSON error 字段；前端初始化失败时仍尝试挂载应用
|
||
日志级别: 以 console.log / console.warn / console.error 为主，关键启动失败直接 process.exit(1)
|
||
```
|
||
|
||
### 测试要求
|
||
```yaml
|
||
测试框架: 未配置统一测试框架
|
||
覆盖率要求: 未声明
|
||
测试文件位置: 当前仓库未建立系统化测试目录，变更后以 package 级 build 和手工冒烟验证为主
|
||
```
|
||
|
||
### Git规范
|
||
```yaml
|
||
分支策略: 仓库内未声明
|
||
提交格式: 仓库内未声明
|
||
```
|
||
|
||
## 5. 当前约束（源自历史决策）
|
||
|
||
> 这些是当前生效的技术约束，详细决策过程见对应方案包
|
||
|
||
| 约束 | 原因 | 决策来源 |
|
||
|------|------|---------|
|
||
| `/workspace` 默认主布局采用“Workbench + 终端 + 状态监控”三栏结构 | 统一终端主区高度，并将命令历史 / 文件 / 编辑器集中到左侧工作台 | workspace-workbench-monitor#D001 |
|
||
|
||
## 6. 已知技术债务（可选）
|
||
|
||
> 主动识别的需要未来处理的技术问题
|
||
|
||
| 债务描述 | 优先级 | 来源 | 建议处理时机 |
|
||
|---------|--------|------|-------------|
|
||
| 根仓与子包均缺少成体系自动化测试，`test` 脚本未形成有效校验 | P1 | 仓库现状 | 涉及核心连接链路、认证或文件操作改造前优先补齐 |
|
||
| `packages/backend/src/index.ts` 同时承担环境初始化、数据库启动、路由装配与服务启动，入口职责偏重 | P2 | 代码结构扫描 | 后端进入中型重构或新增启动流程时拆分 |
|
||
| `packages/remote-gateway/src/server.ts` 以单文件承载配置、HTTP API、Guacamole 服务器与优雅退出逻辑 | P2 | 代码结构扫描 | 远程桌面能力继续扩展前拆出配置层和控制器层 |
|