注意：说明：
注意：TCR 服务已于近期完成底层架构的全面升级。自 2026年5月22日起创建的实例均为新架构实例，具体变更如下：
一、操作场景
Helm Chart 与容器镜像存储于同一命名空间下，共享实例内的访问控制、安全扫描、同步复制等能力。这篇说说如何使用 Helm 客户端通过 OCI 协议管理 TCR 企业版实例中的 Helm Chart。
二、前提条件
在执行 Helm Chart 的推送和管理操作前，你需完成以下准备工作：
·已成功 创建 TCR 企业版实例。
·已成功 创建命名空间。
·如使用子账号进行操作，请参考 子账号权限配置，提前为子账号授予对应实例的操作权限。
·已安装 Helm 客户端，且版本要求 3.8.0 及以上（原生支持 OCI 协议，无需额外配置）。如使用 Helm 3.7 及以下版本，需通过设置环境变量 export HELM_EXPERIMENTAL_OCI=1 启用实验性 OCI 支持。
三、步骤 1：登录 TCR 实例
使用 helm registry login 命令登录 TCR 实例：
helm registry login <实例域名> –username <用户名> –password <密码>
参数说明：
| 参数 | 说明 |
| <实例域名> | TCR 实例的访问域名，例如 your-instance.tencentcloudcr.com |
| <用户名> | 登录用户名，详见下方 认证方式 说明。 |
| <密码> | 登录密码或 Token，详见下方 认证方式 说明。 |
认证方式：
| 认证方式 | 用户名格式 | 密码 / Token |
| 长期访问凭证（推荐） | 主账号 UIN 或 Token 用户名 | 实例访问凭证（Token） |
| 临时访问凭证 | 主账号 UIN | 临时密码（有效期 1 小时） |
| 服务账号 | ServiceAccount 用户名 | ServiceAccount 密码 |
说明：
推荐使用长期访问凭证（Registry Token）。你可在 TCR 控制台 > 实例管理 > 访问凭证中创建长期访问凭证，并获取对应的用户名和 Token。示例：
helm registry login your-instance.tencentcloudcr.com \\ –username 100987654321 \\ –password <your-token>
四、步骤 2：推送 Helm Chart
1. 在本地打包 Helm Chart：
helm package ./my-chart
执行成功后，将在当前目录生成 Chart 压缩包，例如 my-chart-1.0.0.tgz。
2. 将 Chart 推送至 TCR 实例的指定命名空间：
helm push my-chart-1.0.0.tgz oci://<实例域名>/<命名空间>
示例：
helm push my-chart-1.0.0.tgz oci://your-instance.tencentcloudcr.com/my-namespace
五、步骤 3：拉取 Helm Chart
从 TCR 实例拉取指定版本的 Helm Chart：
helm pull oci://<实例域名>/<命名空间>/<chart名称> –version <版本号>
示例：
helm pull oci://your-instance.tencentcloudcr.com/my-namespace/my-chart –version 1.0.0
六、步骤 4：安装 Helm Chart
直接从 TCR 实例将 Helm Chart 安装至 Kubernetes 集群：
helm install <release名称> oci://<实例域名>/<命名空间>/<chart名称> –version <版本号>
示例：
helm install my-release oci://your-instance.tencentcloudcr.com/my-namespace/my-chart –version 1.0.0
七、完整操作示例
以下为从登录到安装的完整操作流程：
# Step 1: 登录 TCR 实例helm registry login your-instance.tencentcloudcr.com –username 100987654321 –password <your-token># Step 2: 打包本地 Charthelm package ./my-chart# Step 3: 推送 Chart 至 TCRhelm push my-chart-1.0.0.tgz oci://your-instance.tencentcloudcr.com/my-namespace# Step 4: 拉取 Charthelm pull oci://your-instance.tencentcloudcr.com/my-namespace/my-chart –version 1.0.0# Step 5: 安装 Charthelm install my-release oci://your-instance.tencentcloudcr.com/my-namespace/my-chart –version 1.0.0
八、helm repo add 返回 404 Not Found
问题现象：
Error: looks like "https://your-instance.tencentcloudcr.com/chartrepo/my-namespace" is not a valid chart repositoryor cannot be reached: failed to fetch https://your-instance.tencentcloudcr.com/chartrepo/my-namespace/index.yaml : 404 Not Found
原因分析：
Harbor 2 实例默认不启用 ChartMuseum 组件，因此 /chartrepo/<namespace>/index.yaml 路径会返回 404。
解决方案：
请切换至 OCI 方式操作 Helm Chart：
# 登录helm registry login your-instance.tencentcloudcr.com –username <用户名> –password <密码># 推送helm push my-chart-1.0.0.tgz oci://your-instance.tencentcloudcr.com/<命名空间># 拉取helm pull oci://your-instance.tencentcloudcr.com/<命名空间>/<chart名称> –version <版本号># 安装helm install <release名称> oci://your-instance.tencentcloudcr.com/<命名空间>/<chart名称> –version <版本号>
九、Helm 版本不支持 OCI 协议
问题现象：
执行 helm push 或 helm pull 时，提示不支持 oci:// 协议。
解决方案：
·Helm 3.8+：原生支持 OCI 协议，无需额外配置。
·Helm 3.7 及以下：需设置环境变量以启用实验性 OCI 支持：
export HELM_EXPERIMENTAL_OCI=1
建议将 Helm 升级至 3.8 及以上版本，以获得完整的 OCI 支持能力。
十、推送时提示命名空间不存在
问题现象：
推送 Chart 时返回错误，提示项目或命名空间不存在。
解决方案：
推送前需确保 TCR 实例中已创建对应的命名空间（Namespace）。可通过以下步骤创建：
1. 登录 容器镜像服务控制台。
2. 选择目标实例，进入命名空间管理页面。
3. 单击新建，创建所需的命名空间。