4. 工具安装与环境准备

在开始风控数据质量沙盘推演之前，必须完成工具链的安装与依赖环境的配置。本章节详细说明系统要求、安装包获取方式以及 Python/Java 依赖环境的配置步骤，确保沙盘推演工具能够稳定运行。

4.1 系统要求

沙盘推演工具支持主流操作系统，推荐使用 Linux 或 macOS 进行生产级推演。Windows 用户可通过 WSL2 获得完整支持。以下为最低与推荐配置：

4.2 安装包获取

沙盘推演工具安装包通过官方制品仓库发布，支持两种获取方式：

1. 直接下载压缩包： 访问内部制品库（Artifactory/Nexus），下载 dq-sandbox-{version}.tar.gz 或 dq-sandbox-{version}.zip。
2. 通过 Git 克隆： 从内部 GitLab 仓库克隆完整项目，包含示例数据与推演剧本。

# 方式一：下载并解压
wget https://artifactory.example.com/dq-sandbox/releases/dq-sandbox-2.1.0.tar.gz
tar -xzf dq-sandbox-2.1.0.tar.gz
cd dq-sandbox-2.1.0

# 方式二：Git 克隆（推荐，便于后续更新）
git clone git@gitlab.example.com:dq-sandbox/dq-sandbox.git
cd dq-sandbox
git checkout tags/v2.1.0 -b stable-v2.1.0

4.3 Python 依赖环境配置

沙盘推演工具的核心引擎基于 Python 开发，依赖管理使用 Poetry 或 pip + virtualenv。以下为两种配置方式：

4.3.1 使用 Poetry（推荐）

# 安装 Poetry
curl -sSL https://install.python-poetry.org | python3 -

# 进入项目目录，安装所有依赖
cd dq-sandbox
poetry install

# 激活虚拟环境
poetry shell

4.3.2 使用 pip + virtualenv

# 创建虚拟环境
python3 -m venv venv

# 激活虚拟环境（Linux/macOS）
source venv/bin/activate

# 激活虚拟环境（Windows PowerShell）
.\venv\Scripts\Activate.ps1

# 安装依赖
pip install --upgrade pip
pip install -r requirements.txt

Python 依赖清单（核心组件）：

4.4 Java 依赖环境配置

沙盘推演工具中的实时流计算模块和部分数据源连接器基于 Java 实现，需要配置 JDK 和构建工具。

4.4.1 JDK 安装与验证

# 检查是否已安装 JDK
java -version

# 安装 OpenJDK 17（Ubuntu/Debian）
sudo apt update
sudo apt install openjdk-17-jdk -y

# 安装 OpenJDK 17（macOS Homebrew）
brew install openjdk@17

# 设置 JAVA_HOME 环境变量（写入 ~/.bashrc 或 ~/.zshrc）
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH

4.4.2 Maven 配置

项目使用 Maven 管理 Java 模块依赖，确保已安装 Maven 3.8+：

# 安装 Maven（Ubuntu/Debian）
sudo apt install maven -y

# 验证安装
mvn -version

# 编译 Java 模块（在项目根目录执行）
mvn clean package -pl java-modules -am -DskipTests

4.5 环境验证与架构总览

完成上述配置后，运行以下命令验证环境是否就绪：

# 验证 Python 环境
python3 -c "import pandas; import great_expectations; print('Python 依赖 OK')"

# 验证 Java 环境
java -version 2>&1 | grep "openjdk version"

# 运行沙盘工具自检
cd dq-sandbox
python3 dq_sandbox.py --check-env

以下 SVG 图展示了沙盘推演工具的完整软件架构与依赖层次：

上图清晰地展示了从用户接口到底层基础设施的完整依赖链路。Python 引擎承担核心推演逻辑，Java 模块负责流式数据接入，两者通过标准数据格式（Arrow/Parquet）进行交互。

4.6 常见安装问题与解决