# 推送页 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` 通过
