📚 课程目录第4章 SDK环境搭建

第4章：SDK环境搭建——安装与配置数据资产发现SDK

好了，到了动手的环节了。

前面几章我们聊了数据资产发现的理论和价值，但说白了，没有工具，一切都是空谈。这一章，我就带你把这个核心的SDK给搭起来。我个人的经验是，环境搭建这一步虽然基础，但恰恰是很多项目后面踩坑的源头。我们基于一个真实可用的开源项目——OpenMetaDiscovery（一个轻量级的数据资产发现引擎）来操作。别担心，我手把手带你过一遍。

4.1 环境准备：先看看你的机器够不够格

在开始之前，你得先确认下你的开发环境。我记得有一次在公司内网服务器上装，结果发现那台老机器Python版本太低，折腾了半天。所以咱们先列个清单，对照着检查一下。

依赖项	最低版本	推荐版本	检查命令
Python	3.8+	3.10.x	`python3 --version`
pip	21.0+	23.x	`pip --version`
Git	2.0+	2.30+	`git --version`
JDK (可选，用于部分扫描插件)	11+	17 LTS	`java -version`

小提示： 如果你用的是Windows，建议安装Python时勾上“Add Python to PATH”，不然后面命令行里调不了python命令，会很痛苦。

4.2 获取SDK源码：两种方式，你选哪一种？

环境确认没问题了，咱们就来拿代码。我一般习惯用Git克隆的方式，因为后续更新方便。但如果你是只想集成看看，直接下载ZIP包也行。

方式一：Git 克隆（推荐）

# 找个你顺手的目录
cd ~/workspace

# 克隆项目（注意，这是示例地址）
git clone https://github.com/example/open-meta-discovery-sdk.git

# 进入项目目录
cd open-meta-discovery-sdk

方式二：直接下载压缩包

去项目的GitHub Release页面，下载最新的 Source code (zip) 文件。然后解压到你的工程目录里。

警告： 千万别直接把下载的SDK文件夹扔到系统盘或者C盘根目录下。我曾经见过同事把代码解压在桌面，结果后面权限、路径问题一大堆。最好放在一个英文路径、无空格的文件夹下。

4.3 搭建虚拟环境：隔离是必须的

接下来，我们要搞一个干净的Python虚拟环境。为什么要这么做？说白了，就是防止你这个项目的依赖包和其他项目“打架”。我之前在一个项目里把Flask的版本搞乱了，结果整个服务器上的web服务都挂了，从那以后，我建任何项目第一件事就是开虚拟环境。

# 在SDK根目录下执行
python3 -m venv venv

# 激活虚拟环境
# Linux/macOS:
source venv/bin/activate
# Windows:
# .\venv\Scripts\activate

# 激活成功后，你会看到命令行前面多了个 (venv) 前缀
(venv) ➜  open-meta-discovery-sdk

4.4 安装依赖与SDK核心包

环境激活了，就可以装东西了。项目里的 requirements.txt 文件已经把需要的第三方库都列好了。我们直接一键安装。

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

# 安装SDK核心包（开发模式安装，方便改代码直接生效）
pip install -e .

pip install -e . 这行命令很关键。它会把我们当前的这个项目，以一个“可编辑”的模式安装到Python环境里。这意味着，你后续改动SDK的源码，不需要重新安装，立刻就能生效。开发调试的时候，这个功能非常爽。

    核心要点： 安装完成后，你可以用 pip list | grep open-meta 命令看看，是不是能看到一个叫 open-meta-discovery-sdk 的包。看到了，就说明安装成功了。

4.5 初始化配置：让SDK知道你是谁

安装好，只是个开始。你得告诉SDK你的数据库连接信息、资产扫描的规则等。这些配置通常放在一个叫 config.yaml 的文件里。项目里有个 config.yaml.example 的示例文件，我们复制一份出来。

# 复制示例配置文件
cp config.yaml.example config.yaml

# 修改配置文件（用vim或你的文本编辑器）
vim config.yaml

配置文件里，最核心的是数据源连接设置。结构大致是这样的：

# config.yaml 核心内容示例
metadata:
  project_name: "my-data-assets"
  storage_type: "sqlite"  # 可选: sqlite, mysql, postgresql

connectors:
  databases:
    - name: "prod_mysql"
      type: "mysql"
      host: "192.168.1.100"
      port: 3306
      user: "reader"
      password: "YourPassword"
      database: "sales_db"
  file_systems:
    - name: "hdfs_primary"
      type: "hdfs"
      uri: "hdfs://namenode:8020"
      path: "/data/business"

plugins:
  - classification.pii_enabled: true   # 开启PII数据分类
  - profiling.sampling_rate: 0.1       # 采样率10%

避坑指南： 配置文件里的密码，千万别硬编码提交到Git仓库里。我之前就踩过这个坑，还好发现及时。建议用环境变量或者配置中心来管理敏感信息。SDK支持从环境变量读取，比如 ${MYSQL_PASSWORD}。

4.6 验证安装：跑一个最简单的扫描

一切就绪，是骡子是马，拉出来溜溜。SDK提供了一个命令行工具 omd-cli，我们先试一个最简单的本地文件扫描，看看能不能正常工作。

# 创建一个测试目录，里面放几个CSV或JSON文件
mkdir demo_scan
echo "id,name,email\n1,alice,alice@test.com" > demo_scan/users.csv

# 执行扫描命令
omd-cli scan --path ./demo_scan --verbose

如果一切顺利，你会看到终端里打印出类似下面的信息：

[INFO] 2024-01-15 10:30:01 - OpenMetaDiscovery: Loaded config from config.yaml
[INFO] 2024-01-15 10:30:02 - Scanner: Starting scan on path ./demo_scan
[INFO] 2024-01-15 10:30:02 - Scanner: 1 file(s) discovered.
[INFO] 2024-01-15 10:30:03 - Classifier: Found 2 fields, 1 PII field(s) detected (email).
[INFO] 2024-01-15 10:30:03 - Report: Written to ./output/report_20240115.json
Scan completed in 0.12 seconds.

看到 Scan completed 这几个字，恭喜你，你的SDK环境已经搭建成功，并且跑通了第一个发现任务！

4.7 知识图谱：这一章的核心逻辑

为了让你对刚才的搭建过程有个全局认识，我画了一张图。它把整个环境搭建和配置的脉络串起来了。

4.8 排雷手册：常见环境问题速查

搭建过程中，难免会遇到些小磕绊。这里我把常见的几种问题和解决办法列出来，你遇到了可以直接查。

症状	可能原因	解决方案
`pip install -e .` 报错	setuptools版本过旧	`pip install --upgrade setuptools wheel`
`omd-cli: command not found`	SDK没安装到PATH里	确认虚拟环境已激活，或者用 `python -m omd_cli` 代替
连不上数据库	配置文件中的host/port写错	先在本机用mysql客户端或telnet测试端口是否通
扫描结果为空	扫描路径不对，或文件类型不支持	检查 `--path` 参数，确保路径下有 `.csv/.json/.parquet` 文件

嗯，到这里，你的SDK环境就算正式搭好了。我带你走了一遍从零到一的全过程，每一步都尽量拆得细一些。后面的章节，我们就要在这个基础上，玩点更高级的东西了。