基础开发环境搭建与入门指南

本文档帮助新加入项目的开发者快速完成开发环境搭建，了解项目基本结构，掌握常用开发命令。

1. 环境要求

组件	最低版本	推荐版本	说明
Python	3.10+	3.12+	后端运行环境
Node.js	20+	22+	前端构建环境
Java (Burp插件)	11 (Legacy) / 17 (Montoya)	17+	Burp 插件开发
Git	2.0+	最新版	版本控制（含子模块）
uv	最新版	最新版	Python 包管理器
pnpm	9+	最新版	Node.js 包管理器
Maven	3.8+	3.9+	Java 构建工具

2. 克隆项目

# 克隆项目（含子模块）
git clone --recurse-submodules https://github.com/your-org/sqlmapWebUI.git
cd sqlmapWebUI

# 如果已克隆但未初始化子模块
git submodule update --init --recursive

注意: src/backEnd/third_lib/sqlmap/ 是 git 子模块，必须正确初始化才能启动后端服务。

3. 后端开发环境

3.1 使用启动脚本（推荐）

启动脚本自动完成虚拟环境创建、依赖安装和服务启动：

Windows:

cd src\backEnd
start.bat

Linux/macOS:

cd src/backEnd
chmod +x start.sh
./start.sh

3.2 手动搭建

cd src/backEnd

# 安装 Python 依赖
uv sync --extra thirdparty

# 启动后端服务
uv run python main.py

服务启动后访问: http://localhost:8775

3.3 启动配置

startup.conf 配置文件说明：

配置项	说明	默认值
NETWORK_MODE	网络模式 (online/intranet/offline)	online
PYPI_MIRROR	PyPI 镜像源	tsinghua
HOST	服务绑定地址	127.0.0.1
PORT	服务端口	8775
ADMIN_USERNAME	管理员用户名	admin
ADMIN_PASSWORD	管理员密码	admin
FORCE_UTF8	强制 UTF-8 编码	true
DEBUG	调试模式	false
LOG_LEVEL	日志级别	INFO
SKIP_DEPS_CHECK	跳过依赖检查	false

3.4 离线环境部署

# 1. 在有网络环境准备离线包
prepare_offline.bat  # Windows
# ./prepare_offline.sh  # Linux/macOS

# 2. 复制 backEnd 目录到离线机器
# 3. 设置 NETWORK_MODE=offline 并启动

4. 前端开发环境

cd src/frontEnd

# 安装依赖
pnpm install

# 开发模式启动（热重载）
pnpm run dev

# 构建生产版本（输出到 src/backEnd/static/）
pnpm run build

# 代码检查
pnpm run lint

开发模式访问: http://localhost:5173

4.1 前端环境变量

文件	用途
`.env.development`	开发环境配置
`.env.production`	生产环境配置

5. VulnShop 靶场

cd src/vulnTestServer

# 安装依赖
pip install flask

# 启动靶场
python server.py

访问: http://127.0.0.1:9527

测试账户:

admin / admin123 (管理员)
test / test (普通用户)
alice / alice123 (普通用户)

6. Burp Suite 插件开发

# Montoya API (Burp 2023.1+，推荐)
cd src/burpEx/montoya-api
mvn clean package -DskipTests
# 输出: target/sqlmap-webui-burp-montoya-{version}.jar

# Legacy API (旧版 Burp)
cd src/burpEx/legacy-api
mvn clean package -DskipTests
# 输出: target/sqlmap-webui-burp-legacy-{version}.jar

在 Burp Suite 中: Extender → Extensions → Add → 选择生成的 JAR 文件

7. 项目目录结构概览

