跳到主要内容

S3 存储完整性检查

验证悦库底层 S3 存储中文件块的完整性，包含下载检查（从数据库抽样块并校验）和上传检查（测试 S3 读写是否正常）两种模式。

所有 check 子命令均需先执行 opscli login。

子命令一览​

子命令只读说明
check s3 download✓从数据库抽取块记录，下载并校验 MD5 与块完整性
check s3 upload—上传测试块，校验 S3 读写正常后自动清理

下载检查​

从数据库中抽取文件块记录，实际下载每个块并验证其完整性（MD5 是否匹配、块是否存在）。

# 默认：随机抽取 1 个块
opscli check s3 download

# 随机抽取 N 个块
opscli check s3 download --n 100

# 按百分比抽样（如 5%）
opscli check s3 download --percent 5

# 检查全部块
opscli check s3 download --all

# JSON 格式输出
opscli check s3 download --n 50 --json
参数默认值说明
--n—随机抽取最多 N 个块
--percent—随机抽取约 X% 的块（如 5.5 表示 5.5%，最少 1 个）
--all—检查数据库中所有块
--json—JSON 格式输出结果

--n、--percent、--all 三者互斥，同时指定会报错。不指定任何参数时默认检查 1 个随机块。

输出示例：

[S3下载检查] 块总数: 15,832  本次抽样: 5
────────────────────────────────────────────────────────────
块名                              大小        结果
A1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6  1.2 MB      ok
9F8E7D6C5B4A3928170F1E2D3C4B5A69  512 KB      ok
0102030405060708090A0B0C0D0E0F10  3.5 MB      missing
AABBCCDDEEFF00112233445566778899  256 KB      corrupted
1234567890ABCDEF1234567890ABCDEF  8.0 MB      ok
────────────────────────────────────────────────────────────
汇总: 通过 3 / 丢失 1 / 损坏 1 / 共 5

存在 missing 或 corrupted 时，命令退出码为 1。

JSON 格式（--json）：

{
  "totalBlockCount": 15832,
  "sampledCount": 5,
  "ok": 3,
  "missing": 1,
  "corrupted": 1,
  "details": [
    { "block": "A1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6", "size": 1258291, "result": "ok" },
    { "block": "0102030405060708090A0B0C0D0E0F10", "size": 3670016, "result": "missing" },
    {
      "block": "AABBCCDDEEFF00112233445566778899",
      "size": 262144,
      "result": "corrupted",
      "expectedMD5": "AABBCCDDEEFF00112233445566778899",
      "actualMD5": "DEADBEEF001122334455667788990011"
    }
  ]
}

上传检查​

构造测试块上传至 S3，校验读写正常后自动清理，不影响正式数据。

# 默认：上传并检查 1 个测试块
opscli check s3 upload

# 上传 N 个测试块
opscli check s3 upload --n 3

# 指定每个测试块大小（字节）
opscli check s3 upload --n 3 --size 1048576

# 检查完成后保留测试块（供人工核查）
opscli check s3 upload --no-cleanup
参数默认值说明
--n1上传并校验的测试块数量
--size随机每个测试块大小（字节）；省略时每块随机（1 KB ~ 10 MB）
--no-cleanup—校验后保留测试块，不执行删除（输出中会标注对象键，请手动清理）
--json—JSON 格式输出

输出示例：

[S3上传检查] 计划上传: 3 个测试块
────────────────────────────────────────────────────────────
序号  块名（MD5）                         大小        结果
1     F1A2B3C4D5E6F7A8B9C0D1E2F3A4B5C6  1.5 MB      ok (已清理)
2     0011223344556677889900AABBCCDDEE  8.2 MB      ok (已清理)
3     AABBCCDDEEFF00112233445566778899  3.7 MB      ok (已清理)
────────────────────────────────────────────────────────────
汇总: 通过 3 / 上传失败 0 / 下载失败 0 / 损坏 0 / 共 3

常见问题​

  • 提示"请先执行 opscli login"：先执行 opscli login。
  • 下载检查发现 missing 块：该块在数据库有记录但 S3 中不存在，可能是 S3 数据丢失。请联系技术支持排查。
  • 下载检查发现 corrupted 块：块存在但内容损坏，MD5 不匹配。请联系技术支持排查。
  • 上传检查失败：S3 写入异常，可能是 S3 服务不可用或凭证配置错误，检查 S3 服务状态后重试。
  • --no-cleanup 留下的测试块：测试块保存在 S3 的 blocks/ 路径下，确认后可手动删除，不影响正式数据。