datahub-upgrade CLI 镜像文档

一、镜像概述和主要用途

datahub-upgrade CLI 镜像是用于 DataHub 数据治理平台升级管理的命令行工具容器化封装。该镜像提供了标准化的升级流程，支持 DataHub 实例的版本检查、预升级验证、升级执行及结果确认等操作，旨在简化 DataHub 升级过程，降低手动操作风险，确保升级过程可重复、可审计。

二、核心功能和特性

核心功能

1. 版本兼容性检查：自动检测当前 DataHub 实例版本与目标版本的兼容性，识别潜在冲突（如依赖组件版本、API 变更）。
2. 预升级验证：执行升级前的环境检查（如数据库连接性、服务健康状态、资源充足性），输出风险评估报告。
3. 升级流程自动化：按预设步骤执行升级（包括元数据迁移、配置更新、服务重启触发等），支持断点续跑。
4. 回滚支持：升级失败时可触发自动回滚（需提前启用备份），恢复至升级前状态。
5. 多环境适配：支持自定义配置文件，适配不同部署环境（开发、测试、生产）的升级需求。

特性

• 无状态设计：工具本身不存储持久数据，升级过程依赖外部配置（如 DataHub 服务地址、认证信息）。
• 轻量级：基于 Alpine 或 Distroless 基础镜像，镜像体积小，启动速度快。
• 日志标准化：输出 JSON 格式日志，支持集成至日志收集系统（如 ELK、Prometheus）。

三、使用场景和适用范围

典型使用场景

1. DataHub 版本升级：生产/测试环境中 DataHub 实例的主版本/次版本升级（如从 v0.10.5 升级至 v0.11.0）。
2. 升级流程测试：在预发环境验证升级脚本的有效性，模拟生产环境条件执行“干跑”（dry-run）。
3. 多实例批量升级：通过统一配置文件，对分布式部署的多个 DataHub 实例执行一致性升级。
4. 升级审计与合规：记录升级过程日志，满足数据治理场景下的操作审计要求。

适用范围

• 基于 Docker/Kubernetes 部署的 DataHub 实例（支持开源版及企业版）。
• 需严格控制升级风险的生产环境（如***、电商等对数据连续性要求高的场景）。
• 需跨团队协作执行升级的组织（通过标准化工具统一操作流程）。

四、使用方法和配置说明

4.1 前置条件

• 已部署 DataHub 实例，且可通过网络访问（需开放 API 端口，默认 8080/8443）。
• 具备 DataHub 管理员权限（用于执行元数据操作、服务重启等）。
• 若启用数据备份，需提前配置外部存储（如 S3、NFS）用于存储备份文件。

4.2 基本使用流程

1. 拉取镜像：从镜像仓库拉取指定版本的 datahub-upgrade CLI 镜像（建议使用固定版本标签，避免自动更新风险）。

   bash
   docker pull acryldata/datahub-upgrade:v0.11.0  # 示例版本，需替换为实际目标版本
   

2. 执行升级操作：通过 docker run 启动容器，传入升级参数（如目标版本、DataHub 服务地址等）。

3. 验证升级结果：升级完成后，通过工具内置命令或外部健康检查确认服务状态及数据完整性。

4.3 配置参数与环境变量

4.3.1 环境变量

4.3.2 命令行参数

4.4 部署示例

4.4.1 基础升级命令（docker run）

以下示例为升级 DataHub 至 v0.11.0，执行预检查并备份数据：

bash
docker run -it --rm \
  -e DATAHUB_BASE_URL="[***]" \
  -e DATAHUB_AUTH_TOKEN="your-auth-token" \
  -e BACKUP_DIR="/backup" \
  -v /host/backup:/backup \  # 挂载主机目录存储备份文件
  acryldata/datahub-upgrade:v0.11.0 \
  upgrade --target-version v0.11.0 --backup

4.4.2 干跑模式（验证升级流程）

bash
docker run -it --rm \
  -e DATAHUB_BASE_URL="[***]" \
  acryldata/datahub-upgrade:v0.11.0 \
  upgrade --target-version v0.11.0 --dry-run --verbose

五、注意事项

1. 版本匹配：确保 datahub-upgrade CLI 镜像版本与目标 DataHub 版本一致（如升级至 v0.11.0 需使用对应 CLI 版本）。

2. 生产环境建议：升级前通过 --dry-run 验证流程，并手动备份关键数据（如数据库、配置文件），避免工具备份失效。

3. 网络隔离：若 DataHub 部署在私有网络，需确保容器可访问 DataHub 服务及依赖组件（如数据库、Kafka）。

4. 资源限制：升级过程可能涉及元数据迁移，建议为容器分配足够 CPU/内存（如 --cpus 2 --memory 4g）。

注：具体参数及功能可能随 DataHub 版本迭代更新，使用前请参考对应版本的***升级文档。