wishforge-ide/docs/reference/artifact-storage.md
eust-w b38db08eeb docs: align documentation with the code and write it in Chinese
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>
2026-10-19 18:01:39 +08:00

3.1 KiB
Raw Blame History

检查点产物存储

检查点中的 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>/ 前缀,结束后只删除自己创建的对象与临时目录。