Your Name
84 lines
4.0 KiB
Markdown
84 lines
4.0 KiB
Markdown
# 全仓库 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 目标机上回归（人工）
|