Operations, development and architecture docs, the reference pages and the component READMEs were rewritten against the code: every documented variable exists, and the settings operators need (runtime image, Git service, listen addresses, Runner targets, single-tenant gateway and provisioner bindings) are documented. Gaps the docs used to present as working are now stated as such: IDE workspaces do not clone the project yet (FR-H2), and in Kubernetes mode dependency installs and image builds have no network path until an egress proxy and builder access exist. The Kubernetes README describes what the provisioner creates, what the Runner needs in a target namespace, and the cluster acceptance that is still outstanding. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
3.1 KiB
3.1 KiB
检查点产物存储
检查点中的 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)。
本地 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。
测试
npx vitest run tests/artifacts.test.ts
WF_ARTIFACT_INTEGRATION=1 npx vitest run tests/integration/artifacts.test.ts
集成测试把真实的 Git bundle 上传到本地 MinIO,验证数据库只保存引用、相同对象去重与存储计量、跨租户与非成员读取被拒绝、在新的 verifier 目录中恢复源码,以及对象内容损坏会被发现。它使用唯一的 integration-<uuid>/ 前缀,结束后只删除自己创建的对象与临时目录。