ZingerLittleBee · ZingerLittleBee · Apr 16, 2026 · Apr 16, 2026 · Apr 16, 2026 · Apr 16, 2026
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/apps/docs/content/docs/cn/api-reference.mdx b/apps/docs/content/docs/cn/api-reference.mdx
@@ -80,6 +80,9 @@ API Key 格式为 `serverbee_` 前缀 + 43 字符随机字符串，创建时仅
 | POST/PUT/DELETE | `/api/servers/*` | 服务器管理 |
 | PUT | `/api/servers/batch-capabilities` | 批量更新功能开关 |
 | POST | `/api/servers/{id}/upgrade` | 触发 Agent 升级 |
+| GET | `/api/servers/{target_id}/recovery-candidates` | 列出推荐的恢复候选项 |
+| GET | `/api/servers/recovery-jobs/{job_id}` | 获取恢复任务详情 |
+| POST | `/api/servers/{target_id}/recover-merge` | 启动 Agent 恢复任务 |
 | CRUD | `/api/server-groups/*` | 服务器分组管理 |
 | CRUD | `/api/notifications/*` | 通知渠道管理 |
 | CRUD | `/api/notification-groups/*` | 通知组管理 |

diff --git a/apps/docs/content/docs/cn/server.mdx b/apps/docs/content/docs/cn/server.mdx
@@ -218,6 +218,19 @@ Auto Discovery Key 用于 Agent 首次自动注册，优先级如下：
 
 为减少重复的占位服务器，Agent 在可读取稳定机器标识时会携带指纹，相同机器重复注册会复用原有服务器记录。你还可以通过 `auth.max_servers` 软限制自动注册创建的新服务器数量；如果历史失败注册留下了离线占位条目，可在 `/servers` 页面使用 **Clean up unconnected** 清理。
 
+## 恢复重装后的 Agent
+
+如果一台已有服务器重装系统后重新注册成了一条新的临时在线节点，可以在原来的离线服务器详情页里发起恢复：
+
+1. 打开原来的离线服务器
+2. 点击 **恢复 Agent**
+3. 选择推荐的在线替代节点
+4. 启动恢复任务
+
+恢复会保留原始服务器记录，并要求替代 Agent 重新绑定到原来的服务器身份，后续恢复流程会继续在这个基础上执行。
+
+这个恢复流程用于“同一台逻辑机器重装后重新接回”。它不适用于任意两条服务器记录的合并，也不适用于迁移到完全不同的硬件主机。
+
 ## OAuth 设置
 
 ServerBee 支持通过 OAuth 第三方登录，目前支持以下提供商：

diff --git a/apps/docs/content/docs/en/api-reference.mdx b/apps/docs/content/docs/en/api-reference.mdx
@@ -80,6 +80,9 @@ API keys use the format `serverbee_` prefix + 43-character random string. The ke
 | POST/PUT/DELETE | `/api/servers/*` | Server management |
 | PUT | `/api/servers/batch-capabilities` | Batch update capabilities |
 | POST | `/api/servers/{id}/upgrade` | Trigger agent upgrade |
+| GET | `/api/servers/{target_id}/recovery-candidates` | List recommended recovery candidates |
+| GET | `/api/servers/recovery-jobs/{job_id}` | Get recovery job details |
+| POST | `/api/servers/{target_id}/recover-merge` | Start an agent recovery job |
 | CRUD | `/api/server-groups/*` | Server group management |
 | CRUD | `/api/notifications/*` | Notification channel management |
 | CRUD | `/api/notification-groups/*` | Notification group management |

diff --git a/apps/docs/content/docs/en/server.mdx b/apps/docs/content/docs/en/server.mdx
@@ -178,6 +178,19 @@ The full key is printed to the logs on first startup and can also be viewed or r
 
 To reduce duplicate placeholder servers, agents reuse the existing server row when they re-register with the same machine fingerprint. You can also set `auth.max_servers` to soft-cap new auto-registered servers, and use **Clean up unconnected** on the Servers page to remove offline placeholders that never finished initialization.
 
+## Recovering a Reinstalled Agent
+
+If an existing server was reinstalled and then re-registered as a new temporary online node, you can recover it from the original offline server detail page:
+
+1. Open the original offline server.
+2. Click **Recover Agent**.
+3. Choose the recommended online replacement candidate.
+4. Start the recovery job.
+
+The original server record is kept. The replacement agent is asked to rebind onto the original server identity, and the recovery flow continues from there.
+
+Recovery is designed for reinstalling the same logical machine. It is not intended for arbitrary record merges or hardware migrations to a different host.
+
 ## GeoIP Setup
 
 To enable geographic location detection for your agents: