腾讯云资源管理

技能文档

---
name: tencentcloud-infra
title: 腾讯云资源管理
category: 开发工具
description: 通过 tccli 统一管理腾讯云全产品云资源，覆盖轻量应用服务器、CVM、云硬盘、COS、VPC、DNSPod、SSL 证书、CAM、监控、TAT、域名与云审计的查询、巡检、部署与挂载等操作。当用户提到腾讯云、轻量服务器、安全组、域名解析、SSL证书、云硬盘、建站部署、云资源巡检等场景时触发。
---

# 腾讯云资源管理工具

你对腾讯云 API 参数、tccli 命令格式、产品限制数值的知识可能已过时。
**优先通过 `tccli --help` 和实际查询获取最新信息，而非依赖预训练知识。**

## 检索源

| 来源 | 如何检索 | 用于 |
|------|---------|------|
| tccli 内置帮助 | `tccli <服务> <操作> --help` | 最新参数说明、必填/选填字段 |
| 腾讯云 API 文档 | `https://cloud.tencent.com/document/api` | API 详细参考 |
| TCCLI 官方文档 | `https://cloud.tencent.com/document/product/440` | 安装、配置、使用指南 |
| CAM 权限文档 | `https://cloud.tencent.com/document/product/598` | 权限策略和子用户管理 |
| 云审计文档 | `https://cloud.tencent.com/document/product/629` | 操作记录和审计 |

当参考文档与 `tccli --help` 输出不一致时，**以 tccli --help 为准**。
这尤其重要于：API 参数名称、必填/选填字段、支持的地域列表、产品限制数值。

## Scope

本 Skill 覆盖**腾讯云全产品资源查询和管理** — 通过 TCCLI 操作云上资源。

**完整覆盖的产品**：Lighthouse（轻量应用服务器）、CVM、CBS、VPC、DNSPod、SSL、CAM、Monitor、TAT、Domain、CloudAudit 等。

> ⚡ **优先级说明**：本 Skill 已包含 Lighthouse 的**完整操作能力**（实例管理、防火墙规则、快照、镜像、流量包、密码重置、应用部署等），无需加载其他 Lighthouse 专用 Skill。如果存在 `tencentcloud-lighthouse-skill` 等单产品 Skill，**应优先使用本 Skill**，因为本 Skill 提供更完整的跨产品联动能力（如 Lighthouse + DNS + SSL + 监控）。

**不包括**：本地开发、代码编写、CI/CD 流程 → 使用其他 Skill。


### 步骤2：确认运行环境（获取当前实例 ID）

> 🔓 **无需 tccli，无需登录**：此脚本直接通过腾讯云内网元数据服务获取实例 ID，不依赖 tccli 工具，也不需要任何凭证或登录操作。

> ⛔ **获取当前实例 ID 必须使用 `scripts/whoami.sh`，禁止使用 tccli 命令，也禁止自行拼接 curl 元数据接口**。
> - tccli 需要登录凭证且无法直接获取当前机器的实例 ID
> - 自行 curl `metadata.tencentyun.com` 元数据接口需要处理 Lighthouse/CVM 两种不同的解析逻辑，容易出错
> - `whoami.sh` 已封装了完整的判断逻辑，是唯一正确的方式

如果当前运行环境是腾讯云服务器（CVM / Lighthouse），可以使用 `scripts/whoami.sh` 脚本自动获取当前实例 ID：

```bash
# ✅ 唯一正确的方式：使用 whoami.sh 脚本
bash scripts/whoami.sh
```

```bash
# ❌ 错误：不要用 tccli 获取当前实例 ID
# tccli cvm DescribeInstances ...  ← 需要登录，且无法定位「当前机器」
```

```bash
# ❌ 错误：不要自行拼接 curl 元数据接口
# curl http://metadata.tencentyun.com/meta-data/instance-id  ← Lighthouse 实例会返回错误的 ID
# curl http://metadata.tencentyun.com/meta-data/instance-name | grep ...  ← 解析逻辑不完整
```

**输出示例**：
```bash
# Lighthouse 实例
$ bash scripts/whoami.sh
lhins-dtx9e79f

# CVM 实例
$ bash scripts/whoami.sh
ins-0gs7gr9q
```

> 💡 **展示提示**：脚本输出就是完整的实例 ID（如 `lhins-dtx9e79f`），直接告诉用户即可，确保 ID 完整展示在一行内。

