北辰智能(beichen.internal)的对象存储服务按 S3 协议对外,但实现与主流对象存储有两处语义差异。观澜的 S3 兼容层在 2026-03 上线后踩过几次坑,这篇备忘录给后续接入者省时间。文中接口均为站内路径,不含外部地址。
| 项 | 值 |
|---|---|
| 端点 | beichen.internal:9000(路径风格寻址) |
| 区域 | cn-north-7(仅此一个,写错不报错但会路由到默认池) |
| 共享桶 | beichen-share(只读)、beichen-inbox(可写,7 天清理) |
| 兼容层版本 | guanlan-s3-compat 0.7.3 |
| 对接人 | 北辰侧:lin.hq;我方:zhou.qi |
北辰的 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
分片上传对象的 ETag 形如 "a1b2c3d4...-12"(后缀为分片数),这是 S3 常见行为,但北辰在多分片时后缀格式为 -12x(多一个 x),且只有在 < 5MiB 的单个上传才返回 MD5。观澜的 checksum 校验因此改为“下载后重算 sha256”,不依赖 ETag。
| 对象大小 | ETag 形态 | 可否当 MD5 用 |
|---|---|---|
| < 5MiB | 32 位 hex | 可以 |
| 5MiB–5GiB(单分片) | 32 位 hex | 可以(但北辰偶尔返回带空格的引号) |
| > 5GiB 或多分片 | hex-分片数[x] | 不可以 |
桶未开启版本化,DELETE 是硬删除;兼容层不做删除重试,避免“重试把别处副本删掉”的误解。北辰的 Inbox 桶有 7 天 TTL,写入后不要依赖长期存在,需在采集任务完成后把数据落息壤。
兼容层为兼容旧脚本,仍接受 v1 的两个字段,建议新接入直接用 v2 写法:
| v1 遗留字段 | v2 写法 | 状态 |
|---|---|---|
"src":"beichen-share" | "source":{"type":"s3","bucket":"beichen-share",...} | 兼容层内部映射;2026-12-31 后移除 |
"dst":"xiran-prod" | "target":{"bucket":"xiran-prod","path":"..."} | 同上 |
fmt | format | 同上 |
这也是 迁移指引 中“北辰兼容层遗留差异”一节提到的那两处字段。正式迁移后由 0.8.0 删除映射,届时旧脚本会直接返回 GL-E-1060。
ListObjectsV2 分页行为:桶内新增对象后旧 token 结果不稳定,北辰侧确认“已知,短期不改”;-12x 变体;北辰文档未写,记录在此;beichen-inbox 的 TTL 从最后一次写入算,不续期;另:北辰侧建议我们关注他们的 x-amz-meta-* 自定义元数据字段大小限制(单对象 2KB),目前回灌对象里没有使用自定义元数据,暂不受影响。