Nexus/docs/audit/2026-06-01-posix-path-full-audit.md

全仓库 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/	工具链本地路径，非远程

---

测试

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

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