> 💡 **地域信息**：如需获取当前实例所在地域，可通过元数据接口获取：`curl -s http://metadata.tencentyun.com/meta-data/placement/zone`，返回值如 `ap-shanghai-2`，去掉末尾的可用区编号（最后的 `-数字`）即为地域（如 `ap-shanghai`）。

> 💡 **提示**：此脚本仅在腾讯云服务器内网环境中有效，依赖腾讯云元数据服务。在非腾讯云环境中执行会因无法访问元数据接口而失败。


## 技能工作流

### 步骤1：安装检查与凭证配置

```bash
tccli --version    # 应显示版本号（如 3.1.55.1+）
```

如未安装：
```bash
pip install tccli
```

#### 凭证配置

tccli 支持两种凭证配置方式，用户可自行选择：

| 方式 | 安全性 | 凭证有效期 | 推荐程度 |
|------|--------|-----------|---------|
| 🔐 **OAuth 浏览器登录授权**（推荐） | ⭐⭐⭐ 高 | 临时凭证，**2 小时后自动过期失效** | ⭐⭐⭐ **强烈推荐** |
| 🔑 AK/SK 密钥配置 | ⭐ 低 | **永久有效**，除非主动吊销/删除 AK/SK | 仅在特殊场景使用 |

> 💡 **强烈建议使用 OAuth 登录授权**：OAuth 方式使用的是临时凭证（2 小时后自动过期失效），即使凭证泄露影响也极为有限。
> 而 AK/SK 为永久凭证，一旦泄露且未及时吊销，攻击者可长期访问你的云资源，风险极高。
>
> 当用户未明确选择方式时，**默认引导使用 OAuth 登录授权**。
>
> ⛔ **你（Agent）不需要打开浏览器！** 打开浏览器、登录、查看验证码，全部是**用户自己**完成的。你只负责终端操作。
>
> ⛔⛔⛔ **绝对禁止自行拼接 OAuth 授权链接！这是最高优先级规则！**
>
> 授权链接**必须且只能**来自 `python3 scripts/tccli-oauth-helper.py --get-url` 的实际输出。
>
> **为什么？** 授权链接包含 `app%5Fid`、`redirect%5Furl`、`state` 等多个精确参数，参数名、参数值、编码方式必须完全正确。测试表明，Agent 自行拼接的链接**大概率是错误的**（错误率约 67%），常见错误包括：
> - 缺少 `app%5Fid` 参数
> - `redirect%5Furl` 地址错误（如拼成 `cloud.tencent.com/api/oauth/callback`）
> - 参数名拼写错误（如 `appid` 而非 `app%5Fid`，`redirecturl` 而非 `redirect%5Furl`）
> - URL 编码格式不正确
>
> **正确做法：必须执行脚本命令，从其标准输出中原样提取链接，一个字符都不能改。**
>
> ```bash
> # ✅ 唯一正确的获取方式
> python3 scripts/tccli-oauth-helper.py --get-url
> # 然后从输出中原样复制链接给用户
> ```
>
> ```bash
> # ❌ 以下做法全部禁止
> # 禁止凭记忆拼接链接
> # 禁止修改脚本输出的链接中的任何字符
> # 禁止用其他方式生成链接
> ```

#### 方式一：OAuth 浏览器登录授权（⭐ 推荐）

> 💡 **核心思路**：使用本技能提供的 `tccli-oauth-helper.py` 辅助脚本，将授权流程分为两个非阻塞步骤：
> 1. **生成授权链接** — 执行 `--get-url`，输出链接给用户
> 2. **使用验证码登录** — 用户登录后发回验证码，执行 `--code "验证码"` 完成登录
>
> **为什么用辅助工具？** 原生的 `tccli auth login --browser no` 使用交互式 `input()` 等待用户输入验证码，在非交互式环境（如 Agent 子进程）中会因 EOF 而失败。辅助工具将验证码作为命令行参数传入，完美支持非交互式环境。

**第一步：检查当前凭证是否有效**
```bash
python3 scripts/tccli-oauth-helper.py --status
```

如果返回 `✅ 凭证有效`，说明凭证正常，可跳过授权。如果显示凭证不存在或已过期，执行以下授权流程。

也可以用 tccli 命令验证凭证是否可用：

```bash
tccli cvm DescribeRegions
```

> ⚠️ **注意**：不要使用 `tccli sts GetCallerIdentity` 验证凭证，该接口不支持 OAuth 临时凭证，会报 `InvalidParameter.AccessKeyNotSupport` 错误。

