Nexus 3 跨架构迁移中的数据完整性陷阱与解决方案

约 1612 字大约 5 分钟

2026-01-05

摘要

在 Sonatype Nexus Repository Manager 3 的运维过程中，因版本回退（从 H2 架构降级回 OrientDB 架构）而进行的双实例数据迁移（Side-by-Side Migration）是一项高风险操作。本文记录了一次在迁移过程中遇到的典型“静默数据损坏”事故——“3KB 伪构件问题”，深入分析了 Shell 管道流处理 HTTP 请求的缺陷，并提供了一套具备完整校验机制的工程化解决方案。

1. 背景与挑战

由于 Nexus 3.69.0+ 引入了 H2 数据库作为默认存储，导致无法直接通过 Docker 镜像标签回滚至旧版本（如 3.68.1）。为了恢复到 OrientDB 架构的稳定版本，采用了 “双实例迁移法”：

Source (源): Nexus Latest (H2 架构)
Target (目标): Nexus 3.68.1 (OrientDB 架构)
手段: 使用 Shell 脚本调用 REST API 搬运 Maven 仓库资产。

2. 故障现象：3KB 的“幽灵”Jar 包

在初次执行流式迁移脚本后，Target 仓库显示资产迁移成功。但在实际构建中，Maven 客户端报错 Invalid JAR。

经过排查，发现异常特征如下：

文件大小异常：目标仓库中所有的 JAR、POM 文件大小均显示为 3KB 左右（或几百字节）。
文件内容异常：使用 head 命令查看该“JAR 包”内容，发现并非二进制乱码，而是明文 HTML：

<html>
  <head><title>404 Not Found</title></head>
  <body>...</body>
</html>

或者是 JSON 报错：

{ "errors" : [ { "id" : "*", "msg" : "Not authorized" } ] }

3. 根本原因分析 (Root Cause Analysis)

3.1 错误的流式处理模型

初代脚本使用了 Linux 管道（Pipe）来提高效率，逻辑如下：

# 错误示范
curl (下载源) | curl (上传目标)

缺陷在于：管道操作是“盲目”的。当 curl (下载源) 因为 401 鉴权失败 或 404 路径错误 而失败时，它返回的并不是空，而是一个包含错误信息的 HTTP 响应体（HTML 页面）。管道符 | 并不关心 HTTP 状态码，它忠实地将这段 HTML 文本传递给了 curl (上传目标)，后者将其写入新仓库并命名为 application.jar。

3.2 不可信的 API 元数据

Nexus API 返回的 downloadUrl 字段通常是基于容器内部配置生成的（例如 http://localhost:8081/...）。如果迁移脚本运行在宿主机或另一台机器上，直接使用该 URL 会导致连接拒绝或超时，进而触发上述的错误页面捕获流程。

4. 工程化解决方案：安全模式 (Safe Mode)

为了确保数据完整性（Data Integrity），我们摒弃了不可控的管道流，转而采用 “下载-校验-上传” (Download-Verify-Upload) 的三段式事务模型。

4.1 核心算法逻辑

物理下载：将资产下载至临时磁盘空间。
前置校验：

检查 HTTP 状态码是否为 200。
检查文件大小是否有效（>100 Bytes）。
检查文件头（Magic Number）是否包含 HTML 标签。

原子上传：仅当校验通过后，执行上传操作。
资源回收：删除临时文件。

4.2 最终版迁移脚本

该脚本修复了特殊字符转义问题，并强制重组了下载 URL 以规避内网 IP 问题。

#!/bin/bash

# ================= 配置区域 =================
# [安全提示] 密码必须使用单引号包裹，防止 Shell 解析特殊字符
SOURCE_HOST="http://192.168.1.10:15581"
SOURCE_USER="admin"
SOURCE_PASS='YourSecretPass!' 
SOURCE_REPO="maven-releases"

TARGET_HOST="http://192.168.1.10:15582"
TARGET_USER="admin"
TARGET_PASS='YourSecretPass!' 
TARGET_REPO="maven-releases"

TEMP_DIR="./migration_buffer"
# ===========================================

# 环境自检
if ! command -v jq &> /dev/null; then echo "Error: jq is required."; exit 1; fi
mkdir -p "$TEMP_DIR"

echo "=== 开始安全模式迁移 ==="

CONTINUATION_TOKEN=""

