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

**日期**: 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`