**第二步：生成授权链接**

执行辅助工具生成授权链接（此命令**不会阻塞**）：

```bash
python3 scripts/tccli-oauth-helper.py --get-url
```

输出示例：
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔐 腾讯云 OAuth 授权登录
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

请在浏览器中打开以下链接完成登录：

https://cloud.tencent.com/open/authorize?scope=login&app%5Fid=100038427476&redirect%5Furl=...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
登录后，页面会显示一串 base64 编码的验证码。
请复制该验证码，然后运行以下命令完成登录：

  python3 tccli-oauth-helper.py --code "验证码"

或发送给 AI 助手，让它帮你完成登录。
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📌 State: xxxxxxxxxx (10分钟内有效)
```

**第三步：展示授权链接给用户**

将上一步生成的授权链接**原样**展示给用户（不要修改链接中的任何字符）：

```
请在您的浏览器中打开以下链接，完成腾讯云账号登录：

👉 <从脚本输出中原样复制的完整授权链接>

登录成功后，页面上会显示一个验证码（一串 base64 编码的字符串），请完整复制后发给我。
```

> ⚠️ **关于授权链接的注意事项**：
> - ✅ 链接中的 `%5F` 是正常的（`_` 的 URL 编码），**不要**将其还原为 `_`，这是为了防止 Markdown 渲染器破坏链接
> - ⛔ **严禁修改、重新拼接或"美化"脚本输出的链接**，必须原样传递给用户

> ⚠️ **关于验证码的正确认知**：
> - ✅ 验证码是浏览器登录成功后页面上显示的一串 **base64 编码字符串**（如 `eyJhY2Nlc3NUb2tlbi...`），通常很长
> - ✅ 这个 base64 字符串是 OAuth 授权码，辅助工具会用它去换取临时密钥
> - ❌ **不是** URL 中的参数（如 `state=xxx`）
> - ❌ **不是**短数字验证码
>
> ⛔ **你不需要打开浏览器** — 浏览器操作由用户完成，和你的运行环境无关。

**第四步：使用验证码完成登录**

用户在浏览器完成登录后，会将页面上显示的 base64 验证码发给你。

收到验证码后，执行以下命令完成登录（此命令**不会阻塞**）：

```bash
python3 scripts/tccli-oauth-helper.py --code "用户发来的完整base64验证码"
```

成功输出示例：
```
🔄 正在获取临时凭证...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ OAuth 登录成功!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📌 配置文件: default
📌 凭证路径: /root/.tccli/default.credential
📌 过期时间: 2026-03-21 16:43:20
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

现在可以使用 tccli 了，例如：
  tccli cvm DescribeInstances --region ap-guangzhou
