64 lines
2.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# ARCH-002 BOS 配置与对象契约
ARCH-002 在既有 `ObjectStorage` 契约后新增百度 BOS Adapter。业务服务仍只使用逻辑 key,
不知道 Bucket、Prefix、SDK 类型或凭据。ARCH-005 已将 BOS 设为正式运行默认值;Local
Adapter 继续用于单元测试和显式配置的本地开发。
## 运行配置
配置只能由部署环境或 Secret Manager 注入,禁止把真实值写入 `.env`、镜像、日志、测试
快照或提交记录。
```text
OBJECT_STORAGE_PROVIDER=bos
BOS_ENDPOINT=<已授权的 BOS Host 或 HTTP(S) 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 的 Host 或 HTTP(S) Origin;旧配置
的纯 Host 会在 Provider 边界强制规范化为 HTTPS,禁止沿用 SDK 的默认 HTTP;
- Bucket 名必须符合 BOS 的小写字母、数字和连字符规则;
- Prefix 可为空;非空时使用安全的 POSIX 相对 key,不允许空段、`.`、`..` 或反斜杠;
- 应用不会创建、删除或修改 Bucket 配置。
## 对象与不可变约束
canonical `Document.storage_key` 保存与 Provider 无关的逻辑 key,例如:
```text
documents/<document_id>/<filename>
```
BOS Adapter 发起请求时才映射为:
```text
<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 的
受控 test 资源中验证;凭据只允许运行时注入,不得写入仓库、日志或测试快照。
官方参考:
- [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)