北辰智能(beichen.internal)的对象存储服务按 S3 协议对外,但实现与主流对象存储有两处语义差异。观澜的 S3 兼容层在 2026-03 上线后踩过几次坑,这篇备忘录给后续接入者省时间。文中接口均为站内路径,不含外部地址。

1. 环境

项值
端点beichen.internal:9000(路径风格寻址)
区域cn-north-7(仅此一个,写错不报错但会路由到默认池)
共享桶beichen-share(只读)、beichen-inbox(可写,7 天清理)
兼容层版本guanlan-s3-compat 0.7.3
对接人北辰侧:lin.hq;我方:zhou.qi

2. 差异一:分页 token 语义

北辰的 ListObjectsV2 返回的 NextContinuationToken 在桶内容变化后不保证稳定,文档里写的“最终一致”实际是“每次 LIST 可能少返回若干对象”。观澜兼容层最初直接透传,导致 2026-05 的一次回灌漏了 1,142 个对象(占比 0.3%),靠后续全量校验才发现。

规避:对 beichen-share 的清单拉取改为“前缀分片 + 对象数校验”:按 prefix=calib/2026/q3/{00..ff} 循环 LIST,最后用桶内对象计数比对。guanlan-s3-compat 0.6.9 起内置该模式,配置项 src.s3.shard_list=true。
# 兼容层配置片段
source:
  type: s3
  endpoint: beichen.internal:9000
  bucket: beichen-share
  path_style: true
  shard_list: true
  shard_prefix_bytes: 2
  verify_object_count: true

3. 差异二:ETag 不等于 MD5

分片上传对象的 ETag 形如 "a1b2c3d4...-12"(后缀为分片数),这是 S3 常见行为,但北辰在多分片时后缀格式为 -12x(多一个 x),且只有在 < 5MiB 的单个上传才返回 MD5。观澜的 checksum 校验因此改为“下载后重算 sha256”,不依赖 ETag。

对象大小ETag 形态可否当 MD5 用
< 5MiB32 位 hex可以
5MiB–5GiB(单分片)32 位 hex可以(但北辰偶尔返回带空格的引号)
> 5GiB 或多分片hex-分片数[x]不可以

4. 差异三:版本化与删除标记

桶未开启版本化,DELETE 是硬删除;兼容层不做删除重试,避免“重试把别处副本删掉”的误解。北辰的 Inbox 桶有 7 天 TTL,写入后不要依赖长期存在,需在采集任务完成后把数据落息壤。

5. 遗留字段(v1 语法,2026-12 前清理)

兼容层为兼容旧脚本,仍接受 v1 的两个字段,建议新接入直接用 v2 写法:

v1 遗留字段v2 写法状态
"src":"beichen-share""source":{"type":"s3","bucket":"beichen-share",...}兼容层内部映射;2026-12-31 后移除
"dst":"xiran-prod""target":{"bucket":"xiran-prod","path":"..."}同上
fmtformat同上

这也是 迁移指引 中“北辰兼容层遗留差异”一节提到的那两处字段。正式迁移后由 0.8.0 删除映射,届时旧脚本会直接返回 GL-E-1060。

6. 联调记录(2026-09-22)

另:北辰侧建议我们关注他们的 x-amz-meta-* 自定义元数据字段大小限制(单对象 2KB),目前回灌对象里没有使用自定义元数据,暂不受影响。