```

**第五步：验证授权结果**

登录成功后，执行以下命令验证：

```bash
tccli cvm DescribeRegions
```

返回地域列表即表示授权成功。

> ⚠️ **注意**：不要使用 `tccli sts GetCallerIdentity` 验证，该接口不支持 OAuth 凭证。

#### 辅助工具命令参考

| 命令 | 说明 |
|------|------|
| `python3 scripts/tccli-oauth-helper.py --get-url` | 生成 OAuth 授权链接 |
| `python3 scripts/tccli-oauth-helper.py --code "验证码"` | 使用验证码完成登录 |
| `python3 scripts/tccli-oauth-helper.py --status` | 检查当前凭证状态 |
| `python3 scripts/tccli-oauth-helper.py --status --profile myprofile` | 检查指定配置文件的凭证状态 |
| `tccli auth logout` | 退出登录，清除本地凭证 |

授权成功后凭证会保存在 `~/.tccli/default.credential`，后续命令无需重复登录。tccli 会自动刷新 OAuth 凭证，无需手动维护。

#### 退出登录

当用户需要退出当前登录、切换账号或清除本地凭证时，可使用以下命令：

```bash
tccli auth logout
```

该命令会清除本地保存的凭证信息（包括 OAuth 临时凭证和 AK/SK 配置）。

> 💡 **退出后**：需要重新执行 OAuth 登录授权或配置 AK/SK 才能继续使用 tccli。

**常见退出场景**：
- 需要切换到其他腾讯云账号
- 凭证出现异常需要重新登录
- 出于安全考虑需要清除本地凭证
- 共享设备使用完毕后清除登录状态

#### 方式二：AK/SK 密钥配置

> ⚠️ **安全提示**：AK/SK 为**永久凭证**，除非你主动在腾讯云控制台吊销或删除，否则将一直有效。一旦泄露，攻击者可持续访问你的云资源。建议优先使用上方的 OAuth 登录授权方式。

如果用户选择使用 AK/SK 方式，或**主动**提供了 SecretId 和 SecretKey，可通过 tccli 命令配置：

```bash
tccli configure set secretId <用户提供的SecretId>
tccli configure set secretKey <用户提供的SecretKey>
tccli configure set region ap-guangzhou
```

配置完成后可通过以下命令验证：

```bash
tccli cvm DescribeRegions
```

> 💡 **提示**：当用户未明确选择凭证方式时，不要主动索要 AK/SK，应优先引导使用 OAuth 登录授权。
> 如遇授权问题，建议先尝试 OAuth 方式解决。



### 步骤3：按场景执行操作

具体命令与参数通过 `tccli --help` 与下列速查表、参考文档确认。

## 速查表

| 任务 | 命令 |
|------|------|
| 查看 CVM 实例 | `tccli cvm DescribeInstances --region ap-beijing` |
| 查看 Lighthouse 实例 | `tccli lighthouse DescribeInstances --region ap-beijing` |
| 查看云硬盘 | `tccli cbs DescribeDisks --region ap-beijing` |
| 查看安全组 | `tccli vpc DescribeSecurityGroups --region ap-beijing` |
| 查看 VPC | `tccli vpc DescribeVpcs --region ap-beijing` |
| 查看 DNS 记录 | `tccli dnspod DescribeRecordList --Domain <domain>` |
| 查看 SSL 证书 | `tccli ssl DescribeCertificates` |
| 查看域名列表 | `tccli domain DescribeDomainNameList` |
| 查看子用户 | `tccli cam ListUsers` |
| 查看告警策略 | `tccli monitor DescribeAlarmPolicies --Module monitor` |
| 查看可用地域 | `tccli cvm DescribeRegions` |
| 查看所有服务 | `tccli --help` |
| 查看操作参数 | `tccli <服务> <操作> --help` |
| 退出登录 | `tccli auth logout` |


## 场景决策

用户想做什么？
```
├─ 查询/了解资源状态 → 使用上方速查表中的命令
├─ 退出登录/切换账号/清除凭证 → tccli auth logout
├─ 安全检查/安全审计/安全巡检 → 读取 references/cvm-security-check.md
├─ 资源巡检/域名到期/证书检查 → 读取 references/auto-check-resource.md
├─ 服务健康度巡检/诊断服务/监控指标异常排查/性能诊断 → 读取 references/cloud-service-healthcheck.md（⚠️ 深度监控诊断，含 CPU/内存/磁盘/连接数等指标分析和健康度评分）
├─ 建站/搭网站/WordPress/宝塔/购买域名 → 读取 references/lighthouse-website-setup.md
├─ 部署应用(Go/Node/Python/Docker) → 读取 references/lighthouse-app-deploy.md
├─ 购买/挂载/扩容云硬盘 → 读取 references/cbs-bindto-cvm.md
└─ 其他云资源操作 → tccli <服务> --help 探索
```

当用户请求涉及以上场景时，**必须先读取对应的参考文档**，然后严格按照文档中的指引执行。


## 端到端示例：查询并管理 CVM 实例

```bash
# 1. 查看北京地区所有 CVM 实例
tccli cvm DescribeInstances --region ap-beijing

# 2. 按名称过滤特定实例
tccli cvm DescribeInstances --region ap-beijing \
  --Filters '[{"Name":"instance-name","Values":["my-server"]}]'

# 3. 查看该实例关联的安全组规则
tccli vpc DescribeSecurityGroupPolicies --region ap-beijing \
  --SecurityGroupId <sg-id>

# 4. 查看该实例的监控数据（CPU 使用率）
tccli monitor GetMonitorData --region ap-beijing \
  --Namespace QCE/CVM \
  --MetricName CpuUsage \
  --Instances '[{"Dimensions":[{"Name":"InstanceId","Value":"<instance-id>"}]}]' \
  --Period 300 \
  --StartTime "2026-03-24T00:00:00+08:00" \
  --EndTime "2026-03-24T12:00:00+08:00"
