# 检查点产物存储 检查点中的 Git bundle 保存在 S3 兼容的对象存储中。executor 与 verifier 只拿到自己被授权的检查点内容,拿不到对象存储凭据。PostgreSQL 记录租户、项目、运行、内容摘要、对象键、大小与可选的对象版本 ID;启用对象存储后不再在数据库中保存 base64 内容。 ## 写入与读取 - 上传前校验执行身份与 fencing token,写入对象存储后再次校验,然后才记录结果。 - 对象键包含租户、项目、运行范围与 SHA-256 内容地址;用 `If-None-Match: *` 条件写入避免覆盖,复用已有对象时读回并重新计算摘要。 - 下载时校验项目成员资格或执行身份对该运行的授权,在对象存储读取后再次校验权限,按记录的大小读取并核对摘要。不签发公开或预签名的对象地址。 - 存储后的检查点带 `gitBundleArtifactId`、去掉 `gitBundleBase64`;运行上下文接口在授权与完整性校验后才把 base64 内容填回。恢复时 runtime 再次校验 bundle、源 commit 与补丁摘要。 - 每个内容地址只计一次存储用量。数据库提交失败可能留下没有引用的对象,运维应按时间阈值清理未被引用的对象,且不能删除仍被检查点引用的对象。 ## 配置 | 变量 | 说明 | |---|---| | `S3_BUCKET` | 已存在的私有桶(不会自动创建) | | `S3_REGION` | 存储区域 | | `S3_ENDPOINT` | 可选的 S3 兼容端点;AWS 留空 | | `S3_ACCESS_KEY_ID`、`S3_SECRET_ACCESS_KEY`、`S3_SESSION_TOKEN` | 可选的服务凭据;不设置时使用 SDK 的工作负载身份链 | | `S3_ARTIFACT_PREFIX` | 对象前缀,默认 `wishforge` | | `S3_SSE` | `aws:kms`、`AES256`,或仅限开发的 `none` | | `S3_KMS_KEY_ID` | 使用 SSE-KMS 时必填 | 生产要求 `S3_SSE=aws:kms`、配置 KMS 密钥,自定义端点必须是 HTTPS;服务端会检查对象存储确认了 KMS 加密。桶策略应强制使用批准的 KMS 密钥并禁止公开访问(参见 [AWS SSE-KMS](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html))。 本地 Compose 中的 MinIO 地址为 `http://127.0.0.1:49000`、区域 `us-east-1`、桶 `wishforge-artifacts`,`npm run setup:local` 会写入对应配置。它使用真实的对象存储协议,但不代表生产的 KMS 配置。 没有配置对象存储时,开发模式下的检查点内联保存并标记为 `artifactStorage: inline-development`;生产模式拒绝没有持久化产物的检查点。bundle 只包含相对基线的增量提交,上限 4 MiB;检查点上传请求的 JSON 体上限为 16 MiB。 ## 测试 ```bash npx vitest run tests/artifacts.test.ts ``` ```bash WF_ARTIFACT_INTEGRATION=1 npx vitest run tests/integration/artifacts.test.ts ``` 集成测试把真实的 Git bundle 上传到本地 MinIO,验证数据库只保存引用、相同对象去重与存储计量、跨租户与非成员读取被拒绝、在新的 verifier 目录中恢复源码,以及对象内容损坏会被发现。它使用唯一的 `integration-/` 前缀,结束后只删除自己创建的对象与临时目录。