# API 巡检 B2 — sync_v2.py + files.py + remote_path_validation.py

**日期**: 2026-06-06  
**范围**: 22 个 `/api/sync/*` 端点 + `GET /api/files/browse` + 路径校验模块

## 结论

| 级别 | 数量 | 说明 |
|------|------|------|
| P0 | 0 | — |
| P1 | 0 | — |
| P2 | 1 | 已修：`SyncFiles`/`SyncVerify` `server_ids` 无上限 |
| H | 1 | `_audit_sync` 写失败仅 warning（不阻断业务） |

**批次结论**: **PASS**

---

## 覆盖摘要

| 检查项 | 结果 |
|--------|------|
| 全部 sync 端点 JWT | ✓ 22/22 `get_current_admin` |
| 远程路径 | ✓ `normalize_remote_abs_path` / `remote_join` |
| 本地 staging | ✓ `ensure_under_nexus_upload` 限制 `/tmp/nexus_upload_*` |
| Shell 拼接 | ✓ 普遍 `shlex.quote` |
| 上传限制 | ✓ 单文件 100MB；ZIP 500MB |
| 剪贴板 copy/move | ✓ `assert_clipboard_transfer_safe` 防 dest 在源子树内 |
| files GET browse | ✓ ETag + 路径规范化 + 审计 |

---

## FINDING

### P2-02 — `SyncFiles` / `SyncVerify` `server_ids` 无 max_length（已修）

- **风险**: 超大列表导致海量协程调度与 DB 查询（verify 虽 Semaphore(5) 仍会创建 N 个 task）。
- **修复**: `max_length=2000`（对齐平台子机规模上限）。
- **文件**: `server/api/schemas.py`

### H-04 — `_audit_sync` 异常时 `logger.warning` 不向上抛

- **位置**: `sync_v2.py` `_audit_sync`
- **处置**: 接受 — 审计失败不应阻断文件操作；已有 exc_info 日志。

---

## 安全亮点

- `file-ops` delete 使用 `rm -rf` 但路径经 `normalize_remote_abs_path` 校验
- `upload` 文件名剥离 `/` `\`
- `local-file-ops` rename 禁止 `..` / `.`
- `write-file` 5MB 上限 + etag 乐观锁（409）
- `read-file` 1MB 默认上限

---

**下一批**: B3 — auth + auth_jwt + dependencies