> For the complete documentation index, see [llms.txt](https://tccli-agent.gitbook.io/tccli/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tccli-agent.gitbook.io/tccli/v2/tcr-rong-qi-jing-xiang-fu-wu/troubleshooting.md).

# 故障排查

> 官方文档：[产品服务层级与容量限制](https://cloud.tencent.com/document/product/1141/104731) · [个人版常见问题](https://cloud.tencent.com/document/product/1141/57780)

## 从这里开始

```bash
tccli tcr DescribeInstances --region <REGION>
# expected: { "TotalCount": "≥0", "Registries": [...] }
```

正常输出： 每个实例 `Status: "Running"`。任何非 Running 状态（`Pending`/`Deploying`/`Deleting`/异常）或实例完全不出现在列表中，见 [状态机](/tccli/v2/tcr-rong-qi-jing-xiang-fu-wu/states.md) 或下方。

## 诊断工具箱

| 命令                                                                                                                    | 检查什么            | 何时使用                 |
| --------------------------------------------------------------------------------------------------------------------- | --------------- | -------------------- |
| `tccli tcr DescribeInstances --Registryids '["<REGISTRY_ID>"]'`                                                       | 实例状态 + 域名 + 规格  | 怀疑实例异常时首先执行          |
| `tccli tcr DescribeExternalEndpointStatus --RegistryId "<REGISTRY_ID>"`                                               | 公网访问开关状态        | docker login 超时      |
| `tccli tcr DescribeInternalEndpoints --RegistryId "<REGISTRY_ID>"`                                                    | 内网 VPC 链接状态     | VPC 内 docker pull 失败 |
| `tccli tcr DescribeInstanceToken --RegistryId "<REGISTRY_ID>"`                                                        | Token 列表 + 启用状态 | docker login 认证失败    |
| `tccli tcr DescribeSecurityPolicies --RegistryId "<REGISTRY_ID>"`                                                     | 公网白名单列表         | 403 Forbidden        |
| `tccli tcr DescribeNamespaces --RegistryId "<REGISTRY_ID>"`                                                           | 命名空间列表          | 确认仓库是否存在             |
| `tccli tcr DescribeRepositories --RegistryId "<REGISTRY_ID>"`                                                         | 仓库列表 + 详情       | push/pull 找不到仓库      |
| `tccli tcr DescribeImages --RegistryId "<REGISTRY_ID>" --NamespaceName "<NAMESPACE>" --RepositoryName "<REPOSITORY>"` | 镜像 Tag 列表       | 确认镜像是否推送成功           |

## 常见问题

### docker login 失败: unauthorized

**可能原因**： Token 不存在、已禁用、或已过期。

**诊断**：

```bash
tccli tcr DescribeInstanceToken --region <REGION> --RegistryId "<REGISTRY_ID>"
# expected: 列出所有 Token。检查目标 Token 的 Enabled 状态和过期时间
```

如果 Token 被禁用 (`Enabled: false`) 或已过期:

**修复**：

```bash
# 方案 1: 重新启用 Token
tccli tcr ModifyInstanceToken --region <REGION> \
  --RegistryId "<REGISTRY_ID>" \
  --TokenId "<TOKEN_ID>" \
  --Enable true
# expected: exit 0

# 方案 2: 创建新临时 Token（temp 默认 1 小时过期；长期用 longterm）
tccli tcr CreateInstanceToken --region <REGION> \
  --RegistryId "<REGISTRY_ID>" \
  --TokenType temp \
  --Desc "Replacement Token"
# expected: {"Username":"<USERNAME>","Token":"<TOKEN>","ExpTime":<EXP_TIME>}
# ⚠️ 临时 Token 1 小时过期；长期凭证用控制台或服务账号
```

**验证**：

> docker CLI（镜像传输，非 tccli；TCCLI 不提供 docker daemon 操作能力）。不要把 Token 写入命令行字面量；隐藏读取后仅通过 stdin 传给 Docker。

```bash
read -r -s -p "TCR Token: " TCR_TOKEN
printf '\n'
printf '%s' "$TCR_TOKEN" | docker login <REGISTRY_DOMAIN> --username <USERNAME> --password-stdin
unset TCR_TOKEN
# expected: Login Succeeded
```

Docker 可能把登录凭证写入 `~/.docker/config.json`。生产环境配置 Docker credential helper；临时排障完成后执行 `docker logout <REGISTRY_DOMAIN>`，并删除或禁用不再使用的临时 Token。

### docker login 超时或连接被拒绝

**可能原因**： 客户端选择了错误的网络路径、目标端点未就绪，或网络无法访问 Registry 域名。

**诊断与分流**：

#### 1. VPC 内客户端先检查内网接入链路

```bash
tccli tcr DescribeInternalEndpoints --region <REGION> --RegistryId "<REGISTRY_ID>"
# expected: InternalEndpoint 列表中目标 VPC 链路处于可用状态；它是内网接入证据，不是 --docker-server 域名
```

#### 2. 仅当客户端确需从公网访问时检查公网端点

```bash
tccli tcr DescribeExternalEndpointStatus --region <REGION> --RegistryId "<REGISTRY_ID>"
# expected: Status="Opened"
```

#### 3. 使用实例的 Registry 域名检查所选网络路径

```bash
curl -v https://<REGISTRY_DOMAIN>/v2/
# expected: HTTP 401 (未授权但可达) 而不是连接超时
```

**修复**：

* VPC 内客户端：优先修复 `DescribeInternalEndpoints` 显示的 VPC 内网链路、路由和 DNS，不开启公网端点；Docker 仍使用实例的 Registry 域名。
* 公网客户端：仅在无法通过 VPC、专线或 VPN 访问时开启公网端点，并立即把访问范围限制为客户端固定出口 IP 的 `/32`。

```bash
# 公网路径：开启端点
tccli tcr ManageExternalEndpoint --region <REGION> \
  --RegistryId "<REGISTRY_ID>" \
  --Operation Create
# expected: exit 0

# 端点 Opened 后，仅放行当前固定出口 IP
tccli tcr CreateSecurityPolicy --region <REGION> \
  --RegistryId "<REGISTRY_ID>" \
  --CidrBlock "<YOUR_EGRESS_IP>/32" \
  --Description "Temporary troubleshooting access"
# expected: exit 0
```

不要使用 `0.0.0.0/0`。公网排障完成后删除临时白名单，并用 `ManageExternalEndpoint --Operation Delete` 关闭不再需要的公网端点。防火墙或代理环境还需核对客户端到 Registry 域名的 443 端口。

**验证**：

```bash
# 内网路径：目标 VPC 链路仍处于可用状态
tccli tcr DescribeInternalEndpoints --region <REGION> --RegistryId "<REGISTRY_ID>"

# 公网路径：端点已开启，且白名单仅含所需出口 CIDR
tccli tcr DescribeExternalEndpointStatus --region <REGION> --RegistryId "<REGISTRY_ID>"
tccli tcr DescribeSecurityPolicies --region <REGION> --RegistryId "<REGISTRY_ID>"
# expected: 公网 Status="Opened"；SecurityPolicySet 含 "<YOUR_EGRESS_IP>/32"

curl -s -o /dev/null -w "%{http_code}" https://<REGISTRY_DOMAIN>/v2/
# expected: 401 (端点可达)
```

### docker push/pull 返回 403 Forbidden

**可能原因**： 当前 IP 不在公网访问白名单中，或仓库权限不足。

**诊断**：

#### 0. 先确认公网端点

```bash
# Closed 时 DescribeSecurityPolicies 报 ResourceNotFound: Failed to get security group id
tccli tcr DescribeExternalEndpointStatus --region <REGION> --RegistryId "<REGISTRY_ID>"
# expected: Status=Opened；若 Closed → 先 ManageExternalEndpoint --Operation Create
```

#### 1. 检查白名单

```bash
tccli tcr DescribeSecurityPolicies --region <REGION> --RegistryId "<REGISTRY_ID>"
# expected: SecurityPolicySet 列表；Closed 端点 → ResourceNotFound（非「无白名单」）
```

#### 2. 检查当前公网 IP

```bash
curl -s ifconfig.me
# expected: 你的公网 IP
```

对比: IP 是否在白名单中的某个 CidrBlock 范围内

**修复**：

```bash
# 添加当前 IP 到白名单
tccli tcr CreateSecurityPolicy --region <REGION> \
  --RegistryId "<REGISTRY_ID>" \
  --CidrBlock "<YOUR_IP>/32" \
  --Description "Added via troubleshooting"
# expected: exit 0
```

**验证**：

> docker CLI（镜像传输，非 tccli；TCCLI 不提供 docker daemon 操作能力）

```bash
docker pull <REGISTRY_DOMAIN>/<NAMESPACE_NAME>/<REPOSITORY_NAME>:<TAG>
# expected: 镜像拉取成功，不再 403
```

### 实例状态不是 Running

**可能原因**： 实例初始化未完成、欠费、或实例异常。

**诊断**：

```bash
tccli tcr DescribeInstances --region <REGION> --Registryids '["<REGISTRY_ID>"]'
# expected: 查看 Status 和 DescribeInstanceStatus 中的 Conditions 明细
```

**修复**：

| 状态                      | 动作                                                                    |
| ----------------------- | --------------------------------------------------------------------- |
| `Pending` / `Deploying` | 等待 3–5 分钟，创建过渡态（官方 `Registry.Status` **无** `Creating` 字面值）            |
| `Deleting`              | 实例正在删除，等待完成                                                           |
| 非 `Running` 且非过渡态       | 查 `DescribeInstanceStatus` 的 `Conditions[].Reason`；欠费则充值，超 1 小时未恢复提工单 |

**验证**：

```bash
tccli tcr DescribeInstances --region <REGION> --Registryids '["<REGISTRY_ID>"]'
# expected: Status: "Running"
```

### 镜像推送成功但 DescribeImages 查不到

**可能原因**： 推送到了错误的命名空间或仓库。

**诊断**：

```bash
# 列出所有命名空间和仓库
tccli tcr DescribeNamespaces --region <REGION> --RegistryId "<REGISTRY_ID>"
tccli tcr DescribeRepositories --region <REGION> --RegistryId "<REGISTRY_ID>"
# expected: 找到你推送的目标 Repository
```

**修复**：

> docker CLI（镜像传输，非 tccli；TCCLI 不提供 docker daemon 操作能力）

```bash
# 用正确的路径重新推送
docker tag <IMAGE_NAME> <REGISTRY_DOMAIN>/<CORRECT_NAMESPACE>/<CORRECT_REPOSITORY>:<TAG>
docker push <REGISTRY_DOMAIN>/<CORRECT_NAMESPACE>/<CORRECT_REPOSITORY>:<TAG>
# expected: push 成功
```

**验证**：

```bash
tccli tcr DescribeImages --region <REGION> \
  --RegistryId "<REGISTRY_ID>" \
  --NamespaceName "<NAMESPACE>" \
  --RepositoryName "<REPOSITORY>"
# expected: ImageInfoList 含目标 ImageVersion（字段名 ImageVersion，非 Tag）
```

## 升级

如果以上步骤无法解决问题，收集以下信息:

#### 1. 实例信息

```bash
tccli tcr DescribeInstances --region <REGION> --Registryids '["<REGISTRY_ID>"]' > tcr-info.json
# expected: 文件写入成功，JSON 含 Registries[]
```

#### 2. 访问配置

```bash
tccli tcr DescribeExternalEndpointStatus --region <REGION> --RegistryId "<REGISTRY_ID>" > tcr-endpoint.json
# expected: 文件写入成功，含 Status（Opened/Closed）
tccli tcr DescribeSecurityPolicies --region <REGION> --RegistryId "<REGISTRY_ID>" > tcr-policies.json
# expected: 文件写入成功；公网 Closed 时可能 ResourceNotFound
```

#### 3. 操作日志 (CloudAudit)

```bash
# StartTime/EndTime 为 Unix 秒级时间戳（必填）；窗口按排查需要自定
START_TIME=<START_UNIX_TS>
END_TIME=<END_UNIX_TS>
tccli cloudaudit LookUpEvents \
  --StartTime "$START_TIME" --EndTime "$END_TIME" \
  --LookupAttributes '[{"AttributeKey":"ResourceName","AttributeValue":"<REGISTRY_ID>"}]' \
  --MaxResults 50
# expected: exit 0；Events[] 含近期与该 ResourceName 相关的操作（空列表表示窗口内无命中，非失败）
```

| 占位符                                 | 含义          | 如何获取                                        |
| ----------------------------------- | ----------- | ------------------------------------------- |
| `<START_UNIX_TS>` / `<END_UNIX_TS>` | 查询起止 Unix 秒 | 本机 `date +%s` 与回溯窗口；须 `StartTime < EndTime` |
| `<REGISTRY_ID>`                     | TCR 实例 ID   | 失败请求或 `DescribeInstances` 返回的 `RegistryId`  |

#### 4. 失败操作的 RequestId

```bash
# 从之前失败的 API 响应中获取
```

提交到: [腾讯云工单系统](https://console.cloud.tencent.com/workorder)，附带以上文件和 RequestId。

## 下一步

* [实例状态机](/tccli/v2/tcr-rong-qi-jing-xiang-fu-wu/states.md) — `Pending`/`Deploying`/`Running`/`Deleting` 等官方 Status 枚举
* [错误码](/tccli/v2/tcr-rong-qi-jing-xiang-fu-wu/error-codes.md) — docker CLI 错误（`unauthorized`/`denied`）+ TCR 特有码
* [访问控制](/tccli/v2/tcr-rong-qi-jing-xiang-fu-wu/manage-1.md) — Token/白名单/VPC 内网配置
* [推送拉取镜像](/tccli/v2/tcr-rong-qi-jing-xiang-fu-wu/push-pull.md) — 完整 push/pull 链路与失败模式
* [访问管理](/tccli/v2/tcr-rong-qi-jing-xiang-fu-wu/index-1/manage-access.md) — 公网/内网端点开启


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://tccli-agent.gitbook.io/tccli/v2/tcr-rong-qi-jing-xiang-fu-wu/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.