# 2026-06-08 — 批量安装 Agent 已安装且版本足够则跳过

## 摘要

批量/单机「安装 Agent」时：若子机已安装且 Agent 版本 **不低于** 主站 `web/agent/agent.py` 中的版本，则跳过 SSH 安装；仅当未安装或版本更低时才执行 `install.sh`。

## 动机

批量勾选已部署 Agent 的服务器会重复跑完整安装脚本，耗时长且可能短暂中断 Agent。

## 涉及文件

- `server/utils/agent_version.py` — 主站版本 SSOT + 版本比较
- `server/application/server_batch_common.py` — `agent_install_skip_result`、Redis/SSH 版本探测
- `server/application/services/server_batch_service.py` — `_run_install_agent` 跳过逻辑
- `server/api/servers.py` — 单机 `install-agent` 对齐
- `tests/test_agent_version.py`

## 迁移 / 重启

- 无 DB 变更；需重启 API

## 行为

| 子机状态 | 动作 |
|----------|------|
| 无 agent_api_key 且无 agent_version | 执行安装 |
| 已安装，版本 ≥ 主站 | 跳过（success，stdout 说明） |
| 已安装，版本 < 主站 | 执行安装（等同升级） |

版本来源优先级：Redis `heartbeat:{id}` → MySQL `agent_version` → SSH 读取 `/opt/nexus-agent/agent.py`。

## 验证

```bash
pytest tests/test_agent_version.py -q
bash scripts/local_verify.sh
```