ArtifactHub 追踪 OCI 注册表错误的排查与解决方案

在 ArtifactHub 平台上使用 Forgejo 托管 Helm 仓库时，开发者可能会遇到追踪错误问题。本文深入分析错误原因并提供解决方案。

错误现象分析

当 ArtifactHub 尝试追踪 OCI 注册表时，系统会向 /v2 端点发起请求。对于某些 Forgejo 实例（如 Codeberg），如果使用 OCI 注册表 URL 格式（oci://）但未正确配置，则可能出现 NAME_UNKNOWN 错误。

典型错误信息如下：

error getting repository remote digest: GET https://codeberg.org/v2/devxy/shinyproxy-helm/tags/list?n=1000: NAME_UNKNOWN:

根本原因

1. OCI 注册表路径配置错误：开发者可能错误地指定了 OCI 注册表路径，例如使用了 oci://codeberg.org/devxy/shinyproxy-helm 而非正确的 oci://codeberg.org/devxy/shinyproxy。

2. Forgejo 的 Helm 包类型限制：Forgejo 支持多种包类型，包括 "helm" 和 "container"。虽然两者都应符合 OCI 标准，但 "helm" 包类型可能不完全兼容 ArtifactHub 的 /v2 API 端点查询。

3. 注册表未初始化：当 Helm 图表尚未推送到 OCI 注册表时，系统会返回 NAME_UNKNOWN 错误。

解决方案

方案一：使用 HTTP API 替代 OCI 注册表

对于 Forgejo 实例，推荐使用 HTTP API 端点而非 OCI 注册表 URL。例如：

https://codeberg.org/api/packages/devxy/helm

这种方法绕过 OCI 注册表查询，直接通过 HTTP API 获取包信息，兼容性更好。

方案二：正确配置 OCI 注册表

如果坚持使用 OCI 注册表，需确保：

1. 路径格式正确：oci://codeberg.org/<用户名>/<仓库名>
2. 已通过 helm push 将图表推送到注册表
3. 使用 "container" 包类型而非 "helm" 类型（部分 Forgejo 实例对后者支持不完善）

方案三：验证注册表状态

通过以下步骤验证 OCI 注册表是否可用：

1. 使用 curl 或 helm CLI 测试 /v2 端点响应
2. 检查包是否已成功推送
3. 确认注册表服务正常运行

最佳实践建议

1. 优先使用 HTTP API：对于 Forgejo/Codeberg 实例，HTTP API 是最稳定的集成方式。

2. 测试环境验证：在正式发布前，先在测试环境验证注册表配置。

3. 监控追踪状态：定期检查 ArtifactHub 的追踪状态，及时发现并解决问题。

通过以上方法，开发者可以有效地解决 ArtifactHub 与 Forgejo 实例集成的追踪问题，确保 Helm 图表能够稳定地在平台上展示和分发。