From 4c4d41b8f5218a89dc4dd7fcbfd97bcc8857b8a9 Mon Sep 17 00:00:00 2001 From: Your Name Date: Sat, 30 May 2026 20:10:28 +0800 Subject: [PATCH] docs: add changelog and audit for ruff cleanup Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/audit/2026-05-30-ruff-cleanup.md | 77 +++++++++++++++++++++++ docs/changelog/2026-05-30-ruff-cleanup.md | 65 +++++++++++++++++++ 2 files changed, 142 insertions(+) create mode 100644 docs/audit/2026-05-30-ruff-cleanup.md create mode 100644 docs/changelog/2026-05-30-ruff-cleanup.md diff --git a/docs/audit/2026-05-30-ruff-cleanup.md b/docs/audit/2026-05-30-ruff-cleanup.md new file mode 100644 index 00000000..7fdcc2e1 --- /dev/null +++ b/docs/audit/2026-05-30-ruff-cleanup.md @@ -0,0 +1,77 @@ +# 审计报告 — 全站 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 + +- [x] ruff check: All checks passed (77 → 0) +- [x] bandit: 0 HIGH, 15 MEDIUM (低风险 B108+B104) +- [x] import server.main: 成功 +- [x] 健康检查: ok +- [x] 无逻辑变更（除 3 个 bug 修复外） diff --git a/docs/changelog/2026-05-30-ruff-cleanup.md b/docs/changelog/2026-05-30-ruff-cleanup.md new file mode 100644 index 00000000..5c75cc60 --- /dev/null +++ b/docs/changelog/2026-05-30-ruff-cleanup.md @@ -0,0 +1,65 @@ +# 2026-05-30 — 全站 ruff 清零 + +## 日期 +2026-05-30 + +## 变更摘要 +全站 ruff 代码质量扫描从 77 个错误清零到 0，同时修复 3 个实际 bug。 + +## 动机 +全站巡检发现 server/ 目录有 77 个 ruff 错误，其中 6 个 F821（未定义变量）会导致运行时 NameError。 + +## 涉及文件（21 个） + +| 文件 | 变更类型 | 说明 | +|------|----------|------| +| server/api/install.py | bug fix | site_url 变量在定义前使用 → 移到函数开头；移除未使用 hashlib 导入 | +| server/api/sync_v2.py | bug fix | 缺少 `import os` 导致对比功能 NameError | +| server/application/services/script_jobs.py | bug fix | `${LOG}` 在 f-string 中触发 Python 变量查找 → 改为普通字符串 | +| server/api/auth.py | 质量 | 移除未使用 ip_address 变量 | +| server/api/scripts.py | 质量 | 移除未使用导入 | +| server/api/settings.py | 质量 | 5 个 B904 raise from 修复 | +| server/api/websocket.py | 质量 | S110 noqa | +| server/api/webssh.py | 质量 | 10 个 S110 noqa (SSH 清理) | +| server/application/services/auth_service.py | 质量 | S105 noqa (Redis key prefix) | +| server/application/services/sync_engine_v2.py | 质量 | 移除未使用导入 | +| server/background/heartbeat_flush.py | 质量 | 移除未使用导入 | +| server/background/schedule_runner.py | 质量 | F541 f-string 修正 | +| server/background/script_execution_flush.py | 质量 | B023 循环变量绑定修复 | +| server/background/self_monitor.py | 质量 | F541 f-string 修正 | +| server/domain/models/__init__.py | 质量 | 移除 4 个未使用导入 | +| server/domain/repositories/__init__.py | 质量 | 移除未使用 Dict 导入 | +| server/infrastructure/database/admin_repo.py | 质量 | 移除未使用 List 导入 | +| server/infrastructure/database/migrations.py | 质量 | 移除未使用导入 | +| server/infrastructure/redis/client.py | 质量 | B904 raise from | +| server/infrastructure/ssh/asyncssh_pool.py | 质量 | S110 noqa + B007 变量重命名 | +| server/infrastructure/subscription_parser.py | 质量 | S110 noqa | + +## 关键 Bug 修复 + +### 1. install.py site_url NameError +- **问题**: `site_url` 在第 472 行使用但第 499 行才定义 → 安装向导初始化数据库会崩溃 +- **修复**: 将 `site_url` 计算移到函数开头（redis_url 之后） + +### 2. sync_v2.py os 未导入 +- **问题**: 对比功能（文件 diff）使用 `os.path` 但未导入 `os` +- **修复**: 在函数内添加 `import os` + +### 3. script_jobs.py f-string 陷阱 +- **问题**: `f'echo $! > "${LOG}.pid"'` 中 `${LOG}` 被 Python 解释为变量查找 +- **修复**: 改为普通字符串 `'echo $! > "${LOG}.pid"'` + +## 是否需迁移 +否 + +## 是否需重启 +是 — 已部署 + +## 验证方式 +- ruff: ✅ All checks passed (77 → 0) +- bandit: ✅ 0 HIGH, 15 MEDIUM (B108+B104 低风险) +- import: ✅ +- 健康检查: ✅ ok + +## Commit +32feb1b