Nexus/docs/audit/2026-05-30-ruff-cleanup.md

审计报告 — 全站 ruff 清零

2026-05-30

---

Step 1: 登记

项	值
审计日期	2026-05-30
Commit	32feb1b
变更文件	21 个 server/ 下的 Python 文件
变更类型	代码质量修复 + 3 个 bug 修复

---

Step 2: 全文 Read

21 个文件全部审阅，变更主要集中在：

• 未使用导入移除（安全，不影响逻辑）
• from e/from None 添加（改善异常链可追溯性）
• # noqa: S110 注释（标记有意的静默异常）

---

Step 3: 规则扫描

H1: install.py site_url NameError

• 检查: site_url 在 settings_kv dict 中使用但未定义
• 原始代码: line 472 使用 site_url，line 499 才定义
• 修复: 将 site_url = req.site_url.rstrip("/")... 移到 line 409（redis_url 之后）
• 判定: ✅ 已修复。安装向导 Step 3 初始化数据库不再 NameError
• 依据: req.site_url 是 InitDbRequest 的字段（line 60），在函数参数中传入

H2: sync_v2.py os 未导入

• 检查: os.path.isdir() / os.walk() / os.path.join() 使用但未导入
• 修复: 在函数内添加 import os
• 判定: ✅ 已修复。文件对比功能恢复正常
• 依据: 同文件其他函数已有 import os（line 205/245/316 等），模式一致

H3: script_jobs.py f-string 陷阱

• 检查: f'echo $! > "${LOG}.pid"' 中 {LOG} 被 Python 解释为变量
• 修复: 改为普通字符串 'echo $! > "${LOG}.pid"'
• 判定: ✅ 已修复。Shell 命令生成不再 NameError
• 依据: ${LOG} 是 shell 变量引用，不是 Python f-string 表达式

H4: B904 raise from 改善

• 检查: 20 个 except 块中 raise 缺少 from e/from None
• 影响: 改善异常链可追溯性，不影响运行时行为
• 判定: ✅ 安全。仅添加 from e/from None，不改变控制流

H5: S110 noqa 注释

• 检查: 20 个 try-except-pass 是否都是有意的
• 分类: SSH 清理(15)、DDL 幂等(3)、WS 断连(1)、URL 解析(1)
• 判定: ✅ 全部有意。每个都有 # noqa: S110 注释说明原因

---

Step 4: Closure 表

编号	风险	判定	依据
H1	NameError	✅ 已修复	site_url 提前到函数开头
H2	NameError	✅ 已修复	添加 import os
H3	NameError	✅ 已修复	f-string 改普通字符串
H4	异常链	✅ 改善	from e/from None
H5	静默异常	✅ 有意	noqa 注释说明原因

---

Step 5-8: DoD

• ruff check: All checks passed (77 → 0)
• bandit: 0 HIGH, 15 MEDIUM (低风险 B108+B104)
• import server.main: 成功
• 健康检查: ok
• 无逻辑变更（除 3 个 bug 修复外）