# US3 对象存储
<subtitle>在沙箱内通过内网访问 UCloud US3 对象存储。</subtitle>

[US3](https://docs.ucloud.cn/ufile/introduction/concept) 是 UCloud 提供的对象存储服务，兼容 S3 协议，适合存放数据集、模型文件、Agent 产出物等需要长期保留的数据。沙箱可以通过**内网**直接访问同地域的 US3，流量不经过公网，传输更快、更稳定。

您可以通过以下两种方式在沙箱中使用 US3：

| 方式 | 说明 | 适用场景 |
|-----|------|---------|
| us3cli | 命令行工具，操作 Bucket 和文件 | 批量上传、下载、同步数据 |
| us3fs | 将 Bucket 挂载为沙箱内的目录 | 让程序像读写本地文件一样访问 US3 |

## 内网访问域名

请根据沙箱所在的[地域](/docs/agent-sandbox/product/region.md)，选择对应的 US3 内网域名：

| 沙箱地域 | 中文描述 | US3 内网域名 |
|---------|---------|-------------|
| `cn-wlcb` | 华北（乌兰察布） | `internal-cn-wlcb.ufileos.com` |
| `cn-sh` | 华东（上海） | `internal-cn-sh2-01.ufileos.com` |
| `us-ca` | 美国（洛杉矶） | `internal-us-ca-01.ufileos.com` |

> 内网域名只能访问同一地域的 Bucket，请确保 Bucket 与沙箱位于同一地域。

## 获取密钥

访问 US3 需要一对公钥和私钥，可以在 [US3 控制台的令牌管理](https://console.ucloud.cn/ufile/token) 中获取。

> **建议**：密钥会以配置文件的形式保存在沙箱内。建议为沙箱单独创建令牌，只授予所需 Bucket 的最小权限，并按需设置有效期，不要使用账号的 API 密钥。

## 使用 us3cli

[us3cli](https://docs.ucloud.cn/ufile/tools/us3cli/introduction) 是 US3 的命令行工具，支持 Bucket 管理，以及文件的上传、下载、删除、移动、批量操作等。以下命令均在沙箱内执行。

### 1. 安装

```bash
sudo curl -o /usr/local/bin/us3cli https://us3-release.cn-bj.ufileos.com/us3cli/us3cli-linux64
sudo chmod +x /usr/local/bin/us3cli
```

### 2. 编辑配置文件

创建配置文件 `/home/user/.us3cliconfig/config`，`endpoint` 填写沙箱所在地域的内网域名（见上文“内网访问域名”）：

```yaml
accesskey: <公钥>
secretkey: <私钥>
endpoint: <US3 内网域名>
```

将该配置设为默认配置：

```bash
us3cli config --su config
```

### 3. 操作 Bucket

```bash
# 列出 Bucket 中的文件
us3cli ls us3://<bucket>/

# 上传文件 / 目录
us3cli cp ./result.csv us3://<bucket>/results/result.csv
us3cli cp -r ./output us3://<bucket>/output

# 下载文件 / 目录
us3cli cp us3://<bucket>/datasets/train.csv ./train.csv
us3cli cp -r us3://<bucket>/datasets ./datasets

# 增量同步本地目录到 Bucket
us3cli sync ./workspace us3://<bucket>/workspace

# 删除文件 / 目录
us3cli rm us3://<bucket>/results/result.csv
us3cli rm -r us3://<bucket>/output
```

更多用法请参阅 [us3cli 常见操作](https://docs.ucloud.cn/ufile/tools/us3cli/quickaccess)。

## 使用 us3fs 挂载

[us3fs](https://docs.ucloud.cn/ufile/tools/us3fs/introduction) 可以将 US3 Bucket 挂载到沙箱内的某个目录，之后即可以文件系统的方式读写 US3 中的数据。以下命令均在沙箱内执行。

### 1. 安装

```bash
sudo curl -o /usr/local/bin/us3fs https://ufile-release.cn-bj.ufileos.com/us3fs/us3fs_2.1.5
sudo chmod +x /usr/local/bin/us3fs
```

### 2. 创建配置文件

创建配置文件，例如 `/home/user/.us3fsconfig/config`（路径可自行指定）：

```yaml
access_key: <公钥>
secret_key: <私钥>
endpoint: <US3 内网域名>
```

### 3. 挂载 Bucket

```bash
mkdir -p /path/to/mount
us3fs --passwd=/home/user/.us3fsconfig/config <bucket> /path/to/mount
```

> `<bucket>` 和挂载目录必须作为命令的最后两个参数，否则其他参数不会生效。

挂载完成后，写入 `/path/to/mount` 的文件会保存到 US3 Bucket 中。卸载时执行：

```bash
umount /path/to/mount
```

> - us3fs 挂载的目录默认只有执行挂载的用户可以访问。如需让其他用户访问，可以加上 `-o allow_other` 参数，并在 `/etc/fuse.conf` 中添加 `user_allow_other`。
> - 对象存储不同于本地磁盘，大量小文件读写、频繁修改的场景性能较差。建议先在沙箱本地完成编译、安装依赖等操作，再将结果写入挂载目录。

更多挂载参数请参阅 [us3fs 快速使用](https://docs.ucloud.cn/ufile/tools/us3fs/quickaccess)。

## 使用 SDK 自动配置

您也可以在创建沙箱后通过 SDK 自动完成 us3cli 的安装和配置。下面的示例从本地环境变量读取 US3 密钥，写入沙箱的配置文件，然后列出 Bucket 中的文件：

```python
import os
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create()

# 安装 us3cli
sandbox.commands.run(
    "sudo curl -o /usr/local/bin/us3cli https://us3-release.cn-bj.ufileos.com/us3cli/us3cli-linux64"
    " && sudo chmod +x /usr/local/bin/us3cli"
)

# 写入配置文件，endpoint 使用沙箱所在地域的内网域名
sandbox.files.write(
    "/home/user/.us3cliconfig/config",
    f"""accesskey: {os.environ["US3_PUBLIC_KEY"]}
secretkey: {os.environ["US3_PRIVATE_KEY"]}
endpoint: internal-cn-wlcb.ufileos.com
""",
)
sandbox.commands.run("us3cli config --su config")

# 列出 Bucket 中的文件
result = sandbox.commands.run("us3cli ls us3://<bucket>/")
print(result.stdout)
```

> 如果每个沙箱都需要使用 us3cli 或 us3fs，建议在[自定义模板](/docs/agent-sandbox/template/quickstart.md)中预装，避免每次创建沙箱时重复下载。