Your Name
5958c21048
5 项新功能: - H2: 服务器搜索过滤 — 目标服务器下拉加搜索框实时过滤 - H3: 推送对比 Diff 视图 — 预览文件列表加 diff 按钮对比本地与远程差异 - H4: 推送排错面板 — 失败行加诊断按钮检查SSH/磁盘/权限 - H5: 源路径直接输入 — 支持直接输入服务器本地路径推送 - H6: 批量重试 — 一键重试所有失败服务器 新增后端端点: - POST /api/sync/validate-source-path (H5) - POST /api/sync/diagnose (H4) - POST /api/sync/file-diff (H3) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
4.4 KiB
4.4 KiB
2026-05-29 推送页面迭代 Round 4 — 设计文档
背景与目标
推送页面已完成 Round 1（5项）+ Round 2（5项）+ Round 3（6项）共 16 项功能。实际使用中发现以下 5 项体验/功能缺口：
- 2000+ 服务器无法快速定位 — 下拉列表滚动查找低效，缺少搜索过滤
- 推送前无法预览内容差异 — 只知道哪些文件会传输，不知道具体改了什么
- 推送失败无法快速诊断 — 失败后不知道是 SSH 不通、磁盘满、还是权限问题
- 源路径仅支持 ZIP 上传 — 服务器已有文件需先下载再上传，重复劳动
- 批量失败需逐台点重试 — 推送 50 台失败 20 台，需点 20 次重试按钮
方案对比
H2 服务器搜索过滤
| 方案 | 优点 | 缺点 |
|---|---|---|
A: <select> 上方加搜索框 + 实时过滤 |
简单直观，不改变交互模式 | 无 |
| B: 替换为自定义下拉组件（带搜索） | 更灵活 | 改动大，多选交互复杂 |
选定方案 A — 在现有 <select> 上方加 <input> 搜索框，按名称/域名实时过滤选项
H3 推送对比 Diff 视图
| 方案 | 优点 | 缺点 |
|---|---|---|
| A: 预览文件列表中，每行加"查看diff"按钮 | 按需加载，精确 | 需后端端点读远程文件 |
| B: 批量拉取所有文件diff | 一次性展示全貌 | 大量文件时性能差 |
| C: 推送完成后对比 | 有实际结果 | 不是"推送前"预览 |
选定方案 A — 预览文件列表中加"查看diff"按钮，点击后请求后端读本地+远程文件内容，前端渲染逐行 diff（新增绿/删除红/修改黄）
H4 推送排错面板
| 方案 | 优点 | 缺点 |
|---|---|---|
| A: 失败行加"🔍 诊断"按钮，弹面板显示检查结果 | 上下文内操作，体验流畅 | 需后端端点 |
| B: 失败后自动诊断 | 全自动 | 每次失败都跑诊断，浪费资源 |
选定方案 A — 失败行加"🔍 诊断"按钮，后端端点依次检查 SSH 连通 → 磁盘空间 → 目标路径权限，返回结构化结果
H5 源路径直接输入
| 方案 | 优点 | 缺点 |
|---|---|---|
| A: ZIP 上传区域旁加"或输入服务器本地路径"输入框 | 不破坏现有流程 | 无 |
| B: 两种模式切换（上传/路径） | 界面清晰 | 增加交互步骤 |
选定方案 A — 上传区域下方加一行"或输入源路径"输入框 + "验证路径"按钮，验证后替代上传路径
H6 批量重试
| 方案 | 优点 | 缺点 |
|---|---|---|
| A: 进度条区域加"重试所有失败"按钮 | 一键操作 | 无 |
| B: 勾选式批量重试 | 灵活选择 | 交互复杂 |
选定方案 A — 推送完成后，如果存在失败行，在进度条区域显示"重试全部失败（N台）"按钮
选定方案及理由
全部选方案 A（最简方案）：
- H2/H5/H6 均为纯前端或轻量前端改动
- H3/H4 需后端新端点，但复用现有 SSH 执行能力
- 改动范围最小，风险最低
接口/数据模型
H3: 新增 API 端点
POST /api/sync/file-diff—{server_id, source_path, relative_path, target_path?}→{diff_lines: [{type, content}], file_name, local_exists, remote_exists}- 新增 Schema:
FileSyncDiff
H4: 新增 API 端点
POST /api/sync/diagnose—{server_id, target_path?}→{ssh_ok, disk_info, path_exists, path_writable, errors[]}- 新增 Schema:
SyncDiagnose
H5: 新增 API 端点
POST /api/sync/validate-source-path—{path}→{valid, is_dir, file_count, size_bytes, error?}- 新增 Schema:
ValidateSourcePath
安全与性能约束
- H3: 仅允许对比
/tmp/nexus_upload_*目录下的文件（realpath 校验）；远程文件通过 SSH cat 读取，限制 100KB - H4: 诊断命令通过
shlex.quote()防注入；SSH 操作复用连接池 - H5: realpath 校验 + 不允许
/etc/root/home等敏感路径前缀；仅允许已存在目录 - H3/H4/H5 均需 JWT 认证 + 审计日志
- H2/H6 纯前端，无安全影响
验收标准
- H2: 输入搜索文字 → 服务器下拉列表实时过滤匹配项
- H3: 预览文件列表 → 点击"diff" → 弹出逐行对比视图
- H4: 推送失败 → 点击"🔍 诊断" → 弹出面板显示 SSH/磁盘/权限检查结果
- H5: 输入服务器本地路径 → 点验证 → 成功后可直接推送
- H6: 推送完成后有失败 → 显示"重试全部失败"按钮 → 点击后所有失败服务器重试