腾讯云容器镜像服务TCR从零到一对接使用全解析

1. 初识腾讯云容器镜像服务TCR

在云原生技术快速迭代的当下，容器化部署已成为应用交付的标准方式。对于开发者和运维人员来说，如何在团队内部安全高效地共享和管理容器镜像，是云原生实践中绕不开的核心问题。自建Docker Registry不仅需要投入维护精力，还要面对存储扩容、网络优化、权限管理等一系列基础设施挑战。腾讯云容器镜像服务（Tencent Container Registry，TCR）正是为了解决这些痛点而生的企业级云原生制品托管服务。

作为腾讯云原生生态的重要组成部分，TCR提供了安全、独享、高性能的容器镜像和Helm Chart托管分发能力。通过与腾讯云容器服务TKE、Serverless架构、CODING DevOps等产品的深度集成，TCR可以无缝嵌入到从代码提交到应用部署的完整DevOps流水线中。下面我们将从零开始，一步步讲解如何对接并使用腾讯云容器镜像服务。

需要先登录腾讯云控制台，点击：腾讯云控制台，还没有账号，点击：注册后再关联，已有账号点击：登录后再关联

2. 个人版与企业版：如何选型

腾讯云TCR同时提供个人版和企业版两种服务层级，理解它们之间的差异，对于做出正确的选型决策至关重要。

个人版是面向个人开发者的免费服务，提供基础的云上镜像托管和分发功能，限额使用。由于所有个人版用户共享服务后端及数据存储资源，镜像托管和上传下载均存在配额限制，不提供SLA保障，适合个人学习测试或企业临时试用场景。

企业版则是面向企业客户的付费服务，分为基础版、标准版和高级版三种规格，提供相对独立的底层资源。以企业版基础版为例，它拥有更独立的数据存储、访问容灾和安全保障。随着规格提升，高级版还支持镜像签名验签、按需加载容器镜像以及同实例多地域就近访问等高级功能。从容量配额上看，企业版各规格也拉开明显差距：基础版支持50个命名空间和1000个镜像仓库，标准版升级到100个命名空间和3000个镜像仓库，高级版则提供500个命名空间和5000个镜像仓库的容量。

在选择时，可以遵循\"个人开发测试优先考虑个人版，生产环境和团队协作务必选择企业版\"的基本原则。尤其是有跨地域镜像分发、细粒度权限管理、生产级SLA保障等需求的企业用户，企业版是唯一合理的选择。

3. 账号准备与服务开通

在使用TCR之前，需要进行账号注册和实名认证。访问腾讯云官网，完成账号注册后按照指引完成实名认证，这是开通所有企业级服务的前提。

登录控制台后，在顶部搜索栏输入\"容器镜像服务\"，进入产品页面点击立即开通。如果是首次使用个人版，还需要特别注意一个关键步骤——初始化访问密码。在实例管理页面找到个人版实例卡片，点击\"初始化密码\"设置一个长度在6至32位之间的强密码，这个密码将作为后续Docker客户端登录的凭证。如果后续忘记密码，可以通过\"更多→重置登录密码\"重新设置。

对于企业版用户，开通流程略有不同，还需要额外做好以下准备工作：提前开通对象存储COS服务（企业版依赖COS桶存储镜像数据）、开通私有网络VPC及私有域解析PrivateDNS服务。在控制台开通TCR服务后，需要为账号授权对象存储、私有网络等相关资源的操作权限，确保实例创建流程正常执行。

在开通服务并完成授权后，即可开始创建TCR企业版实例。

4. 创建TCR企业版实例

进入容器镜像服务控制台的实例管理页面，点击\"新建\"按钮进入购买页，需要配置以下核心参数。

计费类型：支持包年包月和按量计费两种模式。包年包月适合长期稳定使用的生产环境，价格更优惠；按量计费适合测试、临时使用场景，按实际使用量计费，灵活度更高。

实例名称：自定义一个全局唯一的实例名称，购买后不可修改。这个名称将作为Registry服务的访问域名前缀，建议用公司或项目缩写命名，便于识别和管理。

实例地域：选择实例部署的地域，购买后同样无法更改。建议根据容器集群、业务服务器所在地域就近选择，可以显著降低网络延迟，提升镜像拉取和推送速度。

