Nexus/docs/design/specs/2026-06-02-push-post-b5-enhancements-design.md

推送页 B5 后增强 — 设计文档

日期: 2026-06-02
依赖: 2026-06-02-push-refactor-design.md（B0–B5 已完成）

背景

B5 完成架构拆分后，设计文档中仍有三类未闭环项：

项	问题
M2	推送进度走 /ws/alerts，与告警共用频道，多用户/多批次时客户端需过滤 batch_id
M9	失败/放弃的上传目录 /tmp/nexus_upload_* 无定期清理，仅全成功手动推送后删除
预览	B4 限制最多预览 12 台，大批量推送前信息不完整

方案

M2 — 独立 /ws/sync 频道

• 新增 WebSocket：GET /ws/sync?token=<JWT>，认证与 /ws/alerts 相同
• 新增 Redis 频道 nexus:sync；broadcast_sync_progress 仅发往该频道 + sync_manager 本地连接
• 告警/恢复/系统事件仍走 nexus:alerts，互不影响
• 前端 usePushProgress 改为连接 /ws/sync

M9 — 后台清理任务

• upload_staging_cleanup_loop：primary worker 每小时执行
• 删除 mtime 超过 24h 且路径经 realpath 校验仍在 UPLOAD_STAGING_PREFIX 下的目录
• 与 sync_engine_v2._maybe_cleanup_upload_staging（全成功即时删）互补

预览 — 全量并发预览

• 取消 12 台上限；对全部选中服务器按并发度 4 分批请求 /sync/preview
• 对话框显示进度条与 已完成/总数；超过 30 台显示耗时提示

安全与性能

• /ws/sync 仍须 JWT；/ws/ 已在 HTTP 中间件 public 列表（与 alerts 一致）
• 预览并发固定为 4，避免打满 SSH/rsync
• 清理任务仅删本机 /tmp/nexus_upload_*，realpath 防路径逃逸

验收标准

• 推送页 WS 连接 /ws/sync，进度与取消正常
• Dashboard 告警 WS 仍连 /ws/alerts，不受推送流量干扰
• 多机（>12）预览表格逐行填充，进度条正确
• 超过 24h 的 staging 目录在清理周期后被删除
• pytest tests/test_sync_websocket.py tests/test_upload_staging_cleanup.py 通过