大文件上传（命令行快传工具）
1. 什么时候使用命令行快传工具
当 Web 页面上传或下载不适合当前任务时，建议使用命令行快传工具 bita：
-
单次批量上传文件数量较多，例如达到 500 个文件及以上。
-
单个文件体积较大，例如超过 10GB。
-
需要在本地终端、服务器、训练节点或自动化任务中上传、下载文件。
-
当前业务入口已经提供“命令行快传工具”命令，例如存储管理、模型、数据集等上传或下载入口。
命令行快传工具只负责在终端执行上传、下载任务。网页控制台负责展示当前入口对应的命令模板，CLI 授权页负责完成浏览器授权。
2. 命令中的通用参数
本文命令使用占位符展示，实际执行时请优先复制当前业务页面生成的命令。
| 参数 | 说明 | 示例 |
|---|---|---|
<平台地址> | 当前部署环境对应的平台地址。生产环境示例为 https://www.bitahub.com，测试环境、私有部署环境以当前控制台或实际访问地址为准。 | https://www.bitahub.com |
<bucket-id> | 当前存储桶、文件系统或业务对象对应的资源标识。 | b20250626160652855vpyluw |
<目标子目录> | 上传到平台后的目标路径。不填写时通常上传到当前入口的默认根目录，具体以页面生成命令为准。 | dataset/run-001 |
<远端对象路径> | 下载时的平台文件、目录、模型版本或数据集对象路径。 | dataset/run-001/train.zip |
<本地文件或文件夹路径> | 上传时的本地路径，可以是文件或文件夹。 | /data/train |
<本地保存路径> | 下载时的本地保存目录或文件路径。 | /data/downloads |
如本地路径包含空格，建议用引号包裹路径；更推荐在数据、模型和脚本文件名中避免空格、斜线等容易引发解析歧义的字符。
3. 安装命令行工具
3.1 下载安装包
首次使用前，请下载与当前操作系统和芯片架构匹配的安装包。
| 运行环境 | 下载地址 |
|---|---|
| Windows | Bita-Win |
| macOS Intel | Bita-macOS Intel |
| macOS Apple 芯片 | Bita-macOS Apple |
| Linux | Bita-Linux |
如果你是通过控制台内的“命令行快传工具”入口进入，建议优先使用当前页面提供的下载地址，以保证工具版本与当前部署环境匹配。
3.2 Windows 初始化
Windows 安装完成后通常不需要额外初始化。打开命令提示符、PowerShell 或终端后执行：
bita --help
如果提示找不到 bita 命令，请重新打开终端，或确认安装目录已经加入系统 PATH。
3.3 macOS 初始化
macOS 安装前建议先创建工具安装所需目录：
mkdir -p /usr/local/bin/
然后安装与芯片架构匹配的 .pkg 包。Apple 芯片设备请使用 arm64 安装包，并确认 bita 位于终端可访问的目录中。
安装后执行：
bita --help
如果 macOS 安装器提示安装失败，通常是安装目录不存在或无法创建。先执行 mkdir -p /usr/local/bin/，再重新安装。
3.4 Linux 初始化
Linux 版本下载后，请将 bita 放入全局可执行目录，并添加执行权限：
sudo mv ./bita /usr/bin/bita
sudo chmod +x /usr/bin/bita
bita --help
如果执行登录或上传命令时提示权限不足，请确认 /usr/bin/bita 存在，并且已经具备可执行权限。
4. 登录授权
4.1 新版推荐方式：授权码登录
新版 CLI 不在终端中收集账号密码或验证码。登录由 CLI 发起，浏览器完成授权。
在终端执行：
bita login -e https://www.bitahub.com
执行后，CLI 会展示本次登录的关键信息：
授权地址：<当前环境授权地址>
授权码：<一次性授权码>
有效期：<授权码有效期>
提示语：请在浏览器打开授权地址并完成授权，CLI 将自动等待授权结果。
请按以下步骤完成授权：
-
在浏览器打开 CLI 输出的授权地址。
-
如果页面已经带入授权码，确认无误后继续；如果未带入，请手动输入 CLI 输出的授权码。
-
确认浏览器当前登录的是要授权给 CLI 使用的 BitaHub 账号。
-
点击“授权”。
-
页面提示授权成功后，关闭授权页并回到终端。
-
CLI 检测到授权结果后，即可继续执行上传或下载命令。
网页授权页只负责输入或确认授权码并完成授权；不会创建 CLI 登录事务，不会判断你本机 CLI 是否已登录，也不会解锁或隐藏上传、下载命令。真正执行上传、下载时，由 CLI 判断当前是否已有有效登录状态。
4.2 授权码异常处理
| 情况 | 处理方式 |
|---|---|
| 授权码格式输入错误 | 留在当前页面，按 CLI 输出重新输入授权码。 |
| 授权码过期、已使用或不存在 | 返回终端，重新执行 bita login -e <平台地址> 生成新的授权码。 |
| 打开了旧授权页面 | 以终端最新输出的授权地址和授权码为准，重新打开最新授权页。 |
| 浏览器账号不正确 | 先切换到正确的 BitaHub 账号，再提交授权。 |
| 授权服务暂时不可用 | 保留当前终端窗口，稍后重试；如果授权码已过期，重新生成授权码。 |
5. 上传文件或文件夹
5.1 从上传入口复制命令
进入支持命令行快传的上传入口，例如存储管理、模型上传、数据集上传等，打开“命令行快传工具”抽屉。上传入口应展示上传专用说明和上传命令，不应混入下载导向文案。
上传命令始终可以查看和复制。是否已经登录、是否具备上传权限、目标路径是否可写，由 CLI 在执行时判断。
5.2 上传命令格式
bita upload -e <平台地址> -b <bucket-id> -o <目标子目录> -l <本地文件或文件夹路径>
生产环境示例：
bita upload -e https://www.bitahub.com -b b20250626160652855vpyluw -o dataset/run-001 -l /data/train
参数说明：
| 参数 | 是否必填 | 说明 |
|---|---|---|
-e | 是 | 当前部署环境的平台地址。不要把测试环境或私有部署环境误写成生产地址。 |
-b | 是 | 当前入口生成的资源标识。请直接使用页面生成值。 |
-o | 视入口而定 | 上传目标路径。未设置时通常上传到默认根目录，具体以页面生成命令为准。 |
-l | 是 | 本地待上传文件或文件夹路径。 |
5.3 上传操作顺序
-
安装并初始化
bita。 -
执行
bita login -e <平台地址>，按浏览器授权页完成授权。 -
从上传入口复制页面生成的上传命令。
-
在终端执行上传命令。
-
如果 CLI 提示未登录，请重新执行登录命令后再上传。
6. 下载文件或目录
6.1 从下载入口复制命令
进入支持命令行快传的下载入口，例如文件下载、模型版本下载、数据集下载等，打开“命令行快传工具”抽屉。下载入口应展示下载专用说明和下载命令，不应要求用户先进入上传抽屉再切换。
下载命令始终可以查看和复制。是否已经登录、是否具备下载权限、对象是否存在，由 CLI 在执行时判断。
6.2 下载命令格式
bita download -e <平台地址> -b <bucket-id> -o <远端对象路径> -l <本地保存路径>
示例：
bita download -e https://www.bitahub.com -b b20250626160652855vpyluw -o dataset/run-001/train.zip -l /data/downloads
参数说明：
| 参数 | 是否必填 | 说明 |
|---|---|---|
-e | 是 | 当前部署环境的平台地址。 |
-b | 是 | 当前入口生成的资源标识。 |
-o | 是 | 平台上的文件、目录、模型版本或数据集对象路径。 |
-l | 是 | 本地保存路径。 |
6.3 下载操作顺序
-
安装并初始化
bita。 -
执行
bita login -e <平台地址>，按浏览器授权页完成授权。 -
从下载入口复制页面生成的下载命令。
-
在终端执行下载命令。
-
如果 CLI 提示未登录，请重新执行登录命令后再下载。
7. 常见问题与处理
7.1 macOS 安装失败
现象：安装 macOS Apple 芯片版本时，安装器提示安装失败。
处理：
mkdir -p /usr/local/bin/
执行后重新安装对应的 .pkg 包。
7.2 Linux 登录或执行命令提示权限不足
现象：安装 Linux 版本后，执行 bita login、bita upload 或 bita download 时提示权限不足。
处理：
sudo mv ./bita /usr/bin/bita
sudo chmod +x /usr/bin/bita
bita --help
如果文件已经移动过，只需确认 /usr/bin/bita 具备可执行权限。
7.3 Windows 执行上传时报 HTTP Bad Request
常见原因是尚未完成 CLI 登录。
处理：
bita login -e <平台地址>
在浏览器完成授权后，重新执行上传命令。
7.4 上传或下载时报“权限校验失败”
如果本机时间明显早于标准时间，可能导致上传或下载时权限校验失败。
处理：
-
开启系统自动设置时间，让本机与网络时间同步。
-
或手动校准本机时间后重试上传、下载命令。
7.5 Windows 登录时报“未获取到有效认证信息”
如果 Windows 登录时提示未获取到有效认证信息，可按以下方式处理：
-
下载 config.json 模板。
-
将
config.json放入当前用户的.bita目录，例如%USERPROFILE%\.bita\config.json。 -
确认该文件可读、可写。
-
重新执行登录命令。
7.6 旧版账号密码登录时报 502 Bad Gateway
该问题通常出现在旧版账号密码登录场景，且用户名或密码包含特殊字符。
处理：
Windows：
bita login -u "<用户名>" -p "<密码>" -e <平台地址>
macOS/Linux：
bita login -u '<用户名>' -p '<密码>' -e <平台地址>
新版授权码登录不需要在终端输入用户名和密码。
7.7 旧版账号密码登录提示用户名或密码错误
如果账号注册后未设置密码，旧版账号密码登录可能提示用户名或密码错误。
处理：先登录网页端控制台，在个人中心设置密码；或升级到支持授权码登录的新版 CLI 后使用 bita login -e <平台地址>。
8. 使用建议
-
优先从当前业务入口复制命令，不要手工拼接
bucket-id、对象路径或平台地址。 -
上传前确认本地文件路径存在，下载前确认本地保存目录可写。
-
只授权自己刚在终端发起的 CLI 登录请求；如果授权码已过期或不确定来源，请回到 CLI 重新生成。
-
页面提示授权成功后即可关闭授权页，后续进度以终端输出为准。