实例规格：包括基础版、标准版和高级版，不同规格对应不同的性能配额和并发能力，可以根据企业业务规模和镜像数量进行选择。

购买完成后，实例域名会自动生成，前缀与实例名一致。后续使用docker login命令登录实例时，需要用到这个域名。此时可以在控制台实例列表中看到已购买的实例，开始进行命名空间的创建和网络访问策略的配置。

5. 命名空间与镜像仓库管理

TCR企业版实例的两层资源管理结构是理解整个镜像管理流程的基础。

命名空间（Namespace）是实例内部的逻辑隔离单元，用于组织和管理镜像仓库，实现资源的分组和权限控制。一个企业版实例可以包含多个命名空间。建议根据团队结构或项目类型进行合理规划，例如按照部门划分：team-frontend、team-backend，或者按照项目名称划分：project-blog、project-ecommerce。在控制台左侧导航栏选择\"命名空间\"，点击新建，输入符合规范的名称（只支持小写字母、数字及短横线-的组合）即可完成创建。

镜像仓库（Repository）是命名空间下直接管理容器镜像的最小单位，归属于命名空间并从命名空间继承了公开、私有属性及安全扫描触发方式。单个镜像仓库可包含不同版本的容器镜像（即不同的Tag）。进入\"镜像仓库\"页面，点击新建，配置所属实例、命名空间、仓库名称以及简短描述等基本信息，即可完成仓库的创建。

镜像仓库同时也是TCR中进行权限管理的最小单位，实例管理员可以授予子用户对特定镜像仓库的管理或只读权限。例如，可以授权某个子账户仅能拉取某个特定镜像仓库中的镜像，但无法推送或删除该仓库中的镜像。这种细粒度的权限控制是企业级应用中非常实用的特性。

6. 网络访问配置：公网与内网访问

TCR企业版实例创建后，默认为私有状态，需要显式配置网络访问策略才能让Docker客户端访问实例并推送拉取镜像。

6.1 公网访问控制

在控制台左侧导航栏选择\"访问控制>公网访问\"，可以为实例开启公网访问入口。开启后，建议通过白名单功能限制访问来源，只放行特定的公网IP地址段，避免镜像数据被未授权的第三方访问。如果暂时不知道具体IP，测试阶段可以临时设置为0.0.0.0/0放通全部，但在生产环境中务必明确限制访问来源。

6.2 内网访问控制

在实际生产场景中，通过内网拉取容器镜像可以显著提升拉取速度，并有效避免公网带宽成本。TCR企业版支持将用户的私有网络接入到实例中，实现VPC内的内网访问。配置步骤如下：

登录容器镜像服务控制台，选择左侧导航栏中的\"访问控制>内网访问\"。点击\"接入私有网络\"，在弹出的\"新建内网访问链路\"窗口中配置以下信息：选择私有网络VPC及该VPC内可用子网。新建访问链路会占用子网内的一个内网IP地址，作为实例域名的内网解析目标地址。链路创建完成后，该私有网络下任意子网内的云服务器都可以通过这个链路访问TCR企业版实例。等待访问链路状态转变为\"链路正常\"且\"内网解析IP\"不为空，即表示内网访问链路创建成功。

关键提醒：实例的访问域名默认只配置了公网解析。接入指定私有网络后，虽然获得了内网解析IP，但域名在该VPC内并不会自动解析到内网IP上。需要在链路管理页面点击\"管理自动解析\"，使用私有域解析PrivateDNS服务配置内网域名解析，才能真正实现\"域名->内网IP->镜像数据\"的内网访问路径。

7. Docker登录、推送与拉取镜像

网络配置完成后，就可以在本地使用Docker客户端与TCR进行交互了。

7.1 获取访问凭证并登录

在使用Docker客户端与TCR交互前，需要使用凭证信息登录实例。不同类型的账号获取凭证的方式有所不同：

个人版：用户名填写腾讯云账号ID（可在账号信息页面获取），密码填写初始化时设置的密码。执行命令如下：

docker login --username=[YourTencentCloudAccountID] ccr.ccs.tencentyun.com

