文档中心

对象存储

请输入

TOS 命令行工具

配置 ve-tos-cli 统一凭证

本文主要介绍如何为 ve-tos-cli 配置统一访问凭证。ve-tos-cli 支持使用 ve 管理的统一凭证访问 TOS。完成配置后，无需在 ve-tos-cli 中单独配置 AK/SK。该功能适用于需要在多工具间共享统一凭证、自动化任务中避免硬编码 AK/SK、跨环境统一管理访问凭证等场景。

前提条件

已安装 ve 工具。具体操作，请参见安装 ve 工具。

已安装 ve-tos-cli 工具。具体操作，请参见安装 ve-tos-cli。

注意事项

ve login 获取的是临时凭证。凭证失效后，请重新执行 ve login。

使用非 default profile 登录后，需要执行 ve configure profile --profile <profile-name> 切换当前 profile，或在调用 ve-tos-cli 时通过 --profile 显式指定。

ve-tos-cli 使用统一凭证模式时，会忽略其本地配置中的 AK/SK，不会将本地 AK/SK 作为回退凭证。

请勿将本地凭证配置文件提交到代码仓库，也不要在日志或脚本中输出凭证内容。

执行自动化任务前，建议先运行 ve sts GetCallerIdentity 和 ve-tos-cli ls，确认登录状态与访问权限正常。

配置流程

执行 ve login，登录火山引擎账号并在本地生成临时身份凭证。

执行 ve-tos-cli config set auth_mode unified，将 ve-tos-cli 的认证模式设置为统一凭证模式。

执行 TOS 命令，验证配置是否生效。

步骤一：生成临时身份凭证

执行 ve login 命令，使用默认 profile 登录。

ve login 使用 OAuth 2.0 设备码授权。命令执行后，终端会显示登录地址和用户码，并尝试自动打开浏览器。

在浏览器中完成授权后，ve 会将临时身份凭证保存到本地。默认情况下，认证信息写入 ~/.volcengine/config.json 文件中。

如果当前设备无法打开浏览器，例如无图形界面的远程服务器或容器，请执行 ve login --no-browser 命令，然后在其他设备上打开终端显示的登录地址，输入用户码并完成授权。授权期间请勿终止当前命令，ve 会持续轮询登录结果。

如需指定 profile 和地域，请执行 ve login --profile dev --region cn-beijing 命令。

cn-beijing 需替换为您所需的地域，关于 --region 参数支持的地域列表，请参见地域和访问域名。

使用非 default profile 登录后，需执行 ve configure profile --profile dev 命令将其切换为当前 profile。

登录完成后，执行 ve sts GetCallerIdentity 命令验证身份。

步骤二：启用统一凭证模式

执行 ve-tos-cli config set auth_mode unified 命令，将 ve-tos-cli 的认证模式设置为统一凭证模式。

配置完成后，ve-tos-cli 会使用 ve 管理的统一凭证，不再要求单独写入 AK/SK。

执行 ve-tos-cli config show --output json 命令查看当前配置。

确认输出中的 auth_mode 为 unified。

步骤三：验证 TOS 访问

执行 ve-tos-cli ls 命令，列举 TOS 资源。

执行 ve-tos-cli ls tos://<bucket-name>/<prefix>/ 命令列举指定存储桶或目录中的对象。

命令中的 <bucket-name> 替换为实际的存储桶名称，<prefix> 替换为目标目录前缀。如果无需指定目录，可以省略 <prefix>/ 部分。

执行 ve-tos-cli ls tos://<bucket-name>/<prefix>/ --output table 命令，以表格形式显示结果。

命令正常返回结果，表示 ve-tos-cli 已成功使用统一凭证访问 TOS。

完整配置示例

使用默认 profile：

# 登录并在本地生成临时身份凭证
ve login

# 配置 ve-tos-cli 使用统一凭证
ve-tos-cli config set auth_mode unified

# 验证 ve 登录身份
ve sts GetCallerIdentity

# 验证 TOS 访问
ve-tos-cli ls

使用自定义 profile：

# 登录指定 profile
ve login --profile dev --region cn-beijing

# 将该 profile 设置为当前 profile
ve configure profile --profile dev

# 配置 ve-tos-cli 使用统一凭证
ve-tos-cli config set auth_mode unified

# 使用同名 profile 访问 TOS
ve-tos-cli --profile dev ls

使用统一凭证模式时，ve 与 ve-tos-cli 应使用同名 profile。否则，ve-tos-cli 可能无法读取预期的登录状态。

配置说明：

配置项	说明
ve login	通过控制台设备码授权登录，并将临时身份凭证保存到本地。
--profile	指定登录或调用使用的 profile，默认值为 default。
--region	指定登录和资源访问地域。
--no-browser	禁止自动打开浏览器，适用于远程服务器和容器。
auth_mode unified	指定 ve-tos-cli 使用 ve 管理的统一凭证。
ve sts GetCallerIdentity	查看当前登录身份，用于验证 ve 凭证是否有效。
ve-tos-cli config show	查看 ve-tos-cli 的当前配置。

常见问题

ve-tos-cli 提示未找到凭证。

请依次执行以下命令：

ve login
ve sts GetCallerIdentity
ve-tos-cli config set auth_mode unified
ve-tos-cli config show --output json

确认 ve 已登录，且 auth_mode 为 unified。

使用自定义 profile 后无法访问 TOS。

确认 ve 与 ve-tos-cli 使用同名 profile：

ve configure profile --profile dev
ve-tos-cli --profile dev ls

无法自动打开浏览器。

执行以下命令：

ve login --no-browser

在其他可访问浏览器的设备上打开终端显示的地址并输入用户码，即可完成授权。

如何退出登录。

# 退出默认 profile
ve logout
# 退出指定 profile
ve logout --profile dev
# 退出所有通过 ve login 创建的登录状态
ve logout --all

退出后，使用统一凭证模式的 ve-tos-cli 将无法继续访问 TOS。如需恢复访问，请重新执行 ve login。

最近更新时间：2026.10.10 16:47:34

这个页面对您有帮助吗？

有用

无用