admin/Nexus
1
0
Fork 0
Code Issues Pull Requests Actions 82 Packages Projects Releases Wiki Activity

fix: 系统全扫描修复 7 个 HIGH 级 Bug

Browse Source 
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Your Name
2026-06-02 01:22:00 +08:00
parent ea3046f635
commit 19cfb7caaa
8 changed files with 195 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/changelog/2026-06-02-system-bug-fix-7-high.md
+101
View File
@@ -0,0 +1,101 @@
# 2026-06-02 全系统 Bug 扫描与修复
## 日期
2026-06-02
## 变更摘要
对全系统进行静态代码扫描，发现并修复 **7 个 HIGH 级 Bug**。
---
## HIGH-1: `download_file` SSH 连接在流传输前被过早释放
**文件**: `server/api/sync_v2.py`
**问题**: `finally` 块中 `ssh_pool.release()` 在 `StreamingResponse` 生成器尚未开始执行时就关闭连接，导致文件下载中断。
**修复**: 将 `release()` 移入 `file_generator()` 的 `finally` 子句，在流传输完成或客户端断开后再释放；提前退出（404/400/413）在各自分支 `await release()`。
---
## HIGH-2: WebSocket JWT `tv` 默认值 `-1` 与 HTTP 中间件 `0` 不一致
**文件**: `server/api/websocket.py`
**问题**: `_verify_ws_token` 对无 `tv` 字段的旧 token 使用默认值 `-1`，而数据库 `token_version` 为 `NULL/0`，导致 `-1 != 0` 判断失败，合法用户 WebSocket 连接被拒。
**修复**: 对齐 HTTP 中间件逻辑，改为 `payload.get("tv") or 0`，DB 侧 `admin.token_version or 0`。
---
## HIGH-3: `retry_runner` 达到 `max_retries` 后任务永久僵尸
**文件**: `server/background/retry_runner.py`
**问题**: 重试次数达到 `max_retries` 时，任务状态仍维持 `pending` 且 `retry_count < max_retries` 条件不再触发，形成永不被处理的僵尸记录。
**修复**: 成功/失败分支均检查 `retry_count >= max_retries`，达到上限时将 `status` 置为 `failed`，记录原因日志。
---
## HIGH-4: `sync_v2.py` 和 `sync_engine_v2.py` 多处 `stderr` 为 `None` 引发 `TypeError`
**文件**: `server/api/sync_v2.py`, `server/application/services/sync_engine_v2.py`
**问题**: 多处直接执行 `result["stderr"][:N]`，当 SSH 执行结果中 `stderr` 为 `None` 时（如连接超时）抛 `TypeError: 'NoneType' object is not subscriptable`，导致 API 返回 500。
**修复**: 所有 `result["stderr"][:N]` 统一改为 `(result.get("stderr") or "")[:N]`，共修复 5 处。
---
## HIGH-5: `auth_service._verify_password` bcrypt 抛 `ValueError` 导致 500
**文件**: `server/application/services/auth_service.py`
**问题**: DB 中若存在格式异常的 `password_hash`，`bcrypt.checkpw` 会抛 `ValueError`，导致登录接口 500 而非 401。
**修复**: 用 `try/except` 包裹 `bcrypt.checkpw`，异常时返回 `False`（密码不匹配）。
---
## HIGH-6: `install.py /lock` 硬编码查询 `"admin"` 用户名
**文件**: `server/api/install.py`
**问题**: `/lock` 端点通过 `get_by_username("admin")` 验证管理员是否创建，若用户在步骤 4 使用了非 `admin` 的用户名（如 `administrator`），会错误地拒绝锁定（状态 400），且 DB 不可达时会静默放行锁定操作。
**修复**: 改为 `SELECT COUNT(*) FROM admins WHERE is_active = 1` 验证活跃管理员存在；DB 不可达时改为拒绝锁定（503）而非放行。
---
## HIGH-7: `heartbeat_flush.py` 单条失败污染整批事务
**文件**: `server/background/heartbeat_flush.py`
**问题**: 所有服务器在同一 `AsyncSession` 中批量更新，单条 `UPDATE` 失败时仅打日志，但会话处于需要 rollback 的状态，最终 `commit()` 使整批失败，日志显示 "N 台更新" 实际全部失败。同时修复 `datetime` 时区感知问题（naive datetime 写入 MySQL）。
**修复**: 每台服务器使用独立的 `AsyncSessionLocal()` 上下文，单条失败不影响其他；`fromisoformat` 后统一补 `tzinfo=timezone.utc`。
---
## 涉及文件
| 文件 | 修复项 |
|------|-------|
| `server/api/sync_v2.py` | HIGH-1（下载连接）、HIGH-4（stderr None, 3 处） |
| `server/api/websocket.py` | HIGH-2（WebSocket tv） |
| `server/api/install.py` | HIGH-6（/lock 用户名） |
| `server/application/services/auth_service.py` | HIGH-5（bcrypt ValueError） |
| `server/application/services/sync_engine_v2.py` | HIGH-4（stderr None, 2 处） |
| `server/background/retry_runner.py` | HIGH-3（僵尸任务） |
| `server/background/heartbeat_flush.py` | HIGH-7（事务污染、时区） |
## 需要迁移/重启
- 后端重启生效（`supervisorctl restart nexus`）
- 无数据库 migration 变更
## 验证方式
1. `python -c "import server.main"` — 导入无报错 ✓
2. 登录测试 WebSocket 实时推送
3. 下载文件功能测试
4. 查看 `push_retry_jobs` 表确认无 `status=pending` 的僵尸记录
server/api/install.py
+10 -7
View File
@@ -636,23 +636,26 @@ async def lock_install():
"""
_reject_if_installed()
# Verify admin account exists before allowing lock
# Verify at least one active admin account exists before allowing lock
try:
from server.infrastructure.database.session import AsyncSessionLocal
from server.infrastructure.database.admin_repo import AdminRepositoryImpl
from sqlalchemy import text as _text
async with AsyncSessionLocal() as session:
repo = AdminRepositoryImpl(session)
admin = await repo.get_by_username("admin")
if not admin:
result = await session.execute(
_text("SELECT COUNT(*) FROM admins WHERE is_active = 1")
)
count = result.scalar() or 0
if count == 0:
raise HTTPException(
status_code=400,
detail="无法锁定：管理员账户尚未创建。请先完成安装步骤4。",
detail="无法锁定：尚无活跃管理员账户。请先完成安装步骤4。",
)
except HTTPException:
raise
except Exception as e:
logger.warning("Failed to verify admin account before locking: %s", e)
# If DB is unreachable, allow lock (admin may have been created but DB is temporarily down)
# If DB is temporarily unreachable, conservatively reject lock
raise HTTPException(status_code=503, detail="数据库暂时不可用，无法验证管理员账户，请稍后重试。")
# Create lock marker file
INSTALL_LOCK.write_text(
server/api/sync_v2.py
+28 -10
View File
@@ -268,21 +268,25 @@ async def browse_directory(
raise HTTPException(status_code=400, detail=str(exc)) from exc
import shlex
from server.infrastructure.ssh.remote_shell import exec_ssh_command_with_fallback
from server.utils.unix_ls import parse_ls_la_line, perms_to_mode_octal
path_q = shlex.quote(path)
result = await exec_ssh_command(
# 与写文件/chmod 一致：非 root SSH 在 Permission denied 时按 files_elevation 尝试 sudo -n
result = await exec_ssh_command_with_fallback(
server,
f"ls -la --time-style=long-iso {path_q}",
timeout=10,
)
if result["exit_code"] != 0:
result = await exec_ssh_command(server, f"ls -la {path_q}", timeout=10)
result = await exec_ssh_command_with_fallback(
server, f"ls -la {path_q}", timeout=10
)
await _audit_sync("browse_directory", "server", server_id, f"Browse {server.name}:{path}", admin.username, request)
if result["exit_code"] != 0:
return {"path": path, "items": [], "error": result["stderr"][:500]}
return {"path": path, "items": [], "error": (result.get("stderr") or "")[:500]}
raw_entries = []
for line in result["stdout"].split("\n"):
@@ -644,7 +648,7 @@ async def diagnose_push(
if r["exit_code"] == 0 and "ok" in r["stdout"]:
result["ssh_ok"] = True
else:
result["errors"].append(f"SSH 连接异常: {r['stderr'][:200] or 'exit code ' + str(r['exit_code'])}")
result["errors"].append(f"SSH 连接异常: {(r.get('stderr') or '')[:200] or 'exit code ' + str(r['exit_code'])}")
# Cannot continue if SSH fails
await _audit_sync("diagnose", "server", payload.server_id, "诊断: SSH不通", admin.username, request)
return result
@@ -696,7 +700,7 @@ async def diagnose_push(
)
result["path_writable"] = r["exit_code"] == 0
if r["exit_code"] != 0:
result["errors"].append(f"目标路径不可写: {r['stderr'][:200]}")
result["errors"].append(f"目标路径不可写: {(r.get('stderr') or '')[:200]}")
except Exception as e:
result["errors"].append(f"写入测试失败: {e}")
result["path_writable"] = False
@@ -1233,22 +1237,29 @@ async def download_file(
raise HTTPException(status_code=400, detail=str(exc)) from exc
conn = await ssh_pool.acquire(server)
# NOTE: connection is released INSIDE file_generator (after stream finishes),
# not in a finally block here — releasing before the generator runs would close
# the SFTP channel mid-download.
try:
async with sftp_session(conn) as sftp:
# Check file exists and size
try:
stat = await sftp.stat(remote_path)
except FileNotFoundError:
await ssh_pool.release(server.id)
raise HTTPException(status_code=404, detail="文件不存在") from None
except Exception as e:
await ssh_pool.release(server.id)
raise HTTPException(status_code=502, detail=f"无法访问文件: {e}") from e
if stat.type not in ("regular file", "unknown"):
await ssh_pool.release(server.id)
raise HTTPException(status_code=400, detail="只能下载文件，不能下载目录")
# H-15: Download file size limit (100MB)
MAX_DOWNLOAD_SIZE = 100 * 1024 * 1024
if hasattr(stat, "size") and stat.size and stat.size > MAX_DOWNLOAD_SIZE:
await ssh_pool.release(server.id)
raise HTTPException(status_code=413, detail=f"文件大小 {stat.size} 字节超过下载限制 100MB")
# H-02: Sanitize filename for Content-Disposition (RFC 6266)
@@ -1256,9 +1267,13 @@ async def download_file(
filename = _re.sub(r'[^\w.\-]', '_', posix_basename(remote_path)) or "download"
async def file_generator():
async with sftp.open(remote_path, "rb") as f:
while chunk := await f.read(65536):
yield chunk
try:
async with sftp.open(remote_path, "rb") as f:
while chunk := await f.read(65536):
yield chunk
finally:
# Release after stream is fully consumed (or on client disconnect)
await ssh_pool.release(server.id)
await _audit_sync(
"file_download", "server", payload.server_id,
@@ -1271,8 +1286,11 @@ async def download_file(
media_type="application/octet-stream",
headers={"Content-Disposition": f'attachment; filename="{filename}"'},
)
finally:
except HTTPException:
raise
except Exception as e:
await ssh_pool.release(server.id)
raise HTTPException(status_code=502, detail=f"下载失败: {e}") from e
@router.post("/read-file")
@@ -1555,7 +1573,7 @@ async def decompress_file(
result = await exec_ssh_command_with_fallback(server, cmd, timeout=120)
if result["exit_code"] != 0:
raise HTTPException(status_code=502, detail=f"解压失败: {result['stderr'][:300]}")
raise HTTPException(status_code=502, detail=f"解压失败: {(result.get('stderr') or '')[:300]}")
await _audit_sync(
"file_decompress", "server", payload.server_id,
server/api/websocket.py
+3 -2
View File
@@ -336,8 +336,9 @@ async def _verify_ws_token(token: str):
return None
# Primary: token_version must match (immediate invalidation on password change)
token_tv = payload.get("tv", -1)
if token_tv != admin.token_version:
token_tv = payload.get("tv") or 0
admin_tv = admin.token_version or 0
if token_tv != admin_tv:
return None
# Secondary: updated_at timestamp (defense in depth)
server/application/services/auth_service.py
+4 -1
View File
@@ -481,7 +481,10 @@ class AuthService:
def _verify_password(self, password: str, password_hash: str) -> bool:
"""Verify password against stored bcrypt hash"""
return bcrypt.checkpw(password.encode(), password_hash.encode())
try:
return bcrypt.checkpw(password.encode(), password_hash.encode())
except (ValueError, Exception):
return False
@staticmethod
def _verify_totp(code: str, secret: str) -> bool:
server/application/services/sync_engine_v2.py
+2 -2
View File
@@ -149,7 +149,7 @@ class SyncEngineV2:
sync_log.duration_seconds = int(
(sync_log.finished_at - sync_log.started_at).total_seconds()
) if sync_log.started_at else 0
sync_log.error_message = result["stderr"][:1000] if result["exit_code"] != 0 else None
sync_log.error_message = (result.get("stderr") or "")[:1000] if result["exit_code"] != 0 else None
sync_log.diff_summary = result["stdout"][:2000] if result["exit_code"] == 0 else None
sync_log = await self.sync_log_repo.update(sync_log)
@@ -274,7 +274,7 @@ class SyncEngineV2:
return {
"server_id": server_id,
"server_name": server.name,
"error": result["stderr"][:500] or f"rsync exited with code {result['exit_code']}",
"error": (result.get("stderr") or "")[:500] or f"rsync exited with code {result['exit_code']}",
"exit_code": result["exit_code"],
}
server/background/heartbeat_flush.py
+37 -38
View File
@@ -53,45 +53,44 @@ async def heartbeat_flush_loop():
continue
flushed = 0
try:
async with AsyncSessionLocal() as session:
for key in keys:
skipped = 0
for key in keys:
try:
async with AsyncSessionLocal() as session:
server_id = int(key.replace(REDIS_KEY_PREFIX, ""))
data = await redis.hgetall(key)
if not data:
continue
is_online = data.get("is_online") == "True"
system_info = data.get("system_info", "{}")
agent_version = data.get("agent_version", "")
# Parse last_heartbeat — ensure timezone-aware
last_hb_str = data.get("last_heartbeat", "")
try:
server_id = int(key.replace(REDIS_KEY_PREFIX, ""))
data = await redis.hgetall(key)
last_heartbeat = datetime.fromisoformat(last_hb_str)
if last_heartbeat.tzinfo is None:
last_heartbeat = last_heartbeat.replace(tzinfo=timezone.utc)
except (ValueError, TypeError):
last_heartbeat = datetime.now(timezone.utc)
if not data:
continue
is_online = data.get("is_online") == "True"
system_info = data.get("system_info", "{}")
agent_version = data.get("agent_version", "")
# Parse last_heartbeat
last_hb_str = data.get("last_heartbeat", "")
try:
last_heartbeat = datetime.fromisoformat(last_hb_str)
except (ValueError, TypeError):
last_heartbeat = datetime.now(timezone.utc)
await session.execute(
update(Server)
.where(Server.id == server_id)
.values(
is_online=is_online,
system_info=system_info,
last_heartbeat=last_heartbeat,
agent_version=agent_version,
)
await session.execute(
update(Server)
.where(Server.id == server_id)
.values(
is_online=is_online,
system_info=system_info,
last_heartbeat=last_heartbeat,
agent_version=agent_version,
)
flushed += 1
except Exception as e:
logger.warning(f"Failed to flush server {key}: {e}")
# Don't rollback here — just skip this server and continue.
# A partial UPDATE on a single server won't corrupt others.
# The final commit() will persist all successful updates.
)
await session.commit()
flushed += 1
except Exception as e:
logger.warning(f"Failed to flush server {key}: {e}")
skipped += 1
await session.commit()
logger.info(f"Heartbeat flush: {flushed}/{len(keys)} servers updated to MySQL")
except Exception as e:
logger.error(f"Heartbeat flush batch failed: {e}")
logger.info(f"Heartbeat flush: {flushed}/{len(keys)} servers updated to MySQL" +
(f", {skipped} failed" if skipped else ""))
server/background/retry_runner.py
+10 -2
View File
@@ -67,6 +67,10 @@ async def retry_runner_loop():
if sync_result["failed"] == 0:
job.status = "completed"
logger.info(f"Retry job {job.id}: success after {job.retry_count} attempts")
elif job.retry_count >= job.max_retries:
job.status = "failed"
job.last_error = f"Retry exhausted after {job.retry_count} attempts"
logger.warning(f"Retry job {job.id}: max retries reached, marking failed")
else:
# Still failing — schedule next retry with backoff
backoff = RETRY_BACKOFF_BASE * (2 ** min(job.retry_count - 1, 6))
@@ -83,9 +87,13 @@ async def retry_runner_loop():
except Exception as e:
logger.error(f"Retry job {job.id} execution error: {e}")
job.retry_count += 1
backoff = RETRY_BACKOFF_BASE * (2 ** min(job.retry_count - 1, 6))
job.next_retry_at = now + timedelta(seconds=backoff)
job.last_error = str(e)[:500]
if job.retry_count >= job.max_retries:
job.status = "failed"
logger.warning(f"Retry job {job.id}: max retries reached (exception), marking failed")
else:
backoff = RETRY_BACKOFF_BASE * (2 ** min(job.retry_count - 1, 6))
job.next_retry_at = now + timedelta(seconds=backoff)
await session.commit()
if retried: