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

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