📚 课程目录第3章 SDK的安装与配置

3. SDK的安装与配置

SDK的安装与配置，说实话是整场测试的起点。起点不扎实，后面跑用例时各种报错，查了半天才发现是环境没搭对。我自己就折腾过好几回，所以这一章我尽量把踩过的坑都指出来。

3.1 系统环境要求

先看看你的系统够不够“资格”。这个SDK对底层依赖挺挑的，尤其是一些老掉牙的CentOS 6，glibc版本太低，装都装不上。

项目	最低要求	推荐版本
操作系统	Linux kernel 3.10+ / macOS 12+ / Windows 10 64-bit	Ubuntu 22.04 / macOS 14 / Windows 11
CPU架构	x86_64 / arm64	x86_64
内存	2 GB	8 GB 及以上
磁盘空间	500 MB	2 GB（含示例数据和日志）
依赖库	glibc 2.17+, OpenSSL 1.1.1+, libcurl 7.68+	glibc 2.35, OpenSSL 3.0, libcurl 7.81

⚠ 注意： 如果你用的是Windows，记得装好Visual C++ Redistributable（2019或更高）。不然SDK加载时直接崩掉，我遇到过两次，后来才反应过来。

3.2 下载与安装SDK

SDK包可以在我们官方的制品仓库下载，也支持通过包管理器直接拉。我个人习惯用以下方式：

下载压缩包：wget https://releases.example.com/cspm-sdk/v3.2.0/linux-amd64.zip
解压：unzip linux-amd64.zip -d /opt/cspm-sdk
设置执行权限：chmod +x /opt/cspm-sdk/bin/*

如果是Debian/Ubuntu，也可以添加APT源一键安装：

echo "deb https://packages.example.com/cspm-sdk/apt stable main" | sudo tee /etc/apt/sources.list.d/cspm.list
sudo apt update
sudo apt install cspm-sdk

我记得有一次生产环境不能连外网，只能用内网仓库。那时候我提前把deb包下载好，再用 dpkg -i 手动装，结果依赖问题折腾了一下午。所以啊，建议优先用包管理器，它会自动把libcurl、openssl这些一并装好。

3.3 环境变量与初始化配置

装好之后，还得让系统知道SDK在哪儿。把下面几行加到 ~/.bashrc 或 ~/.zshrc 里：

export CSPM_SDK_HOME=/opt/cspm-sdk
export PATH=$CSPM_SDK_HOME/bin:$PATH
export LD_LIBRARY_PATH=$CSPM_SDK_HOME/lib:$LD_LIBRARY_PATH

然后 source ~/.bashrc 刷新。检查一下：echo $CSPM_SDK_HOME 能看到路径就对了。

接下来是初始化配置。SDK需要一个 cspm_config.json 文件，里面填上你的、区域端点这些。模板长这样：

{
  "": "your__here",
  "region": "ap-southeast-1",
  "endpoint": "https://api.cspm.example.com",
  "timeout_seconds": 30,
  "log_level": "info"
}

  💡 提示： 建议别硬编码在配置文件里，尤其是提交到Git的时候。可以先用环境变量 CSPM_ 传进去，SDK会自动读。我在项目中就用这个方案，既灵活又安全。

文件默认放在 $CSPM_SDK_HOME/conf/，也可以通过 --config 参数指定其他位置。

3.4 验证安装

验证很简单，跑一个自检命令就好：

cspm-sdk version
cspm-sdk health --config /opt/cspm-sdk/conf/cspm_config.json

第一个命令输出SDK版本号，第二个命令检查网络连通性和API可用性。如果看到 Status: OK，那基本就搞定了。我曾经遇到过 health 命令报证书错误，后来发现是系统CA证书没更新，手动更新一下 ca-certificates 就好了。

3.5 常见问题与避坑

🔧 小技巧： 如果 cspm-sdk health 返回超时，多半是防火墙或代理问题。可以设 HTTP_PROXY 环境变量，SDK会自动读取。我项目里就遇到过公司内网需要走代理，加上 export HTTP_PROXY=http://proxy.company.com:8080 就通了。

🚨 踩坑实录： 我曾经在macOS上安装后，运行SDK直接 Illegal instruction。查了半天发现是Intel的SDK被装到了Apple Silicon机器上。后来下载 arm64 版本就正常了。所以下载前一定确认架构！

另外，配置文件里的字段如果填错了，SDK不会报语法错误，只会在API调用时返回403。那时候排查起来特别绕。我建议你写个简单脚本来验证：

cspm-sdk list-providers --config ./cspm_config.json

如果能拉回云供应商列表，说明密钥和网络都没问题。这一步虽然小，但能省掉后面很多调试时间。