Skip to content

MIGRATION_GUIDE.md

Latest commit

 

History

History
194 lines (137 loc) · 4.82 KB

MIGRATION_GUIDE.md

File metadata and controls

194 lines (137 loc) · 4.82 KB
Raw

DeepVuln 模块化重构迁移指南

概述

本文档描述了如何将 DeepVuln 从基于 CLI 子进程的扫描架构迁移到基于协程的模块化架构，参考 DeepAudit 的设计。

架构对比

当前架构 (CLI + Celery)

Web API → Celery Worker → subprocess → CLI扫描 → JSONL → 解析 → DB
        (独立进程)     (新进程)    (python -m)    (IPC)   (写DB)

问题：

  • 进程启动开销：每次扫描 ~1-2 秒
  • 内存占用：4 个独立 Python 进程
  • IPC 开销：JSONL 序列化/反序列化
  • 调试困难：多进程通信复杂

新架构 (协程 + BackgroundTasks)

Web API → BackgroundTasks → ScanOrchestrator → Phases → Engines → DB
        (协程池)          (内存编排)      (并行)      (直接写)

优势：

  • 快速启动：协程切换 ~10ms
  • 内存共享：单进程多协程
  • 无 IPC：直接函数调用
  • 易调试：同步调用栈

新目录结构

src/web/services/scan/
├── __init__.py              # 模块导出
├── context.py                # 扫描上下文 (ScanContext, ScanConfig)
├── orchestrator.py           # 扫描编排器 (核心)
├── background.py             # 后台任务管理
├── phases/                   # 扫描阶段
│   ├── __init__.py
│   ├── base.py              # 阶段基类
│   ├── preparation.py       # L1: 准备阶段
│   ├── engines.py           # L2/L3: 引擎扫描
│   └── verification.py      # L4: 验证阶段
└── events/                   # 事件系统
    ├── __init__.py
    ├── emitter.py           # 事件发射器
    └── db_handler.py        # 数据库事件处理器

迁移步骤

阶段 1: 安装新模块 (无破坏性)

新模块与现有代码共存，可以逐步迁移：

# 新模块已创建在 src/web/services/scan/
# 现有代码继续使用 Celery

阶段 2: 更新 API 端点

使用新的 API 端点进行测试：

# src/web/main.py

from src.web.api.v1 import scans_v2  # 新 API

app.include_router(scans_v2.router, prefix="/api/v1", tags=["scans-v2"])
# 使用新端点启动扫描
POST /api/v1/scans/{scan_id}/start-v2

# 或使用便捷端点
POST /api/v1/scans/quick-scan?project_id=7&scan_type=base

阶段 3: 配置并发控制

# src/web/core/config.py

class ScanSettings(BaseSettings):
    """Scan service configuration."""
    max_concurrent_scans: int = 3
    enable_llm_verify: bool = False
    enable_adversarial: bool = False

阶段 4: 监控和日志

# 新系统使用标准 Python logging

import logging
logger = logging.getLogger(__name__)

# 扫描进度会自动记录到日志
logger.info(f"Scan {scan_id} started")
logger.info(f"Phase {phase} completed")

API 变更

旧版 (Celery)

# 1. 创建扫描
POST /api/v1/scans
{
  "project_id": 7,
  "scan_type": "base"
}

# 2. 启动扫描
POST /api/v1/scans/{scan_id}/start

新版 (协程)

# 方式 1: 分步创建
POST /api/v1/scans
{...}
POST /api/v1/scans/{scan_id}/start-v2

# 方式 2: 一键扫描 (推荐)
POST /api/v1/scans/quick-scan?project_id=7&scan_type=base

性能对比

指标 旧版 (CLI) 新版 (协程) 改进
扫描启动 ~1500ms ~50ms 30x
内存占用 ~500MB ~200MB 2.5x
CPU 利用率 ~40% ~85% 2x
并发能力 受限于 Celery 协程池可配置 灵活

回滚计划

如果新架构出现问题，可以快速回滚：

  1. API 层面：停止使用 /start-v2 和 /quick-scan 端点
  2. 服务层面：重启 Celery Worker
  3. 数据层面：新架构使用相同的数据库表结构，无需迁移

常见问题

Q: 新架构支持暂停/恢复吗？

A: 当前版本支持取消（cancel），暂停/恢复功能将在下一版本添加。

Q: 如何查看扫描进度？

A: 使用现有的 /api/v1/scans/{scan_id} 端点，新架构会实时更新数据库。

Q: WebSocket 支持吗？

A: 计划在下一版本添加基于现有事件系统的 WebSocket 支持。

Q: 如何配置最大并发扫描数？

A: 在 BackgroundScanManager 初始化时设置，默认值为 3。

下一步

  1. ✅ 核心模块已创建
  2. ⏳ 需要添加单元测试
  3. ⏳ 需要更新前端 API 调用
  4. ⏳ 需要添加监控指标
  5. ⏳ 逐步废弃 Celery Worker

参考代码

DeepAudit 参考

  • /opt/AI/DeepAudit/backend/app/api/v1/endpoints/scan.py - 扫描端点
  • /opt/AI/DeepAudit/backend/app/services/llm/service.py - LLM 服务
  • /opt/AI/DeepAudit/backend/app/services/scanner.py - 扫描器

DeepVuln 新代码

  • src/web/services/scan/orchestrator.py - 编排器
  • src/web/services/scan/phases/ - 阶段实现
  • src/web/api/v1/scans_v2.py - 新 API 端点