# 实施说明 — rsync 推送 sudo 提权

## 背景

非 root SSH 用户推送至宝塔 `www:www` 站点目录时，rsync 接收端无写权限；文件管理的 `files_elevation` 此前未作用于 rsync 推送。

## 方案

与文件管理一致：**root 不提权**；**非 root** 且 `files_elevation` 非 `off`（默认 `auto_sudo`）→ rsync 附加 `--rsync-path="sudo -n rsync"`。仅显式 `off` 禁用。

## 涉及文件

| 文件 | 变更 |
|------|------|
| `server/utils/rsync_elevation.py` | 新增 |
| `server/application/services/sync_engine_v2.py` | `_rsync_push` 提权与重试 |
| `server/api/sync_v2.py` | diagnose 写入测试 sudo 回退 |
| `server/api/servers.py` | setup-files-sudo 模板加 rsync |
| `docs/deploy/nexus-files-sudoers.example` | 加 rsync |
| `server/infrastructure/ssh/files_capability.py` | 白名单探测含 rsync |
| `tests/test_rsync_elevation.py` | 单测 |

## 目标机要求

`/etc/sudoers.d/nexus-files` 须含 `NOPASSWD: /usr/bin/rsync`（或 `/bin/rsync`）。可通过服务器页「配置 sudo」或手动安装示例文件。

## 验证

```bash
pytest tests/test_rsync_elevation.py tests/test_rsync_push_permissions.py -q
```

## 回滚

Revert 上述文件；推送恢复为仅 root SSH 可写站点目录。
