# 全仓库 POSIX 路径审计（Windows 误用排查）

| 项 | 内容 |
|----|------|
| 日期 | 2026-06-01 |
| 范围 | 远程 SSH/SFTP/rsync 路径；Nexus 主机 Unix 路径字符串 |
| SSOT 实现 | `server/utils/posix_paths.py` |

## 问题定义

在 **Windows 开发机** 上运行 Nexus API 时，`os.path.join("/www", "foo")` 可能得到 `\www\foo`，导致远程命令、SFTP、压缩失败。  
**规则**：凡表示 Linux 远程路径或 Nexus 生产机 Unix 路径的 **字符串拼接**，必须用 `posixpath` / `posix_paths`，禁止 `os.path` 做 join/dirname/basename。

---

## 审计结果总表

| 模块 | 文件 | 状态 | 说明 |
|------|------|------|------|
| **工具** | `server/utils/posix_paths.py` | ✅ 已建 | 规范化、join、zip-slip、upload 前缀 |
| **校验** | `server/api/remote_path_validation.py` | ✅ | 复用 posix_paths |
| **SSH 写** | `server/infrastructure/ssh/asyncssh_pool.py` | ✅ | `posix_dirname` |
| **SSH 压缩** | `server/infrastructure/ssh/remote_archive.py` | ✅ 原本正确 | 已用 `posixpath` |
| **同步 API** | `server/api/sync_v2.py` | ✅ 已修 | browse/ops/读写/chmod/压缩/上传/诊断/校验 |
| **rsync 引擎** | `server/application/services/sync_engine_v2.py` | ✅ 已修 | 远程 `target_path` 规范化 |
| **服务器** | `server/api/servers.py` | ✅ 已修 | workerman `target_dir` |
| **脚本远程日志** | `server/application/services/script_service.py` | ✅ 无问题 | 仅 `shlex.quote` + 固定 `/var/log/...` |
| **前端文件** | `frontend/src/utils/remotePath.ts` | ✅ | `/` 拼接 + `\`→`/` |
| **前端页面** | `FilesPage.vue`, `FileDirectoryTree.vue`, `filePreload.ts` | ✅ | 均用 `joinRemotePath` |
| **安装** | `server/api/install.py` | ➖ 不适用 | `Path("/www/...")` 在 Linux 安装目标机执行 |
| **本机仓库** | `main.py`, `auth_jwt.py`, `settings.py` | ➖ 不适用 | `Path(__file__)` 为 Nexus 代码目录 |
| **MCP/部署** | `mcp/Nexus_server.py`, `deploy/gate_log.py` | ➖ 不适用 | 部署机本地路径 |
| **文档/审计** | `docs/build_html.py`, `audit_scan.py` | ➖ 不适用 | 仓库内 Windows/Linux 本地扫描 |
| **测试** | `tests/test_api.py` 等 | ➖ 不适用 | 测试文件定位 `.env` |

---

## 已修复端点清单（sync_v2）

| 端点 | 修复内容 |
|------|----------|
| `POST /browse` | `normalize_remote_abs_path` |
| `POST /file-ops` | path / new_path 规范化 |
| `POST /file-clipboard` | 已有 `assert_clipboard_transfer_safe` |
| `POST /browse-local` 等 | `ensure_under_nexus_upload` + `posix_join` |
| `POST /validate-source-path` | `resolve_nexus_host_path` + `posix_join` walk |
| `POST /diagnose` | `normalize_remote_dest` + `remote_join` 测试文件 |
| `POST /file-diff` | upload 前缀 + `remote_join` 远程路径 |
| `POST /upload` | `remote_join` |
| `POST /upload-zip` | `assert_zip_member_safe` + `posixpath.relpath` |
| `POST /verify` | 远程 `dest` 规范化 |
| `POST /download` `read-file` `write-file` | 远程 path 规范化 |
| `POST /chmod` `compress` `decompress` | 远程 path 规范化 |

---

## 仍使用 `os.path` 的合法位置

| 位置 | 原因 |
|------|------|
| `posix_paths.resolve_nexus_host_path` | 真实访问 Nexus 主机文件系统 |
| `sync_v2` 中 `os.path.isdir/exists/walk` | 同上（生产为 Linux） |
| `sync_engine_v2` `os.path.isdir(source_path)` | Nexus 本机推送源目录 |
| `mcp/`, `tests/`, `deploy/` | 工具链本地路径，非远程 |

---

## 测试

```bash
pytest tests/test_posix_paths.py tests/test_remote_path_validation.py -q
ruff check server/utils/posix_paths.py server/api/sync_v2.py server/application/services/sync_engine_v2.py
```

---

## DoD

- [x] 全 `server/**/*.py` 检索 `os.path.(join|dirname|basename|normpath|realpath)`
- [x] 远程相关调用点已归类并修复或标注豁免
- [x] 前端远程路径统一 `remotePath.ts`
- [x] 单元测试覆盖反斜杠拒绝与 join
- [ ] 生产部署后文件管理器在 Windows 开发 + Linux 目标机上回归（人工）