# PRD 需求文档 — 自动化部署测试模块

> **文档类型**: PRD 需求文档
> **创建日期**: 2026-08-12
> **作者**: czj
> **优先级**: P0
> **版本**: v1.0
> **状态**: 待评审
> **所属模块**: 自动化部署测试（部署运维）

---

## 一、需求背景

### 1.1 业务背景

当前平台已覆盖 UI 自动化测试、安全测试、性能测试、设备模拟等模块，测试能力日趋完善。但随着**新统一平台**的持续迭代，每次版本发布都需要人工通过 SSH 登录目标服务器执行部署脚本，部署过程存在以下痛点：

1. **操作繁琐**：需要运维/测试人员手动打开终端、SSH 连接多台服务器、逐条执行命令。
2. **交互式输入无法自动化**：部署脚本执行过程中常包含交互式提示（输入数据库密码、确认 Y/N、选择部署模式等），人工值守耗时且易出错。
3. **过程不可追溯**：部署过程中的输出日志散落在各终端，无法统一留存、回看、排障。
4. **无法实时监测**：部署发起后无法集中查看进度，失败原因排查困难。

因此，需要在本测试平台中内置**自动化部署测试模块**，通过 Web 界面一键触发远程部署，自动完成脚本交互输入，实时流式展示部署日志，并留存历史执行记录。

### 1.2 目标用户

| 用户角色 | 使用场景 | 核心需求 |
|---------|---------|---------|
| 测试工程师 | 新统一平台版本发布前执行部署验证 | 一键执行部署、实时查看部署进度、确认部署成功 |
| 开发工程师 | 联调环境部署 / 脚本调试 | 配置服务器与部署脚本、查看完整交互日志 |
| 运维人员 | 多环境发布与回滚 | 集中管理多台目标服务器、查看历史部署记录 |

### 1.3 需求目标

1. **远程部署执行**：通过 SSH 连接**远程目标服务器**（非本机），一键执行目标服务器上已有的部署脚本
2. **交互式输入自动完成**：部署脚本执行期间的交互式提示（如输入密码、确认、选择模式）自动应答
3. **实时进度监测**：部署过程通过 WebSocket 实时流式展示日志输出
4. **执行记录留存**：部署历史记录与完整日志持久化存储，支持回看
5. **服务器与脚本管理**：平台内维护目标服务器列表与部署脚本配置

---

## 二、功能需求

### 2.1 功能模块总览

```
自动化部署测试（父级模块，侧边栏独立菜单）
├── 服务器管理    — 目标服务器 SSH 连接配置管理（IP、端口、凭据、连接测试）
├── 部署脚本      — 部署脚本配置（远程命令、工作目录、交互式应答规则）
└── 部署执行      — 一键执行部署 + 实时日志监测 + 历史记录回看
```

### 2.2 服务器管理

#### 功能描述

管理平台可 SSH 连接的**远程目标服务器**信息，是部署执行的基础。服务器凭据加密存储，支持密码/密钥两种认证方式。

#### 功能清单

| 功能 | 说明 | 优先级 |
|------|------|--------|
| 新增服务器 | 添加目标服务器（名称、IP、端口、用户名、密码/私钥、认证方式） | P0 |
| 编辑服务器 | 修改服务器配置（密码留空时不修改） | P0 |
| 删除服务器 | 删除服务器（有关联部署脚本时禁止删除） | P0 |
| 连接测试 | 通过 SSH 实际连接测试服务器连通性 | P0 |
| 服务器列表 | 展示所有服务器，含连接状态标识（未知/在线/离线） | P0 |

#### 服务器字段

| 字段 | 类型 | 说明 |
|------|------|------|
| 名称 | string | 服务器标识名称，如"生产环境-60" |
| 主机地址 | string | IP 或域名 |
| 端口 | integer | SSH 端口，默认 22 |
| 用户名 | string | SSH 登录用户名 |
| 密码 | string | SSH 密码（**加密存储**，编辑时留空表示不修改） |
| 认证方式 | enum | password（密码）/ key（私钥） |
| 私钥 | text | SSH 私钥内容（认证方式为 key 时填写） |
| 状态 | enum | unknown（未知）/ online（在线）/ offline（离线） |
| 描述 | text | 备注说明 |

### 2.3 部署脚本

#### 功能描述

配置部署脚本的远程执行命令与**交互式应答规则**。部署脚本已存在于目标服务器上，本模块仅配置其执行路径、工作目录与交互应答。

#### 功能清单