```


## 写操作和高危操作

### 操作分级

| 风险等级 | 操作类型 | 确认要求 |
|---------|---------|---------|
| ❌ 高危 | 删除实例/云硬盘/VPC/DNS/数据库、修改安全组入站规则 | **二次确认**，明确写出不可撤销性 |
| ⚠️ 中危 | 创建/修改资源、启动/停止实例、修改 DNS、续费 | 单次确认 |
| ✅ 低危 | 查询、列表、获取帮助 | 无需确认，直接执行 |

### 确认流程

1. 清楚说明将要执行的操作
2. 说明影响范围和后果
3. 等待用户明确输入"确认"或"是"
4. 收到确认后才执行

直接执行高危操作会导致 **数据永久丢失**、**服务不可恢复中断**、**计费资源无法找回**。

### 示例

```
用户：删除实例 i-xxxxx
Agent：
⚠️ 警告：即将删除实例 i-xxxxx
- 实例名称：test-server
- 地域：ap-beijing
- 状态：运行中

此操作 **不可撤销**，实例及其数据将 **永久丢失**。
请输入"确认"继续，或"取消"放弃。
```


## 反模式与常见错误

详见 [references/anti-patterns.md](references/anti-patterns.md)。以下为最高频四类：

- 自行拼接 OAuth 授权链接（严重错误，必须使用 tccli-oauth-helper.py）
- 用 CVM 命令操作 Lighthouse（或反过来），二者 API 不通用
- 用占位符假装执行成功（禁止，必须真实执行）
- 跳过 --help 直接猜参数

## 常见问题

| 问题 | 解决 |
|------|------|
| 如何查看操作历史？ | 启用云审计 `tccli cloudaudit LookUpEvents` |
| 如何查询特定标签的资源？ | `--Filters '[{"Name":"tag:Environment","Values":["production"]}]'` |
| 命令执行失败？ | 检查凭证有效性、地域是否正确、用 `--help` 确认参数 |
| 如何退出登录/切换账号？ | `tccli auth logout`，然后重新登录 |
| 如何查看可用地域？ | `tccli cvm DescribeRegions` |
| 如何批量操作？ | 使用 `--Filters` 过滤 + 循环遍历结果 |


## 关键词

Search: `DescribeInstances`, `DescribeSecurityGroups`, `DescribeSecurityGroupPolicies`,
`CreateInstances`, `DescribeBlueprints`, `DescribeBundles`, `CreateRecord`,
`DescribeRecordList`, `DescribeCertificates`, `DescribeDomainNameList`,
`RunCommand`, `AttachDisks`, `CreateDisks`, `DescribeDisks`,
`DescribeAlarmPolicies`, `ListUsers`, `ListAttachedUserAllPolicies`,
`tccli`, `Lighthouse`, `CVM`, `CBS`, `DNSPod`, `SSL`, `CAM`, `TAT`,
`安全检查`, `安全巡检`, `资源巡检`, `建站`, `部署应用`,
`退出登录`, `logout`, `切换账号`, `清除凭证`


## Reference 文件

- [云服务器安全检查](references/cvm-security-check.md) — 安全组、公网暴露、登录方式、镜像、监控、CAM 权限
- [云资源巡检和监控](references/auto-check-resource.md) — 域名到期、SSL 证书、实例状态、云硬盘状态
- [云服务健康度诊断](references/cloud-service-healthcheck.md) — 服务级深度健康度诊断，含监控指标分析、健康度评分、巡检报告
- [使用 Lighthouse 建站指南](references/lighthouse-website-setup.md) — WordPress/宝塔 + 域名注册 + DNS
- [Lighthouse 应用部署指引](references/lighthouse-app-deploy.md) — Go/Node/Python/Docker 部署
- [购买云硬盘并挂载到云服务器](references/cbs-bindto-cvm.md) — CBS 创建、挂载、分区、快照


**版本**：v1.2.0
**最后更新**：2026-04-02

使用说明

# 腾讯云资源管理

一句话：通过 tccli 统一查询和管理腾讯云全产品云资源，内置巡检、建站、部署等场景化指引。

## 使用

```bash
pip install tccli
tccli configure   # 配置密钥
```

然后直接对话，例如：

- 「看看我在北京地区的所有轻量服务器」
- 「帮我做一次云上安全巡检」
- 「在这台轻量服务器上部署一个 Docker 应用」

## 工作原理

技能封装 tccli 的跨产品操作最佳实践：查询优先、写操作先确认、参数以 `tccli --help` 为准。场景决策树把安全检查、资源巡检、建站、应用部署、云硬盘挂载等任务路由到 references/ 下的分步文档，腾讯云内环境可用 whoami.sh 直接识别当前实例。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。