Nexus/docs/changelog/2026-05-28-push-5-features.md

2026-05-28 推送页面 5 项迭代功能

变更摘要

1. F1: 推送进度实时追踪 — WebSocket 逐台推送进度更新
2. F2: 服务器分组选择 — 分类/平台筛选 + 选中当前筛选
3. F4: 推送历史增强 — 可展开详情面板（耗时/错误/diff）
4. F7: 文件管理器操作 — 解压文件删除/重命名
5. F8: 推送后校验 — md5sum 对比本地源与远程目标

动机

推送页面已完成 ZIP 上传 + rsync 推送基础功能，但存在 5 个体验缺陷：批量推送无实时反馈、2000+ 服务器无法分组选择、历史记录无详情、文件管理器只读、推送后无法校验文件一致性。

涉及文件

后端

• server/api/websocket.py — 新增 broadcast_sync_progress() 函数
  • 参数: batch_id, server_id, server_name, status, completed, failed, total, error_message, duration_seconds
  • 通过 _dispatch_ws_message() 发布到 Redis Pub/Sub + 本地 WebSocket
• server/application/services/sync_engine_v2.py — 推送引擎改造
  • sync_files(): 新增 batch_id (uuid) 用于 WS 消息过滤
  • _sync_one(): 计数器更新后调用 broadcast_sync_progress()
  • _sync_one(): 捕获 diff_summary = result["stdout"][:2000]
  • _log_to_dict(): 新增 files_transferred, files_skipped, bytes_transferred, diff_summary
  • 返回 dict 新增 batch_id
• server/api/servers.py — 服务器列表 + 历史增强
  • list_servers(): 新增 platform_id, node_id Query 参数
  • 新增 GET /api/servers/categories 端点（分类+平台列表）
  • _sync_log_to_dict(): 新增 files_skipped, bytes_transferred, diff_summary
• server/infrastructure/database/server_repo.py — get_paginated() 增加 platform_id, node_id 参数
• server/api/schemas.py — 新增 LocalFileOperation, SyncVerify 模型
• server/api/sync_v2.py — 新增端点
  • POST /api/sync/local-file-ops: 删除/重命名上传临时目录中的文件
  • POST /api/sync/verify: md5sum 对比本地源与远程目标

前端

• web/app/push.html — 全面改造
  • F1: WebSocket 连接 connectPushWS() + updateProgressFromWS() 逐台更新
  • F2: 分类/平台筛选下拉框 + filterServers() + "选中当前筛选" 按钮
  • F4: 历史记录可点击展开详情（源/目标路径、耗时、错误、diff_summary）
  • F7: 文件管理器 hover 显示操作按钮 + deleteLocalFile()/renameLocalFile()
  • F8: "推送后校验" 复选框 + doVerify() + 校验结果面板

安全影响

• F1 (WS): WS 消息需 JWT 认证 + batch_id 过滤防混淆
• F7 (文件操作): os.path.realpath() + startswith("/tmp/nexus_upload_") 双重校验，新路径也必须在上传目录内
• F8 (校验): SSH 命令中文件名通过 shlex.quote() 防注入
• 所有新端点需 JWT 认证 + 审计日志

需要迁移/重启

• 是：后端 Python 需重启（supervisorctl restart nexus）
• 否：无数据库 schema 迁移

验证方式

1. F1: 推送 3+ 台服务器 → 观察 WS 逐台更新状态（不等全部完成）
2. F2: 分类筛选 → 选中筛选 → 服务器列表正确过滤
3. F4: 点击历史记录 → 展开详情 → 显示耗时/错误/diff
4. F7: 上传 ZIP → 文件管理器 → 删除/重命名文件 → 刷新确认
5. F8: 勾选校验 → 推送 → 校验结果正确显示匹配/缺失

进度条

☑实现 ☑WSL验证 ☐审计8步 ☐部署 ☐健康检查 ☐浏览器验证 ☐changelog