# 设计 — 新服务器接入自动化

## 背景

非 root 子机推送需目标机 `nexus-files` sudoers；未设 `target_path` 时推送回退 `/www/wwwroot`。此前需人工「一键配置 sudo」+「检测目标路径」。

## 目标

创建/导入/凭据轮询添加服务器成功后，**后台自动**：

1. 非 root：安装/补全 `nexus-files` sudoers（含 rsync）
2. `target_path` 仍为「未设路径」：SSH 探测 workerman.bat 并写入站点目录

## 方案

新增批量操作 `onboard`，复用现有 `server_batch_service` 后台任务 + WebSocket 进度。

| 入口 | 触发 |
|------|------|
| POST `/servers/` | 单台 → job |
| CSV import | 批量 created_ids → 一个 job |
| 凭据轮询 / add-by-ip / pending retry | `_create_server_from_poll` 内触发 |

root SSH：跳过 sudo 步骤；已有具体 `target_path`：跳过探测。

## 非目标

- 不自动安装 Agent
- 不因 onboarding 失败阻断创建 API（仅记录 batch job 失败项）

## 验收

- 新建 ubuntu 服务器 → 返回 `onboarding_job_id`，任务含 sudo + detect
- pytest 覆盖 onboard 编排逻辑