# ARCH-002 BOS 配置与对象契约 ARCH-002 在既有 `ObjectStorage` 契约后新增百度 BOS Adapter。业务服务仍只使用逻辑 key, 不知道 Bucket、Prefix、SDK 类型或凭据。Local Adapter 继续用于单元测试和本地开发;正式 默认切换留在 ARCH-005,避免在 Vector/Reranker 迁移完成前形成半套运行配置。 ## 运行配置 配置只能由部署环境或 Secret Manager 注入,禁止把真实值写入 `.env`、镜像、日志、测试 快照或提交记录。 ```text 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,例如: ```text documents// ``` BOS Adapter 发起请求时才映射为: ```text /documents// ``` 上传先写入可回卷的临时流,以满足官方 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 的 受控测试资源中验证,并且只允许使用轮换后的凭据。 官方参考: - [BOS Python SDK 上传文件](https://cloud.baidu.com/doc/BOS/s/yl5jfscvi) - [BOS 获取 Object](https://cloud.baidu.com/doc/BOS/s/Mk4xtzv8v) - [BOS 访问控制](https://cloud.baidu.com/doc/BOS/s/Tjwvysda9)