从 v1/v2 升级到 v3

CloudBase CLI v3.0 在 v1/v2 基础上进行了功能扩充和命令体系梳理，同时兼容 v1/v2 中已有的主要命令格式。升级后，建议优先关注全局使用方式、能力收敛方式，以及已废弃命令的迁移路径。

升级操作

npm install -g @cloudbase/cli

查看当前版本：

tcb --version

---

v3.0 重要变更

1. 全局使用体验升级

v3.0 先做的是 CLI 基础体验统一，这部分会直接影响您后续使用所有命令的方式。

• 全局环境参数统一为 --env-id，旧参数 --envId 仍兼容，但不再推荐使用。
• 新增 tcb env use，支持设置全局默认环境；环境解析优先级为：tcb env use < 项目 cloudbaserc.json < 命令行 --env-id。
• 更多命令支持 --json 输出，便于脚本、CI/CD 和 AI 工具稳定解析结果。
• 更多命令支持 --yes，可跳过交互确认，适合自动化场景。
• 新版 --help 的自解释能力明显增强，支持从顶层命令逐级下钻到具体子命令，并按“用法、参数、示例、相关命令、文档”组织输出。
• v3.0 引入结构化退出码（Exit Code），可区分认证失败、参数错误、资源不存在、云 API 错误、本地文件错误等场景，方便流水线做重试和错误处理。

信息

其中新版 --help 值得关注。它不再只是参数速查，而是命令发现入口：先用顶层帮助定位命令，再进入子命令帮助确认真实签名。像 tcb fn deploy --help 这样的输出，会把命令写法、关键参数、示例、相关命令和文档链接放在一起，既方便人工检索，也适合 AI 先读帮助再生成命令，减少幻觉和试错。

$ tcb fn deploy --help
Usage: tcb fn deploy [options] [name]

Options:
  --force
  --dir <dir>
  --runtime <runtime>
  --json

描述:
  部署云函数（首次部署即创建新函数）...

示例:
  tcb fn deploy hello
  tcb fn deploy hello --force
  tcb fn deploy --all

相关命令:
  tcb fn invoke
  tcb fn log

文档:
  https://docs.cloudbase.net/cli-v1/functions/deploy

2. 新增通用能力

v3.0 补齐了几类跨场景的通用能力，减少“必须跳到控制台”或“自己封装脚本”的情况。

命令	作用
tcb docs	在终端内检索和阅读官方文档，无需登录
tcb api	直接调用腾讯云 API，无需自行处理鉴权和请求封装
tcb secrets	获取当前 Web 登录态下的临时密钥，便于本地调试 SDK

这部分能力更偏工具层增强，适合排障、自动化和 AI 协作场景。

3. 原有命令能力增强与收敛

v3.0 不只是加新命令，也对原有命令做了能力补齐和职责收敛。

云存储增强

• 新增 tcb storage rm，替代旧的 tcb storage delete，支持递归删除、--force、--dry-run。
• 新增 tcb storage cp，支持云端复制和移动文件。
• 新增 tcb storage search，支持按模式、目录、后缀和正则搜索文件。

日志能力统一

• 新增统一日志入口 tcb logs search，支持云函数、云托管、数据库、大模型等日志统一检索。
• 原先分散在资源模块中的日志查询方式开始收敛，例如云函数日志文档已改为引导使用 tcb logs。

权限能力统一

• 资源权限统一收敛到 tcb permission，用于管理数据库集合、存储桶、SQL 表、云函数的权限。
• 原有存储 ACL / rules 相关命令在 v3.0 起废弃，迁移到统一权限模型。

4. 新增能力

除通用能力外，v3.0 还新增了一批面向具体资源和业务场景的命令模块：

命令	说明
tcb cors	安全域名管理（Web SDK 白名单）
tcb domains	自定义域名管理
tcb routes	HTTP 服务路由管理
tcb app	CloudBase 云应用部署管理
tcb agent	AI Agent 管理
tcb user	终端用户管理
tcb role	角色管理
tcb db	MySQL / NoSQL 数据库管理

其中比较值得关注的新增方向有：

• 环境管理从“查看/重命名”扩展到完整生命周期，新增 tcb env use/create/modify/renew/delete/usage/info。
• HTTP 访问服务从旧的 tcb service 拆分为 tcb cors、tcb domains、tcb routes 三个更清晰的模块。
• 云托管新增 tcb cloudrun traffic，支持灰度流量分配、全量发布和回滚。
• tcb db 不再只承载旧的数据模型命令，还扩展出 MySQL 执行、实例管理、备份回档、慢查询监控，以及 NoSQL 原生命令和回档能力。

5. 已移除能力

以下能力在 v3.0 中已移除，不再支持：

已移除命令	替代方式
tcb fun list/deploy/run	迁移到 tcb cloudrun list/deploy/run
tcb run standalonegateway ...	无 CLI 替代命令，相关操作请参考控制台

6. 废弃命令说明

以下命令在 v3.0 中仍兼容保留，但已标记为废弃，建议尽快迁移：

废弃项	推荐替代
tcb functions:*	tcb fn ...
tcb storage:*	tcb storage ...
tcb hosting:*	tcb hosting ...
tcb service ...	tcb cors / tcb domains / tcb routes
tcb db list/pull/push	tcb db model list/pull/push
tcb run list/delete	tcb cloudrun list/delete
tcb storage get-acl/set-acl/rules ...	tcb permission