企业版：在控制台\"访问凭证>用户级账号\"中选择已创建的实例，点击\"生成临时登录指令\"，复制弹出窗口中的登录指令，直接在命令行中执行即可。示例命令如下：

sudo docker login demo-tcr.tencentcloudcr.com --username 100012345678 --password eyJhbGciOiJSUzI1NiIsImtpZCI6Ilt...]

执行后如果命令行显示\"Login Succeeded\"，即表示登录成功，本地Docker客户端已与TCR实例建立连接。需要注意的是，企业版的临时登录指令有有效期限，生产环境中建议使用长期访问凭证进行自动化集成。

7.2 推送镜像到TCR

登录成功后，就可以将本地镜像推送到TCR了。整个流程分为两个步骤：

第一步，给本地镜像打上TCR仓库地址的标签：

docker tag nginx:latest demo-tcr.tencentcloudcr.com/project-a/nginx:latest

其中nginx:latest是本地镜像名称和标签，demo-tcr.tencentcloudcr.com是TCR实例域名，project-a是命名空间名称，nginx是镜像仓库名称，latest是镜像版本号。按照实际的实例和命名空间信息替换即可。

第二步，执行推送命令：

docker push demo-tcr.tencentcloudcr.com/project-a/nginx:latest

推送完成后，即可在TCR控制台的对应镜像仓库中看到已推送的镜像及其版本信息。

7.3 拉取镜像

拉取镜像同样使用docker pull命令：

sudo docker pull demo-tcr.tencentcloudcr.com/project-a/nginx:latest

拉取后即可在本地运行测试：

docker run -d -p 80:80 demo-tcr.tencentcloudcr.com/project-a/nginx:latest

至此，与腾讯云TCR的基本交互流程已经完整走通。

8. TKE集群使用TCR插件内网免密拉取镜像

在实际的Kubernetes生产环境中，每次部署都需要拉取TCR中的私有镜像。传统做法是在K8s中创建imagePullSecret资源来保存访问凭证，但这种方式需要手动维护敏感信息，不够优雅。TCR企业版提供了更加便捷的免密拉取方案。

TCR插件是TKE集群的一个可选组件，安装后可以使TKE集群通过内网自动完成TCR企业版实例的镜像拉取，无需手动配置imagePullSecret，也不需要频繁更换凭证。具体操作流程如下：

第一步，将TKE集群所在VPC关联到TCR企业版实例。这一步实际上就是前面介绍的内网访问链路配置——在TCR控制台\"访问控制>内网访问\"中，选择TKE集群所在的VPC进行接入。

第二步，在TKE集群中安装TCR插件。登录TKE控制台，选择目标集群，进入\"组件管理\"页面，点击新建，在组件列表中找到TCR插件并安装。安装过程中会要求选择TCR实例并进行网络认证。

第三步，部署工作负载时直接使用镜像地址。当Pod YAML中的image字段指定TCR企业版实例中的镜像地址时，集群会自动通过内网拉取镜像，无需额外配置imagePullSecrets字段。整个过程对应用运维人员完全透明，大幅简化了K8s部署的复杂度。

9. 跨地域镜像分发：实例复制与实例同步

当企业的容器业务拓展到多个地域时，如何高效地将镜像分发到各地域并实现就近拉取，成为必须面对的问题。TCR企业版提供了两种跨地域镜像分发能力：实例复制和实例同步，两者各有所长，可以灵活组合使用。

实例复制允许为单个高级版实例在多个地域内配置副本（子实例），并提供就近访问能力。它的核心特点包括：多个地域共用同一个实例，可以使用统一的镜像仓库名称和版本号，保持容器配置的一致性；镜像Layer数据实时跨地域流式复制，实现单地域推送、多地域即时可拉取；最重要的是，在各个地域部署的K8s集群可以通过内网就近拉取同地域副本中的镜像，避免了跨地域公网流量的高昂成本。实例复制特别适合在全球多地域同时部署的出海业务。

实例同步则是在多个独立实例间自动按需同步指定镜像。同步规则可以根据镜像名称、Tag等条件进行精确匹配，当符合条件的镜像推送到源实例后，会自动触发同步流程将镜像复制到目标实例。实例同步还支持跨主账号进行同步，适合大型集团内部多个子公司账号间的镜像共享场景。

