64 lines
2.7 KiB
Markdown
64 lines
2.7 KiB
Markdown
# 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)
|