Linux oras 的 OCI Artifact 推送与 Helm chart 作为 artifact 存储

根本原因是目标仓库不支持oci artifact或未指定–manifest-type；helm chart需显式声明application/vnd.cncf.helm.chart.layer.v1+tar类型，且必须为helm package生成的.tgz文件，否则oras按默认镜像类型解析失败。

oras push 为什么报错 “failed to resolve reference”

根本原因通常是目标仓库不支持 OCI Artifact，或 oras 没指定正确的 --manifest-type。Helm chart 本身不是标准 OCI image，必须显式声明为 artifact 类型，否则 oras 默认按 application/vnd.oci.image.manifest.v1+json 尝试解析，而 Helm chart 的 index.yaml 或 Chart.yaml 不符合该结构，直接失败。

• 确认 registry 支持 OCI Artifact：Harbor ≥ 2.8、github Container Registry、azure Container Registry 都可以；docker Hub 不支持
• 推送前必须用 oras push --manifest-type application/vnd.cncf.helm.chart.layer.v1+tar 显式指定 Helm 层类型，不能省略
• 确保本地 chart 已打包为 .tgz 文件（用 helm package 生成），oras 不接受目录直推
• 错误信息如 failed to resolve reference: unexpected media type "" 就是没设 --manifest-type 的典型表现

如何把 Helm chart 正确打包并推送到 Harbor

关键在两步：先生成合规的 .tgz，再用匹配的 media type 推送。Harbor 对 artifact 的校验比普通镜像更严格，media type 必须与内容一致，否则拉取时 helm pull 会拒绝解析。

• 用 helm package mychart/ 生成 mychart-0.1.0.tgz，不要手动 tar 或改后缀
• 推送命令示例：oras push myharbor.example.com/project/mychart:0.1.0 mychart-0.1.0.tgz --manifest-type application/vnd.cncf.helm.chart.layer.v1+tar
• 如果 Harbor 启用了项目级权限，确保 Token 或用户名密码有 push 权限，否则报 unauthorized: authentication required
• 推送后可在 Harbor UI 的“Artifacts”标签页看到类型为 Helm Chart 的条目，而非 Image

helm pull 能否直接拉取 oras 推送的 artifact

可以，但依赖 Helm CLI 版本和 registry 配置。Helm v3.8+ 原生支持从 OCI registry 拉取 chart，但必须用完整 OCI 地址格式，且 registry 必须返回正确的 Content-Type 头。

• 拉取命令：helm pull oci://myharbor.example.com/project/mychart --version 0.1.0（注意是 oci:// 前缀）
• 若报 failed to do request: Head "https://.../v2/.../blobs/...": dial tcp: lookup ...: no such host，大概率是 helm 解析 registry 地址失败，检查是否漏了协议或拼写错误
• Harbor 需开启 content-trust 或至少允许非签名 artifact，否则某些版本 Helm 会静默跳过
• helm show values 和 helm install 对 OCI 源的行为与传统 repo 一致，无需额外插件

替代方案：用 helm chart repo vs oras 推送的取舍

OCI 方式更适合作为 CI/CD 流水线中的一环，尤其当团队已统一使用 Harbor 或 ACR；但若只是内部快速共享，传统 helm serve 或 GitHub Pages + helm repo index 更轻量。

• oras 推送后无法通过 helm search repo 发现，必须知道确切地址，缺少索引发现能力
• CI 中自动打 tag 并推送 OCI 是原子操作，避免了 helm repo update 的网络抖动风险
• 多个 chart 共享同一 registry 凭据，权限模型比 HTTP basic auth 更清晰
• 但调试困难：没有 helm repo list 对应的 oras list，得靠 registry UI 或 curl -H "Authorization: ..." https://reg/v2/_catalog 查

OCI artifact 的核心约束就一条：media type 必须真实反映内容，且 registry 必须认它。推错一次，后续拉取链就断了，重试前先 oras delete 干净再推。