说明：
TCR 服务已于近期完成底层架构的全面升级。自 2026年5月22日起创建的实例均为新架构实例，具体变更如下：
可用性提升：新实例支持在制品清理周期内持续接收镜像推送，消除运维窗口期的业务阻断风险。
AI 能力增强：上线 AI Skill 存储与 AI 制品存储两大新特性。该功能目前处于灰度期，采用白名单机制，如需使用请 提交工单 申请开通。
Helm 交互调整：新实例对 Helm Chart 的底层存储格式进行了重构。为确保兼容性，请统一使用 Helm 客户端命令行进行 Chart 推送操作。
操作场景
容器镜像服务 TCR 企业版支持托管 Helm Chart，满足用户对云原生应用制品的安全托管与高效分发需求。TCR 企业版基于 Harbor 2 内核，原生支持通过 OCI（Open Container Initiative）协议存储 Helm Chart，用户可通过 Helm 客户端实现 Chart 的推送、拉取及安装等操作。
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 <密码>
参数说明：
认证方式：
认证方式 | 用户名格式 | 密码 / 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
注意：
推送前请确保目标命名空间已在 TCR 实例中创建。
Chart 包文件名中的版本号将作为 Chart 的版本标识。
步骤 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. 单击新建，创建所需的命名空间。
