yinjianm
3f6e2bffc6
补充快捷指令动态变量解析与编辑弹窗一键插入， 统一列表执行、粘贴到终端和批量发送的处理链路 扩展快捷命令右键菜单动作，并为文件面板新增 多根目录资源管理器式侧栏浏览体验 为首页 dashboard 增加当前用户与系统总览双视角的 实时会话指标展示，并同步更新相关知识库记录
171 lines
8.0 KiB
Markdown
171 lines
8.0 KiB
Markdown
# 变更提案: dashboard-live-session-metrics
|
|
|
|
## 元信息
|
|
```yaml
|
|
类型: 新功能
|
|
方案类型: implementation
|
|
优先级: P1
|
|
状态: 草稿
|
|
创建: 2026-03-26
|
|
```
|
|
|
|
---
|
|
|
|
## 1. 需求
|
|
|
|
### 背景
|
|
首页 dashboard 已经具备稳定统计能力，但仍缺少运行态视角。用户继续要求补“在线会话数/实时指标”，并明确选择“混合视角”，意味着首页同时需要展示当前登录用户的运行态会话信息，以及整个系统范围内的总在线会话概况。
|
|
|
|
### 目标
|
|
- 在现有 dashboard summary 基础上补充运行态指标，而不是另起一套接口。
|
|
- 同时展示“当前用户视角”和“系统总览视角”的在线 SSH / 挂起会话指标。
|
|
- 补充能体现实时性的附加指标，例如被监控中的活跃状态流数量，让首页更接近真实运维总控台。
|
|
- 保持首页首屏仍为单次 summary 请求，不要求前端直接订阅 WebSocket 状态。
|
|
|
|
### 约束条件
|
|
```yaml
|
|
时间约束: 本轮内完成前后端联动与基础构建验证
|
|
性能约束: 运行态统计应在现有 dashboard summary 接口内组合返回，避免首页新增额外请求
|
|
兼容性约束: 不改变现有 workspace WebSocket 协议与挂起会话 API 语义
|
|
业务约束: 当前用户口径必须与后端登录态一致；系统口径必须来自后端共享运行态，而不是浏览器本地 session store 猜测
|
|
```
|
|
|
|
### 验收标准
|
|
- [ ] `GET /api/v1/dashboard/summary` 返回新增的 live metrics 字段
|
|
- [ ] 首页同时展示当前用户在线 SSH / 挂起会话数与系统总在线 SSH / 挂起会话数
|
|
- [ ] 首页补充至少一个与实时运行态有关的附加指标，例如当前活跃状态监控流数量
|
|
- [ ] 前端 UI 对新增实时指标完成中英日文案适配
|
|
- [ ] `packages/backend` 与 `packages/frontend` 构建通过
|
|
|
|
---
|
|
|
|
## 2. 方案
|
|
|
|
### 技术方案
|
|
延续现有 `dashboard` 业务域，但把运行态统计从纯数据库聚合扩展为“数据库统计 + 内存运行态组合”。数据库部分继续由 `dashboard.repository.ts` 提供稳定统计；运行态部分由 `dashboard.service.ts` 直接组合后端共享的 `clientStates` 与 `sshSuspendService`：前者提供系统范围和按当前 `req.session.userId` 过滤的在线 SSH 会话数量，并进一步统计处于状态监控中的会话数量；后者补充当前用户与系统范围的挂起会话数。前端沿用现有 `dashboard.store.ts`，在 `DashboardOverviewPanel.vue` 中新增“实时会话”板块，使用清晰的双列卡片同时呈现“我的会话”和“系统会话”。
|
|
|
|
### 影响范围
|
|
```yaml
|
|
涉及模块:
|
|
- backend: 扩展 dashboard summary 组合逻辑，补运行态统计
|
|
- backend: 为 sshSuspendService 暴露系统级计数方法
|
|
- frontend: 扩展 summary 类型与总览组件
|
|
- frontend: 更新 dashboard 文案
|
|
预计变更文件: 6-9
|
|
```
|
|
|
|
### 风险评估
|
|
| 风险 | 等级 | 应对 |
|
|
|------|------|------|
|
|
| 前端本地 session store 与后端真实在线会话不一致 | 中 | 在线/挂起口径统一以后端运行态为准，只在首页展示后端汇总结果 |
|
|
| `clientStates` 中可能包含正在恢复、挂起标记中或半断开的会话 | 中 | 统计时显式按状态字段过滤，优先统计未被服务接管的可用活跃会话 |
|
|
| `sshSuspendService` 目前只有按用户列出接口，没有系统汇总接口 | 低 | 为服务补一个只读统计方法，不改现有对外 API |
|
|
|
|
---
|
|
|
|
## 3. 技术设计
|
|
|
|
### 架构设计
|
|
```mermaid
|
|
flowchart LR
|
|
A[DashboardController] --> B[DashboardService]
|
|
B --> C[dashboard.repository.ts]
|
|
B --> D[clientStates]
|
|
B --> E[sshSuspendService]
|
|
B --> F[req.session.userId]
|
|
```
|
|
|
|
### API设计
|
|
#### GET /api/v1/dashboard/summary
|
|
- **新增响应字段**:
|
|
```json
|
|
{
|
|
"liveMetrics": {
|
|
"currentUser": {
|
|
"activeSshSessions": 0,
|
|
"suspendedSessions": 0
|
|
},
|
|
"system": {
|
|
"activeSshSessions": 0,
|
|
"suspendedSessions": 0,
|
|
"statusStreams": 0
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 数据模型
|
|
| 字段 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| `liveMetrics.currentUser.activeSshSessions` | `number` | 当前登录用户的活跃 SSH 会话数 |
|
|
| `liveMetrics.currentUser.suspendedSessions` | `number` | 当前登录用户的挂起会话数 |
|
|
| `liveMetrics.system.activeSshSessions` | `number` | 系统范围的活跃 SSH 会话数 |
|
|
| `liveMetrics.system.suspendedSessions` | `number` | 系统范围的挂起会话数 |
|
|
| `liveMetrics.system.statusStreams` | `number` | 当前处于状态轮询中的活跃会话数 |
|
|
|
|
---
|
|
|
|
## 4. 核心场景
|
|
|
|
### 场景: 当前用户查看自己的在线与挂起会话
|
|
**模块**: frontend / backend
|
|
**条件**: 用户已登录并打开首页 dashboard。
|
|
**行为**: 后端基于当前 session 的 `userId` 统计用户活跃 SSH 会话和挂起会话，并在首页实时会话面板中显示。
|
|
**结果**: 用户能快速判断“我当前开了多少会话、还有多少挂起会话待恢复”。
|
|
|
|
### 场景: 管理员查看系统整体运行态
|
|
**模块**: frontend / backend
|
|
**条件**: 首页 dashboard 已完成 summary 拉取。
|
|
**行为**: 后端同时返回系统总活跃 SSH 会话数、总挂起会话数和状态监控流数量。
|
|
**结果**: 首页能同时表达“我的视角”和“系统视角”，满足混合视角需求。
|
|
|
|
---
|
|
|
|
## 5. 技术决策
|
|
|
|
### dashboard-live-session-metrics#D001: 运行态指标继续并入 summary 接口，而不是前端再建额外实时 API
|
|
**日期**: 2026-03-26
|
|
**状态**: ✅采纳
|
|
**背景**: 现有 dashboard 已经是单接口驱动。继续拆新接口只会增加首页请求数和前端状态拼装复杂度。
|
|
**选项分析**:
|
|
| 选项 | 优点 | 缺点 |
|
|
|------|------|------|
|
|
| A: 扩展现有 `/api/v1/dashboard/summary` | 首页保持单请求，口径集中，最适合当前仪表盘架构 | service 层需同时组合数据库与运行态来源 |
|
|
| B: 新增独立 `/api/v1/dashboard/live` | 可把稳定统计和实时统计分离 | 首页需要二次请求和额外错误处理，前端复杂度上升 |
|
|
**决策**: 选择方案A
|
|
**理由**: 这轮增强是现有 dashboard 的自然延展，不值得拆出第二条首页专用链路。
|
|
**影响**: backend, frontend
|
|
|
|
### dashboard-live-session-metrics#D002: 在线/挂起统计口径以后端运行态为准，不使用浏览器本地 session store 作为首页事实来源
|
|
**日期**: 2026-03-26
|
|
**状态**: ✅采纳
|
|
**背景**: 前端 session store 只能反映当前浏览器标签页，无法代表同一用户其他浏览器窗口、恢复中的会话或后端已接管的挂起状态。
|
|
**选项分析**:
|
|
| 选项 | 优点 | 缺点 |
|
|
|------|------|------|
|
|
| A: 后端 `clientStates + sshSuspendService` 统一统计 | 口径统一，能同时覆盖系统和当前用户 | 需要后端 service 增加只读组合逻辑 |
|
|
| B: 首页直接读前端 `session.store` | 实现快 | 只能看到当前浏览器局部状态，无法满足混合视角 |
|
|
**决策**: 选择方案A
|
|
**理由**: 用户明确要“当前用户 + 系统总览”混合视角，只能以后端运行态作为事实源。
|
|
**影响**: backend, frontend
|
|
|
|
---
|
|
|
|
## 6. 成果设计
|
|
|
|
### 设计方向
|
|
- **美学基调**: 保持现有 dashboard 驾驶舱风格，但把运行态指标做成更“控制台式”的双层面板
|
|
- **记忆点**: 首页同时出现“我的会话 / 系统会话”两组清晰分栏，不再只有静态总量
|
|
- **参考**: 当前 dashboard 卡片体系 + 运维控制台常见的 live session summary
|
|
|
|
### 视觉要素
|
|
- **配色**: 当前用户指标偏主色和绿色，系统总览指标偏青蓝和琥珀，避免与稳定总量卡片混淆
|
|
- **字体**: 沿用现有项目后台字体体系
|
|
- **布局**: 运行态指标独立为一块 summary panel，位于统计卡片区之后、图表区之前
|
|
- **动效**: 只保留轻量 hover 和数字层级，不增加复杂动画
|
|
- **氛围**: 强调“控制面板”而非“报表页”，以密度和清晰分组为主
|
|
|
|
### 技术约束
|
|
- **可访问性**: 每个实时指标必须带文字标签，不用纯 icon 表达
|
|
- **响应式**: 窄屏下“当前用户 / 系统总览”两组指标要能自然折叠为单栏
|