登录认证
tcb login 登录腾讯云账号,授权 CloudBase CLI 操作你的云开发资源。未登录时,大多数命令会提示先登录。
登录方式选择
| 场景 | 推荐命令 |
|---|---|
| 本机开发(默认) | tcb login:设备码授权,终端输出链接与用户码,同时尝试打开浏览器 |
| 本机,走本地回调 | tcb login --flow web:回调由本机 127.0.0.1 接收,无需输入用户码 |
| 远程服务器 / SSH / 容器 / AI Agent | tcb login:设备码流程不依赖本地回调 |
| CI/CD 非交互 | tcb login --apiKeyId <SecretId> --apiKey <SecretKey>:账号级云 API 密钥 |
| 环境级长期凭证 | tcb login --cloudbase-api-key <key> -e <envId>:权限限定在指定环境 |
| 临时密钥 | tcb login --apiKeyId <SecretId> --apiKey <SecretKey> --token <Token> |
| 国际站账号 | tcb login --intl true:同时持久化站点配置 |
| 企业自建授权服务 | tcb login --endpoint <url>:仅设备码流程生效 |
命令参数
| 参数 | 说明 | 必填 |
|---|---|---|
-k, --key | 交互式输入腾讯云 API 永久密钥 | 否 |
--apiKeyId <SecretId> | 腾讯云 API SecretId,与 --apiKey 配合使用 | 否 |
--apiKey <SecretKey> | 腾讯云 API SecretKey,与 --apiKeyId 配合使用 | 否 |
--token [token] | 腾讯云 API 临时密钥 Token,配合密钥使用 | 否 |
--cloudbase-api-key <key> | 环境级 API Key,必须配合 -e/--env-id | 否 |
--flow <flow> | 授权方式,可选 device(默认)与 web | 否 |
--intl [value] | 站点,只接受 true(国际站)与 false(国内站) | 否 |
--endpoint <url> | 自定义设备授权 Endpoint,仅 --flow device 生效 | 否 |
-e, --env-id <envId> | 云开发环境 ID,环境级 API Key 登录时必填 | 否 |
不带任何参数时走设备码授权。
本机登录
tcb login
CLI 默认使用设备码授权(OAuth 2.0 Device Authorization Grant,RFC 8628),不要求发起登录的终端与完成确认的浏览器在同一台机器上:
- 执行
tcb login,CLI 输出授权链接(verification_uri)和用户码(user_code),并尝试自动打开浏览器。 - 在浏览器中确认授权。没有自动打开时,手动复制链接访问。
- CLI 轮询授权状态,完成后保存本地登录态。
已登录且凭证有效时,tcb login 直接返回登录成功提示,不再走授权流程。要换方式或换账号,先执行 tcb logout。
本地回调授权
本机有图形界面时,可以让 CLI 拉起浏览器,通过本地回调完成授权,无需输入用户码:
tcb login --flow web
该模式下 CLI 在本机启动临时 HTTP 服务并监听随机端口,授权结果由 http://127.0.0.1:<port> 接收,因此要求本机既能打开浏览器,也能接收本地回调(等待回调默认超时 10 分钟)。远程服务器、容器、无头环境请使用默认的设备码流程。
TCB_NO_BROWSER=true只在--flow web下生效,用于禁止自动打开浏览器;设备码流程不读取该变量。
远程与无头环境
远程服务器、SSH、Docker / Kubernetes 容器、CI Runner、AI 编程助手(Claude Code、Codex 等通过 MCP 工具调用 CLI)都用默认的设备码流程:
tcb login
复制终端输出的授权链接和用户码,在任意可访问浏览器的设备上打开并确认授权。CLI 自动轮询结果,不需要端口映射,也不要求本地回调。
无浏览器时,自动打开浏览器这一步失败会被忽略,授权链接与用户码照常输出。
云 API 密钥登录
已有腾讯云云 API 密钥时,可以跳过浏览器授权。
交互式输入
tcb login -k
按提示输入 SecretId 和 SecretKey。密钥在云 API 密钥管理页面创建或查看。
⚠️ 腾讯云 API 密钥可以操作你名下的所有腾讯云资源,妥善保存并定期更换,换密钥后及时删除旧的。
非交互式登录
脚本和流水线直接用参数传入密钥:
# 永久密钥
tcb login --apiKeyId <SecretId> --apiKey <SecretKey>
# 临时密钥
tcb login --apiKeyId <SecretId> --apiKey <SecretKey> --token <Token>
⚠️ 账号级密钥可以操作你名下的所有腾讯云资源。放在 CI 的 Secrets 里,不要写进仓库。
环境级 API Key
环境级 API Key 是 CloudBase 的长期凭证,权限范围限定在指定环境内,适合按环境隔离授权:
tcb login --cloudbase-api-key <key> -e <envId>
必须配合 -e/--env-id 指定环境。创建方式见 API Key 管理。
GitHub Actions 示例
- name: Login to CloudBase
run: npx @cloudbase/cli login --cloudbase-api-key ${{ secrets.CLOUDBASE_API_KEY }} -e ${{ secrets.CLOUDBASE_ENV_ID }}
国际站登录
国际站账号在登录时显式指定站点:
tcb login --intl true
--intl true让本次登录立即使用国际站,授权页与 OAuth 端点同时切换,并把站点配置持久化- 切回国内站用
tcb login --intl false,或tcb config set isIntl false - 也可以先执行
tcb config set isIntl true,再执行tcb login - 站点优先级:
--intl> 配置文件isIntl> 环境变量TCB_IS_INTL> 默认国内站 - 站点与地域相互独立,切换站点不改变 region。国际站环境通常在新加坡,需要指定地域时加
-r ap-singapore,例如tcb env list -r ap-singapore
自定义授权端点
企业可以把设备码授权指向自建服务:
tcb login --endpoint https://your-auth-server.example.com
CLI 使用指定 Endpoint,依次调用 /device/code 和 /token 接口获取凭证。该选项仅在 --flow device(默认)时生效。自建服务需遵循 CloudBase CLI Device Flow 协议,见设备码授权概览与企业自建设备码授权服务。
验证登录状态
tcb env list
能列出环境即表示登录成功。提示未登录、凭证失效或列表为空时,重新执行 tcb login;国际站账号还要确认地域参数(见国际站登录)。
获取临时密钥
tcb secrets get 读取当前 Web 登录态的临时密钥(secretId / secretKey / token),用于在本地调试时初始化 @cloudbase/manager-node 或 @cloudbase/node-sdk,省去手动配置。
通过 tcb login --key 输入的永久密钥不允许输出。永久密钥一旦泄露影响永久,不要用它跑本命令。
tcb secrets get [options]
| 参数 | 说明 |
|---|---|
-e, --env-id <envId> | 绑定环境 ID,附加到输出 |
--json | 输出 JSON |
tcb secrets get --json -e my-env-id
{
"secretId": "AKID...",
"secretKey": "xxx",
"token": "yyy",
"expiredAt": "2026-03-30 22:00:00",
"isTemporary": true,
"envId": "my-env-id"
}
用输出初始化 SDK:
// @cloudbase/manager-node
const CloudBase = require('@cloudbase/manager-node')
const app = new CloudBase({
secretId: '<secretId>',
secretKey: '<secretKey>',
token: '<token>',
envId: 'my-env-id'
})
// @cloudbase/node-sdk
const tcb = require('@cloudbase/node-sdk')
const tcbApp = tcb.init({
secretId: '<secretId>',
secretKey: '<secretKey>',
token: '<token>',
env: 'my-env-id'
})
临时密钥有时效性,过期后自动失效。不要提交到代码仓库或粘贴到公开渠道。
登出与切换账号
tcb logout
tcb logout 清除本地登录凭证(包括项目级凭证)和当前环境记录。切换账号时,登出后重新执行 tcb login。
凭证存储与安全
- 登录凭证保存在 CLI 配置目录的
auth.json,默认路径为~/.config/.cloudbase/(遵循XDG_CONFIG_HOME) - 使用环境级 API Key 登录时,凭证可能写入项目级存储,与登录时的项目目录一致
auth.json包含身份凭据,不要提交到仓库或分享给他人- 长期密钥优先通过 CI Secrets 或环境变量注入,避免硬编码在脚本和配置文件中
常见问题
环境列表为空
- 账号下没有创建环境,去控制台创建
- 国际站账号没有指定地域,尝试
tcb env list -r ap-singapore - 子账号权限不足,见子账号授权
浏览器无法打开授权页
用默认设备码流程,手动复制终端输出的链接和用户码。TCB_NO_BROWSER=true 对设备码流程无效,只影响 --flow web。
本地回调失败
--flow web 要求本机可访问 127.0.0.1 的随机端口。远程服务器、容器或端口受限的环境改用默认的 --flow device。
提示无权限
检查账号与环境归属。环境级 API Key 只能操作创建时指定的环境,账号级密钥受 CAM 权限策略限制。