Nexus/docs/changelog/2026-05-30-servers-iteration.md

2026-05-30 — 服务器列表迭代

日期

2026-05-30

变更摘要

服务器列表页面全面迭代：后端新增服务端分页/搜索/排序/状态筛选，前端完全重写支持新功能。

动机

原服务器列表一次性加载全部数据，2000+ 服务器场景下性能差且无搜索/排序能力。

涉及文件

文件	变更类型	说明
server/infrastructure/database/server_repo.py	修改	get_paginated() 新增 search/sort_by/sort_order/is_online 参数，白名单排序，DB 级分页
server/api/servers.py	修改	list_servers() 新增 4 个 Query 参数 + Redis post-filter；修复 12 个预存 ruff 错误；修复 agent_port F821 bug
web/app/servers.html	重写	服务端分页/搜索/排序/状态筛选/自动刷新/键盘快捷键/CSV 导出/骨架屏/空状态优化

变更详情

后端 — server_repo.py

• get_paginated() 签名扩展：新增 search（name/domain LIKE）、sort_by（白名单验证）、sort_order（asc/desc）、is_online（MySQL 预过滤）
• _SORT_COLUMNS 白名单：id/name/domain/status/heartbeat/agent_version/category
• is_online 过滤时 over-fetch +10 补偿 Redis overlay 修正

后端 — servers.py

• list_servers() 新增 Query 参数：search/sort_by/sort_order/is_online
• Redis post-filter：is_online 过滤时移除 Redis 状态不匹配的记录
• 修复 12 个预先存在的 ruff 错误：F401 unused imports、B904 raise from、S110 try-except-pass、F541 f-string
• 修复 F821 bug：upgrade_agent() 中 agent_port 变量未定义

前端 — servers.html

• 服务端分页：50/100/200 条/页，首页/上一页/数字页码/下一页/末页
• 防抖搜索（300ms）：名称/地址 LIKE 模糊搜索
• 可点击列排序：Agent 状态/名称/地址/分类/Agent/最后心跳，▲▼ 指示器
• 状态筛选下拉：全部/在线/离线
• 自动刷新：30 秒间隔，弹窗编辑时自动暂停
• 键盘快捷键：↑↓/jk 移动、Esc 关闭面板、/ 搜索、r 刷新
• CSV 导出：当前筛选条件下导出最多 5000 条
• 骨架屏加载：8 行脉冲动画替代"加载中..."
• 空状态优化：区分"无数据"和"无匹配结果"

是否需迁移

否

是否需重启

是 — supervisorctl restart nexus

验证方式

1. ruff check: ✅ All checks passed
2. bandit: ✅ No issues
3. import: ✅ 成功
4. Playwright 浏览器验证：✅ 搜索/排序/筛选/分页全部通过

Commit

84282e8