2026-09-01 20:48:41 +08:00

2.6 KiB
Raw Blame History

ARCH-002 BOS 配置与对象契约

ARCH-002 在既有 ObjectStorage 契约后新增百度 BOS Adapter。业务服务仍只使用逻辑 key, 不知道 Bucket、Prefix、SDK 类型或凭据。Local Adapter 继续用于单元测试和本地开发;正式 默认切换留在 ARCH-005,避免在 Vector/Reranker 迁移完成前形成半套运行配置。

运行配置

配置只能由部署环境或 Secret Manager 注入,禁止把真实值写入 .env、镜像、日志、测试 快照或提交记录。

OBJECT_STORAGE_PROVIDER=bos
BOS_ENDPOINT=<已授权的 HTTP(S) BOS Origin>
BOS_ACCESS_KEY_ID=<运行时注入>
BOS_SECRET_ACCESS_KEY=<运行时注入>
BOS_BUCKET=<预创建的 Bucket>
BOS_KEY_PREFIX=knowledge-platform
BOS_TIMEOUT_SECONDS=30
  • Endpoint 必须是无用户名、密码、Path、Query 和 Fragment 的显式 HTTP(S) Origin;
  • Bucket 名必须符合 BOS 的小写字母、数字和连字符规则;
  • Prefix 可为空;非空时使用安全的 POSIX 相对 key,不允许空段、.、.. 或反斜杠;
  • 应用不会创建、删除或修改 Bucket 配置。

对象与不可变约束

canonical Document.storage_key 保存与 Provider 无关的逻辑 key,例如:

documents/<document_id>/<filename>

BOS Adapter 发起请求时才映射为:

<BOS_KEY_PREFIX>/documents/<document_id>/<filename>

上传先写入可回卷的临时流,以满足官方 SDK 对长度和 CRC 计算的要求;随后使用 If-None-Match: * 执行单对象 Put,服务端返回 412 时统一映射为 ObjectAlreadyExistsError。这样不会用“先 HEAD、再 PUT”的竞态检查破坏不可变来源约束。

下载返回 SDK 的流式 Response Body,由调用方负责关闭;存在性检查只发 HEAD,不下载正文。 404、412 和其他 SDK 异常映射为稳定的 Provider-neutral 错误,外层错误不包含 Endpoint、 SDK Response Body 或凭据。

权限与验收边界

运行身份只授予目标 Bucket/Prefix 所需的 Put、Get/Head 和 Delete 权限,不授予 Bucket 管理或 全局 List 权限。若生产策略要求来源不可物理删除,应在后续 Document Version/Retention 设计中单独处理;当前 Demo 的直接删除行为保持不变。

默认测试使用 Fake Client,不连接 BOS。真实连接、权限和临时对象清理统一在 ARCH-006 的 受控测试资源中验证,并且只允许使用轮换后的凭据。

官方参考: