跳到主要内容

登录认证

tcb login 登录腾讯云账号,授权 CloudBase CLI 操作你的云开发资源。未登录时,大多数命令会提示先登录。

登录方式选择​

场景推荐命令
本机开发(默认)tcb login:设备码授权,终端输出链接与用户码,同时尝试打开浏览器
本机,走本地回调tcb login --flow web:回调由本机 127.0.0.1 接收,无需输入用户码
远程服务器 / SSH / 容器 / AI Agenttcb 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),不要求发起登录的终端与完成确认的浏览器在同一台机器上:

  1. 执行 tcb login,CLI 输出授权链接(verification_uri)和用户码(user_code),并尝试自动打开浏览器。
  2. 在浏览器中确认授权。没有自动打开时,手动复制链接访问。
  3. 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 权限策略限制。