TCR跨地域同步仅支持企业版，个人版因架构限制完全不支持；需新建企业版实例并迁移数据，同步规则中源registry和namespace须严格匹配且区分大小写，同时必须为系统账号tcr-sync@tencent.com配置白名单及命名空间只读权限。
TCR跨地域同步必须用企业版，个人版不支持
腾讯云容器镜像服务（TCR）的跨地域同步功能仅对企业版开放，个人版控制台里根本看不到“同步规则”入口，API 调用也会直接返回 UnsupportedOperation 错误。这不是权限没开，是底层架构就不支持——个人版所有资源绑定单一地域，连跨地域拉取都要手动配置公网地址，更别说自动同步了。
实操建议：
- 确认当前实例类型：在 TCR 控制台右上角看是否显示「企业版」，或调用
DescribeInstancesAPI 查看InstanceType字段值是否为enterprise - 升级路径只有新建企业版实例 + 迁移命名空间，无法原地升级；旧个人版仓库需先推送到新实例，再配置同步
- 企业版按月计费，同步本身不额外收费，但目标地域产生的存储和流出流量会计入对应地域账单
同步规则里 registry 和 namespace 必须严格匹配源端
创建同步规则时填的 SourceRegistry 和 SourceNamespace 不是“你想同步哪个”，而是“你授权 TCR 从哪读”。它必须和源实例的公网访问地址、命名空间完全一致，少一个斜杠、多一个下划线都会导致同步失败，日志里只显示模糊的 SyncFailed: failed to list manifest。
常见错误现象：
- 源实例是
ccr.ccs.tencentyun.com/your-ns，却填成ccr.ccs.tencentyun.com/your-ns/（末尾斜杠） - 源命名空间含大写字母或中划线，但同步规则里用了小写或下划线（TCR 命名空间区分大小写，且只允许小写字母、数字、短横线）
- 用了内网地址如
ccr-vpc.gz.tencentcloudapi.com—— 同步走的是 TCR 后台服务间通信，不走客户 VPC，必须填公网 registry 地址
镜像 tag 同步有延迟，且不触发自动重试
TCR 同步不是实时的，通常有 30 秒到 3 分钟不等的延迟，尤其在源端高频推送时。更关键的是：如果某次同步失败（比如目标地域临时不可写），TCR 不会自动重试，也不会告警，那个 tag 就永远卡在“未同步”状态，后续同名 tag 推送也不会覆盖或补发。
使用场景与应对：
- CI/CD 流水线依赖目标地域镜像就绪？别等同步完成再部署，改用
docker pull加重试逻辑，或监听 TCR 的 CMQ 事件通知（需单独开通） - 需要强一致性？放弃自动同步，改用脚本定时调用
DescribeImageLifecycleGlobal检查同步状态，失败则手动触发CreateImageSyncRule（注意：重复创建同名规则会报错，得先DeleteImageSyncRule） - 同步列表里看到 tag 状态长期为
Pending，大概率是源镜像被删了，或目标地域配额超限（检查DescribeNamespaces返回的StorageSize）
私有镜像同步失败时，ServiceAccount 权限容易被忽略
跨地域同步本质是 TCR 后台服务以某个系统身份去源实例拉取镜像。如果源实例启用了「仅允许白名单账号访问」或「开启命名空间级鉴权」，而该系统账号没被添加进白名单，就会静默失败，控制台只显示 SyncFailed: unauthorized，连具体是哪个账号都没提示。
排查要点：
- 源实例的「访问控制」→「白名单管理」里，必须添加 TCR 系统账号：
tcr-sync@tencent.com（这是官方文档明确写的，不是示例邮箱） - 如果源命名空间开启了「镜像拉取权限控制」，需在「命名空间权限」里给
tcr-sync@tencent.com分配ReadOnly权限 - 这个账号对每个源命名空间都要单独授权，不能只加在实例级别；且授权后不会立即生效，一般要等 2–5 分钟
跨地域同步真正卡住的地方，往往不在网络或配置，而在这个藏得深、文档提得淡的账号授权上。漏掉一次，所有同步都停摆，还找不到原因。
