Nexus/docs/design/specs/2026-06-08-servers-live-sort-design.md

服务器列表实时字段排序设计

日期: 2026-06-08

背景

GET /api/servers/ 在 MySQL 层 ORDER BY 后分页，再用 Redis heartbeat 覆盖 is_online、last_heartbeat、agent_version、status。展示值与排序键不一致，导致状态/心跳/Agent 列排序无效。

目标

对 sort_by ∈ {status, heartbeat, agent_version}：overlay 全量筛选结果后内存排序，再分页返回。

方案

1. server_repo.get_filtered() 拉取筛选后全量（上限 5000）
2. Redis pipeline 批量 HGETALL heartbeat:{id}
3. server_list_sort.sort_server_items() 按 UI 语义排序
4. slice[offset:offset+per_page]

静态列（name/domain/category/target_path/id）仍 DB 排序。

排序语义

字段	键
status	online(0) → offline(1) → unknown(2)，tiebreaker name
heartbeat	ISO 时间；缺失置后（升序/降序均置后）
agent_version	字符串；空置后

性能

≤5000 台 × 一次 pipeline + 内存 sort；运维列表低频可接受。

验收

见 docs/changelog/2026-06-08-servers-live-sort-fix.md