使用时需要注意，实例同步仅支持企业版实例，个人版由于架构限制完全不支持。此外，同步规则中SourceNamespace字段必须与源实例的命名空间严格一致且区分大小写，同时需要为系统账号配置命名空间只读权限和白名单访问。同步不是实时完成的，通常有30秒到3分钟不等的延迟，CI/CD流水线不应在镜像同步完成后再执行部署，而应设计为包含重试逻辑的拉取-重试模式。

10. 深度集成DevOps与CI/CD流水线

腾讯云TCR天然兼容主流的CI/CD工具链，从代码提交到镜像构建、推送、再到自动部署，整个流程可以完全自动化。下面以Jenkins为例，介绍如何实现自动化镜像构建和推送：

在Jenkins Pipeline中使用Docker CLI与TCR交互的基本流程如下：

pipeline {
    agent any
    environment {
        TCR_INSTANCE = 'demo-tcr.tencentcloudcr.com'
        NAMESPACE = 'project-a'
        REPO_NAME = 'myapp'
    }
    stages {
        stage('Build and Push Image') {
            steps {
                script {
                    sh "docker login -u $TCR_USER -p $TCR_PASSWORD $TCR_INSTANCE"
                    sh "docker build -t $TCR_INSTANCE/$NAMESPACE/$REPO_NAME:${env.BUILD_ID} ."
                    sh "docker push $TCR_INSTANCE/$NAMESPACE/$REPO_NAME:${env.BUILD_ID}"
                }
            }
        }
        stage('Deploy to TKE') {
            steps {
                sh "kubectl set image deployment/myapp myapp=$TCR_INSTANCE/$NAMESPACE/$REPO_NAME:${env.BUILD_ID} -n production"
            }
        }
    }
}

在GitLab CI/CD中，可以通过.gitlab-ci.yml文件实现类似的自动化流程：

stages:
  - build
  - deploy

build_image:
  stage: build
  script:
    - docker build -t tcr.tencentcloudcr.com/project/app:${CI_COMMIT_SHA} .
    - docker login -u $TCR_USER -p $TCR_PASSWORD tcr.tencentcloudcr.com
    - docker push tcr.tencentcloudcr.com/project/app:${CI_COMMIT_SHA}

除了与Jenkins、GitLab CI等第三方工具的集成外，TCR还可以与腾讯云CODING DevOps平台深度打通，提供云原生构建能力。依托腾讯云弹性资源，可以在CODING中配置代码提交后自动触发镜像构建，并将构建结果直接推送到TCR实例，最后通过TKE的Helm Chart自动更新K8s集群中的服务。

此外，TCR还提供了Webhook触发器功能。当镜像推送完成后，可以触发下游CI/CD工具（如Argo CD、Jenkins等）执行后续的部署任务，形成完整的从代码提交到应用上线的全自动化链路。

11. 安全与最佳实践

在使用TCR的过程中，以下安全实践和管理要点需要格外关注：

细粒度权限管理：生产环境中应避免使用主账号密钥直接进行操作，建议通过访问管理CAM创建具有最小必要权限的子账号。镜像仓库是权限管理的最小单位，可以精确控制到子账号对某个具体仓库的只读或读写权限。同时，通过命名空间级别的权限配置，可以实现团队间的资源隔离。

网络访问白名单：无论是公网访问还是内网访问，都应该配置严格的访问来源控制。公网访问开启后务必设置IP白名单，仅放行特定的公网IP段。内网访问链路创建后，也只有关联VPC内的云服务器才具备访问能力，不应额外放宽。

镜像安全扫描：TCR企业版内置了镜像漏洞扫描功能。在镜像仓库详情页的版本管理列表中，可以对指定镜像版本执行安全扫描，系统会自动检测镜像中的CVE漏洞并生成详细报告和安全级别评估。建议将漏洞扫描作为CI/CD流水线中的强制卡点：只有扫描结果符合安全标准的镜像才能被推送到生产环境的命名空间或被生产集群拉取使用。