sqlmapWebUI/
├── src/
│   ├── backEnd/                 # 后端 (Python/FastAPI)
│   │   ├── api/                 # API 路由层
│   │   │   ├── webApi/          # Web 前端调用的 API
│   │   │   ├── burpSuiteExApi/  # Burp 插件调用的 API
│   │   │   └── commonApi/       # 通用 API (认证/配置/Header/Body)
│   │   ├── model/               # 数据模型层
│   │   │   ├── requestModel/    # 请求 DTO
│   │   │   ├── Task.py          # 任务模型
│   │   │   ├── ScanPreset.py    # 扫描配置预设
│   │   │   ├── PersistentHeaderRule.py  # 持久化 Header 规则
│   │   │   └── SessionBodyField.py      # 会话 Body 字段
│   │   ├── service/             # 业务逻辑层
│   │   │   ├── taskService.py   # 任务管理服务
│   │   │   ├── headerRuleService.py  # Header 规则服务
│   │   │   └── scanPresetService.py  # 扫描预设服务
│   │   ├── utils/               # 工具函数
│   │   │   ├── header_processor.py        # Header 处理
│   │   │   ├── body_field_processor.py    # Body 字段处理
│   │   │   ├── scope_matcher.py           # 作用域匹配
│   │   │   ├── session_header_manager.py  # 会话 Header 管理
│   │   │   ├── session_body_field_manager.py  # 会话 Body 字段管理
│   │   │   ├── task_monitor.py            # 任务监控
│   │   │   └── websocket_manager.py       # WebSocket 管理
│   │   ├── third_lib/sqlmap/    # SQLMap 子模块
│   │   ├── app.py               # FastAPI 应用
│   │   ├── main.py              # 入口文件
│   │   ├── config.py            # 全局配置
│   │   └── startup.conf         # 启动配置
│   ├── frontEnd/                # 前端 (Vue 3/TypeScript)
│   │   └── src/
│   │       ├── api/             # API 请求模块
│   │       ├── components/      # 公共组件
│   │       ├── stores/          # Pinia 状态管理
│   │       ├── types/           # TypeScript 类型定义
│   │       ├── utils/           # 工具函数
│   │       └── views/           # 页面视图
│   │           ├── Home/        # 首页仪表盘
│   │           ├── TaskList/    # 任务列表
│   │           ├── TaskDetail/  # 任务详情
│   │           ├── AddTask/     # 添加任务
│   │           ├── Config/      # 配置管理
│   │           ├── About/       # 关于/帮助
│   │           └── Login/       # 登录
│   ├── burpEx/                  # Burp Suite 插件
│   │   ├── legacy-api/          # Legacy API (Java 11)
│   │   └── montoya-api/         # Montoya API (Java 17)
│   └── vulnTestServer/          # VulnShop 靶场
│       ├── handlers/            # 请求处理器（模块化）
│       ├── static/              # 前端静态资源
│       ├── server.py            # HTTP 服务器
│       ├── database.py          # 数据库管理
│       ├── waf.py               # WAF 模块
│       └── logger.py            # 日志模块
└── doc/                         # 项目文档

8. 开发流程

8.1 日常开发

# 1. 启动后端（终端1）
cd src/backEnd
uv run python main.py

# 2. 启动前端（终端2）
cd src/frontEnd
pnpm run dev

# 3. 开发前端页面，浏览器访问 http://localhost:5173
# 4. 前端 API 请求自动代理到后端 http://localhost:8775

8.2 前后端联调

开发模式下前端请求通过 Vite 代理转发到后端：

// vite.config.ts 中的代理配置
server: {
  proxy: {
    '/api': 'http://localhost:8775'
  }
}

8.3 构建部署

# 构建前端
cd src/frontEnd
pnpm run build

# 构建产物自动复制到 src/backEnd/static/
# 启动后端即可访问完整应用
cd src/backEnd
uv run python main.py
# 访问 http://localhost:8775

9. 常见问题

Q: uv sync 报错 "No module named sqlmap"?

A: 确保已初始化 git 子模块: git submodule update --init --recursive

Q: 前端请求后端返回 403?

A: 检查 CORS 配置，确保前端在允许的端口范围内 (5173-5176)

Q: Burp 插件构建失败?

A: 检查 Java 版本: Montoya API 需要 JDK 17+，Legacy API 需要 JDK 11+

Q: VulnShop 启动后无法访问?

A: 确保使用 127.0.0.1:9527 而非 localhost:9527

下一篇: 核心功能开发与调试技巧

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

基础开发环境搭建与入门指南

1. 环境要求

2. 克隆项目

3. 后端开发环境

3.1 使用启动脚本（推荐）

3.2 手动搭建

3.3 启动配置

3.4 离线环境部署

4. 前端开发环境

4.1 前端环境变量

5. VulnShop 靶场

6. Burp Suite 插件开发

7. 项目目录结构概览

8. 开发流程

8.1 日常开发

8.2 前后端联调

8.3 构建部署

9. 常见问题

Q: uv sync 报错 "No module named sqlmap"?

Q: 前端请求后端返回 403?

Q: Burp 插件构建失败?

Q: VulnShop 启动后无法访问?

FilesExpand file tree

beginner_guide.md

Latest commit

History

beginner_guide.md

File metadata and controls

基础开发环境搭建与入门指南

1. 环境要求

2. 克隆项目

3. 后端开发环境

3.1 使用启动脚本（推荐）

3.2 手动搭建

3.3 启动配置

3.4 离线环境部署

4. 前端开发环境

4.1 前端环境变量

5. VulnShop 靶场

6. Burp Suite 插件开发

7. 项目目录结构概览

8. 开发流程

8.1 日常开发

8.2 前后端联调

8.3 构建部署

9. 常见问题

Q: uv sync 报错 "No module named sqlmap"?

Q: 前端请求后端返回 403?

Q: Burp 插件构建失败?

Q: VulnShop 启动后无法访问?