docs: add changelog and audit for ruff cleanup

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

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 修复外）

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