while true; do
    # 1. 分页获取资产列表
    API_URL="$SOURCE_HOST/service/rest/v1/assets?repository=$SOURCE_REPO"
    if [ -n "$CONTINUATION_TOKEN" ] && [ "$CONTINUATION_TOKEN" != "null" ]; then
        API_URL="${API_URL}&continuationToken=${CONTINUATION_TOKEN}"
    fi

    RESPONSE=$(curl -s -f -u "$SOURCE_USER:$SOURCE_PASS" "$API_URL")
    if [ $? -ne 0 ]; then
        echo "❌ Critical Error: 无法获取列表，请检查网络或账号权限。"
        exit 1
    fi

    # 2. 遍历处理
    echo "$RESPONSE" | jq -r '.items[] | .path' | while read -r ASSET_PATH; do
        # 过滤元数据文件（建议迁移后重建索引）
        if [[ "$ASSET_PATH" == *"maven-metadata"* ]]; then continue; fi

        # 路径标准化
        SAFE_FILENAME=$(echo "$ASSET_PATH" | sed 's/\//_/g')
        LOCAL_FILE="$TEMP_DIR/$SAFE_FILENAME"
        
        # 强制拼接 URL (不信任 API 返回的 downloadUrl)
        REAL_DOWNLOAD_URL="$SOURCE_HOST/repository/$SOURCE_REPO/$ASSET_PATH"
        TARGET_UPLOAD_URL="$TARGET_HOST/repository/$TARGET_REPO/$ASSET_PATH"

        echo "Processing: $ASSET_PATH"

        # --- STEP A: 下载 ---
        # -L: 跟随重定向, -f: HTTP错误时静默失败
        curl -s -f -L -u "$SOURCE_USER:$SOURCE_PASS" -o "$LOCAL_FILE" "$REAL_DOWNLOAD_URL"

        # --- STEP B: 校验 (核心安全机制) ---
        if [ ! -f "$LOCAL_FILE" ]; then
            echo "  ⚠️ [Skip] 下载失败 (Source 404/Connection Error)"
            continue
        fi

        # 校验文件指纹：排除 HTML 错误页
        FILE_SIZE=$(wc -c < "$LOCAL_FILE")
        CONTENT_HEAD=$(head -n 1 "$LOCAL_FILE")
        
        if [ "$FILE_SIZE" -lt 200 ] && ([[ "$CONTENT_HEAD" == *"html"* ]] || [[ "$CONTENT_HEAD" == *"errors"* ]]); then
            echo "  ⚠️ [Skip] 文件损坏 (检测到 HTML/Error 响应): $CONTENT_HEAD"
            rm -f "$LOCAL_FILE"
            continue
        fi

        # --- STEP C: 上传 ---
        UPLOAD_CODE=$(curl -s -o /dev/null -w "%{http_code}" -u "$TARGET_USER:$TARGET_PASS" -T "$LOCAL_FILE" "$TARGET_UPLOAD_URL")

        if [[ "$UPLOAD_CODE" == "200" ]] || [[ "$UPLOAD_CODE" == "201" ]]; then
            echo "  ✅ [OK] Size: $FILE_SIZE bytes"
        else
            echo "  ❌ [Fail] HTTP $UPLOAD_CODE"
        fi

        # --- STEP D: 清理 ---
        rm -f "$LOCAL_FILE"
    done

    # 分页逻辑
    CONTINUATION_TOKEN=$(echo "$RESPONSE" | jq -r '.continuationToken')
    if [ -z "$CONTINUATION_TOKEN" ] || [ "$CONTINUATION_TOKEN" == "null" ]; then
        echo "=== Migration Completed ==="
        break
    fi
done

rm -rf "$TEMP_DIR"

5. 实施指南：环境重置与执行

由于之前的错误操作导致目标仓库被数千个损坏文件污染，在执行上述脚本前，必须彻底清洗环境。

5.1 方案 A：仓库级重置（推荐）

适用于保留用户配置，仅重置数据的场景。

登录 Nexus Target 界面。
导航至 Administration -> Repositories。
删除污染的仓库（如 maven-releases）。
立即使用相同名称和配置重建该仓库。
无需重启容器。

5.2 方案 B：实例级重置（彻底）

适用于测试环境，彻底清除所有数据。

# 停止容器
docker stop nexus-target
# 物理删除挂载卷数据（高危操作，请二次确认路径）
rm -rf /opt/nexus/data/*
# 重启容器初始化
docker start nexus-target

6. 结论

在 DevOps 自动化脚本编写中，HTTP 状态码的检查与异常处理至关重要。对于二进制文件的迁移任务，“管道流”虽然优雅，但在缺乏错误熔断机制时极其脆弱。采用“落地校验”模式虽然增加了少量的磁盘 I/O 开销，但其提供的安全性和数据一致性保障是生产环境迁移所必须的。

后续建议：迁移完成后，建议在目标 Nexus 仓库中执行 Repair - Rebuild repository metadata 任务，以确保 Maven 索引文件的正确性。