| 功能 | 说明 | 优先级 |
|------|------|--------|
| 新增脚本配置 | 配置脚本名称、目标服务器、远程命令、工作目录、超时时间 | P0 |
| 交互应答配置 | 配置多条"触发提示 → 应答内容"规则，自动完成交互输入 | P0 |
| 编辑脚本配置 | 修改脚本配置与交互应答规则 | P0 |
| 删除脚本配置 | 删除脚本配置 | P0 |
| 脚本列表 | 展示所有脚本，可按服务器筛选 | P0 |

#### 脚本字段

| 字段 | 类型 | 说明 |
|------|------|------|
| 名称 | string | 脚本配置名称，如"统一平台全量部署" |
| 描述 | text | 说明 |
| 目标服务器 | FK | 关联的服务器 |
| 远程命令 | string | 远程执行命令，如 `bash /opt/deploy/deploy.sh` |
| 工作目录 | string | 远程工作目录（可选，执行前先 cd） |
| 超时时间 | integer | 整体执行超时（秒），默认 3600 |

#### 交互式应答规则（核心）

每条规则定义"当输出中出现某提示时，自动发送某应答"：

| 字段 | 类型 | 说明 |
|------|------|------|
| 触发提示 | string | 匹配的提示文本，如"请输入数据库密码:" |
| 匹配方式 | enum | contains（包含匹配，默认）/ regex（正则匹配） |
| 应答内容 | string | 匹配后自动发送的内容（自动追加换行） |
| 超时 | integer | 等待该提示出现的最大时间（秒） |
| 顺序 | integer | 匹配顺序，防止重复匹配 |
| 敏感 | boolean | 是否敏感信息（日志中显示为 `***`） |
| 描述 | string | 该应答规则的说明 |

### 2.4 部署执行

#### 功能描述

一键执行部署的核心页面。选择脚本 → 点击【执行部署】→ 实时查看部署日志 → 完成/失败/取消。

#### 功能清单

| 功能 | 说明 | 优先级 |
|------|------|--------|
| 发起执行 | 选择部署脚本，一键【执行部署】 | P0 |
| 实时日志 | WebSocket 实时流式展示部署输出（终端风格，自动滚动） | P0 |
| 自动应答提示 | 日志中展示自动应答已发送（敏感内容隐藏） | P0 |
| 执行状态 | 状态徽标：待执行/执行中/成功/失败/已取消 + 耗时 | P0 |
| 取消执行 | 执行中可一键取消（关闭 SSH 通道） | P0 |
| 执行记录列表 | 展示历史执行记录（脚本、服务器、状态、耗时、触发人） | P0 |
| 执行详情 | 查看单次执行完整日志（历史回看） | P0 |
| 日志落库 | 每次执行日志持久化到数据库 | P0 |

#### 执行状态机

```
pending(待执行) → running(执行中) → completed(成功)
                                  → failed(失败)
                                  → cancelled(已取消)
```

#### WebSocket 消息类型

| 类型 | 说明 | 主要字段 |
|------|------|---------|
| `deploy_start` | 部署开始 | execution_id, script_name, server, command |
| `deploy_output` | 标准输出 | execution_id, line, timestamp |
| `deploy_stderr` | 错误输出 | execution_id, line, timestamp |
| `deploy_answer_sent` | 自动应答已发送 | execution_id, trigger, answer, order |
| `deploy_complete` | 部署完成 | execution_id, status, exit_code, duration |
| `deploy_error` | 执行错误 | execution_id, error_message |

---

## 三、非功能需求

| 类别 | 需求 |
|------|------|
| 安全 | 服务器密码加密存储（Fernet 加密）；敏感应答在日志/接口中隐藏 |
| 性能 | 日志流式推送，不阻塞其他请求；部署执行在独立线程运行 |
| 可靠性 | SSH 断连、脚本超时、非零退出码均能正确标记失败状态 |
| 兼容性 | 支持密码/私钥两种 SSH 认证；支持 SQLite/MySQL 数据库 |
| 可追溯 | 执行记录含脚本/服务器快照，删除脚本/服务器不影响历史记录 |

## 四、约束与依赖

1. **SSH 库**：paramiko（需新增依赖，现有 `deploy_to_560.py` 已使用同款）
2. **执行模型**：长耗时任务沿用 `execution_service.py` 的专用 `threading.Thread` + `loop.run_in_executor` 模式（Windows 平台避免 asyncio 死锁）
3. **实时推送**：复用现有 WebSocket `ConnectionManager`（按 execution_id 分组广播）
4. **前端约束**：axios `baseURL` 留空、`useRoute()` 在 setup 顶层调用（遵守项目踩坑记录）