镜像生命周期管理：定期清理旧版本镜像可以显著节约存储成本。可以在命名空间或镜像仓库级别配置生命周期策略，例如保留最近N个版本，或者删除创建时间超过一定天数的镜像版本。

日志审计与监控：TCR会记录所有的操作日志，包括镜像推送、拉取、仓库创建删除等，这些日志可以被收集到腾讯云日志服务CLS中进行审计分析。对于生产级服务，建议配置监控告警，关注实例的存储使用率、请求并发数等关键指标。

12. 常见问题与排障指南

问题1：实例拉取镜像失败，提示未授权
可能的原因包括未指定imagePullSecret、镜像地址配置错误、使用了错误的密钥或磁盘空间不足。在K8s场景中，首先检查Pod YAML文件中是否存在imagePullSecrets字段且字段值与TCR实例的访问凭证匹配。其次确认镜像地址格式是否正确，例如demo-tcr.tencentcloudcr.com/project-a/nginx:latest，确保实例域名、命名空间和仓库名称拼写无误。

问题2：内网访问配置后仍然失败
内网访问链路配置完成后，域名在内网中并不会自动解析，还需要在链路管理页面点击\"管理自动解析\"，配置实例域名在VPC内的专用内网解析。如果开启自动解析后仍然失败，检查PrivateDNS服务是否已开通。另外，需要确认TCR实例与访问客户端所在的VPC是否在同一地域，跨地域内网访问需要额外配置云联网。

问题3：镜像同步规则配置后没有生效
首先确认使用的是否是企业版实例，个人版不支持实例同步。其次检查同步规则中的源命名空间名称是否与源实例中的命名空间完全一致，包括大小写和短横线。还需要在源实例的白名单中添加TCR系统账号并配置命名空间只读权限。同步完成后，可以在TCR控制台的同步日志页面查看执行记录和错误信息，定位具体原因。

问题4：临时登录凭证过期导致自动化流水线失败
在CI/CD自动化场景中，不建议每次临时生成登录凭证。可以在控制台\"访问凭证>用户级账号\"中为企业版实例创建长期访问凭证（用户名和密码），并将凭证作为CI/CD系统的环境变量或机密存储，在构建脚本中引用这些变量进行docker login操作。同时建议定期轮换这些长期凭证，提升安全性。

问与答

Q1：腾讯云TCR个人版和企业版的主要区别是什么？
A1：个人版面向个人开发者，免费但限额使用，所有用户共享服务资源，不提供SLA保障；企业版面向企业客户，提供独立资源池、多种规格可选，支持细粒度权限控制、跨地域同步、镜像安全扫描等企业级功能。

Q2：如何通过内网访问TCR企业版实例？
A2：在TCR控制台“访问控制>内网访问”中，创建内网访问链路，选择目标VPC和子网。链路创建成功后，使用私有域解析PrivateDNS配置内网域名解析，即可从该VPC内的云服务器或TKE集群通过内网访问TCR实例。

Q3：TCR企业版实例的镜像访问凭证从哪里获取？
A3：在TCR控制台“访问凭证>用户级账号”中，选择目标实例后点击生成临时登录指令，复制指令直接执行即可登录。生产环境中可以创建长期访问凭证，保存用户名和密码用于自动化场景。

Q4：TCR与TKE集成实现免密拉取镜像需要哪些步骤？
A4：首先配置TCR与TKE集群所在VPC的内网访问链路，然后在TKE集群中安装TCR插件，安装时关联TCR实例即可。部署工作负载时无需配置imagePullSecret，集群会自动从TCR拉取镜像。

Q5：跨地域镜像同步和实例复制有什么区别？
A5：实例复制是为单个高级版实例在多个地域创建副本，实现实时流式复制和就近拉取，无需管理多个独立实例；实例同步是在多个独立实例之间配置同步规则，支持按需同步和跨账号同步，适合多业务环境隔离的场景。

Q6：在企业版实例中如何删除命名空间？
A6：在TCR控制台左侧导航栏选择命名空间，在命名空间列表中找到目标，点击右侧的删除即可。为避免误删重要数据，删除命名空间时需要二次确认。注意命名空间下的镜像仓库全部删除后，命名空间才可以被删除。