📚 课程目录第4章环境准备

环境准备：从零搭好校验环境

说实话，很多数据迁移事故都栽在环境不一致上。我入行第三年就吃过这个亏——生产环境跑得好好的校验脚本，到测试环境各种报错，最后发现是SDK版本差了一个小号。所以这一章，咱们先把地基打牢。

你会配置操作系统依赖、打通网络、初始化数据库，最后装好Secrets SDK。整个过程不复杂，但每一步都有坑。我按顺序来说，你跟着做就行。

操作系统：选对版本，少踩一半坑

我个人习惯用 CentOS 7.9+ 或 Ubuntu 20.04 LTS。内核版本不能太老，否则 glibc 跟不上，SDK 编译时会报一些莫名其妙的链接错误。

操作系统	最低要求	推荐配置
CentOS / RHEL	7.6 + kernel 3.10	8.4 + kernel 4.18
Ubuntu	18.04 LTS	20.04 LTS 或 22.04 LTS
Debian	10	11

装好系统后，先跑一遍以下命令，确认基础工具链齐全：

# 检查内核版本
uname -r

# 查看 glibc 版本
ldd --version | head -n1

# 检查 Python 3
python3 --version || python --version

# 如果少了依赖，用包管理器装
# CentOS
yum install -y gcc gcc-c++ make python3 python3-pip git
# Ubuntu
apt update && apt install -y build-essential python3 python3-pip git

小建议： 如果是在容器里跑，用官方 Python 3.11 slim 镜像最省事。我每次搭建新环境都用 Dockerfile 把依赖写死，避免手动漏装。

网络：打通源和目标的数据通道

数据迁移一致性校验要在源库和目标库之间来回跑查询。网络不通，后面全白搭。

你需要确认以下几点：

端口可达： 源端 API 端口（默认 8443）和目标端 API 端口，数据库端口（MySQL 3306 / PostgreSQL 5432）。
代理透传： 如果有 HTTP 代理，确保 SDK 能读到 http_proxy 和 https_proxy 环境变量。
DNS 解析： 检查 /etc/hosts 或 DNS 服务器，防止因域名解析失败导致连接超时。

# 测试 API 连通性
curl -v https://source-secrets-api.example.com:8443/health

# 测试数据库连通性
mysql -h source-db.example.com -P 3306 -u checkuser -p -e "SELECT 1"
psql -h target-db.example.com -U checkuser -c "SELECT 1"

注意： 我曾经遇过一个问题——源库和目标库之间有防火墙，但防火墙只允许特定源 IP 访问。结果 SDK 容器跑在另一个 IP 段，连接全被 reject。建议提前把校验机器的 IP 加白名单。

数据库：创建专用校验用户

一致性校验需要读取表结构和数据，但 不要用 root。我习惯创建一个只读用户，权限缩到最小。

MySQL 和 PostgreSQL 的常见配置如下：

数据库类型	创建 SQL	最小权限
MySQL	`CREATE USER 'checker'@'%' IDENTIFIED BY '...';`	`SELECT, SHOW VIEW, LOCK TABLES` on 校验库
PostgreSQL	`CREATE USER checker WITH PASSWORD '...';`	`CONNECT, SELECT` on 目标 schema
SQL Server	`CREATE LOGIN checker WITH PASSWORD='...';`	`db_datareader` 角色

除了用户，还要检查数据库的 binlog_format 和 binlog_row_image。MySQL 必须设为 ROW 和 FULL，否则增量校验拿不到完整的数据变更。

-- MySQL 检查配置
SHOW VARIABLES LIKE 'binlog_format';
SHOW VARIABLES LIKE 'binlog_row_image';

-- 如果不对，动态修改（需要 super 权限）
SET GLOBAL binlog_format = 'ROW';
SET GLOBAL binlog_row_image = 'FULL';

避坑： 源库的 auto_increment 字段和目标库可能不一致。校验前先跑一次 MAX(id) 对两边，如果差太多可能数据没迁移干净。

Secrets SDK：安装与验证

SDK 安装没什么神奇的，但版本要跟迁移目标匹配。我一般固定到某个小版本，避免大版本升级带来偏移变化。

以 Python SDK 为例：

# 使用 pip 安装
pip install secrets-sdk==2.1.0

# 或者从源码安装（需要 git 和编译工具）
git clone https://github.com/your-org/secrets-sdk.git
cd secrets-sdk
pip install -e .

# 验证安装
python -c "from secrets_sdk import Client; print('SDK version:', Client.version)"

装好之后，第一步就是用测试环境跑一次连通性检测。创建一个最小的客户端，连到 API 并拉一条记录：

from secrets_sdk import Client

client = Client(
    endpoint="https://source-secrets-api.example.com:8443",
    ="your_",
    timeout=30
)

# 尝试获取一个 secret
try:
    secret = client.get_secret("test/connection-check")
    print("连接成功:", secret["metadata"]["name"])
except Exception as e:
    print("连接失败:", e)

关键点： timeout 建议设为 30s，别用默认的 5s——我第一次跑线上环境时，源库刚好在做全量备份，5s 超时频发，折腾了半天才发现不是代码的锅。

SDK 安装完成后，我建议你顺手把 ~/.secrets_sdk/config.yaml 写好。这样后续所有 CLI 命令都不用重复传参数。配置文件示例如下：

# ~/.secrets_sdk/config.yaml
default:
  endpoint: https://source-secrets-api.example.com:8443
  : your_
  timeout: 30
  retry_max: 3

快速检查清单

环境配好后，别急着往后跑。花 5 分钟过一遍这个清单，能省下后面排查问题的几小时。

操作系统、Python/go 版本符合要求
源端 API 和数据库端口双向可达
数据库只读用户已创建，权限正确
binlog 配置为 ROW + FULL
Secrets SDK 安装成功，连接测试通过
SDK 配置文件就绪

嗯，到这一步，你的环境就算彻底搭好了。后面章节我们会用它跑具体的校验流程。