## 模块 1：熟悉 TiDB Cloud 文件系统

`ti` 是 TiDB Cloud CLI 命令行的名称。它为管理 TiDB Cloud 上的各类服务提供了统一的命令行入口，覆盖 TiDB Cloud 文件系统和 TiDB Cloud Starter。

```mermaid
---
title: 模块环境概览
---
flowchart LR
  subgraph region["区域 aws-${LAB:REGION_CODE}"]
    style region stroke-dasharray: 5 5
    USER["实验用户"] --> TI["ti CLI"]
    TI -->|通过 API Key 管理| API["TiDB Cloud Filesystem"]
    TI -->|通过 FS Token 挂载/使用| API["TiDB Cloud Filesystem"]
  end
```

本模块旨在让你熟悉 TiDB Cloud CLI `ti` 命令：安装 `ti`，配置 TiDB Cloud API Key，验证连接，并了解 CLI 的帮助信息和输出控制。hermes-智能体将在下一模块加入工作流。

### 步骤 1：安装 TiDB Cloud CLI

- 点击 **[终端 1](ssh://monitor1-ssh#1)**。本模块后续所有命令均在该 shell（用户 `ubuntu`）下执行。
- 下载并安装 TiDB Cloud CLI——`ti`。

```bash
curl -fsSL https://github.com/tidbcloud/ti-cli/releases/latest/download/install.sh | sh
export PATH="$HOME/.ti/bin:$PATH"
```

```output
...
  Docs: https://github.com/tidbcloud/ti-cli
```

- 将 `ti` 命令添加到你的 shell 配置文件，便于后续重新进入终端时直接使用 `ti`。

```bash
grep -qxF 'export PATH="$HOME/.ti/bin:$PATH"' "$HOME/.bashrc" || \
  echo 'export PATH="$HOME/.ti/bin:$PATH"' >> "$HOME/.bashrc"
```

- 检查 TiDB Cloud CLI 版本。你安装的版本可能高于示例输出中的版本。

```bash
ti --version
```

```output
ti 0.2.1 (6b5d3f48e5b852d13906a592f64cac03b614eca9, 2026-08-11T09:07:43Z, linux/amd64)
```

### 步骤 2：获取一对 TiDB Cloud API 密钥

> [!IMPORTANT]
> 此步骤需要你有 TiDB Cloud 账号。推荐你使用自己的 TiDB Cloud 账号（而非组织生产账号）。实验设计均在 TiDB Cloud 免费额度内完成。

- 点击 [TiDB Cloud API Keys](https://tidbcloud.com/org-settings/api-keys)。页面会在新标签页打开 TiDB Cloud Web 控制台。（如进入的是主页而不是 **API Keys** 页面，请在 **组织设置** 下找到。）
- 右上角点击 **Create API Key**。
- 在 **Description** 输入 `lab-test`，点击 **Generate API Key**，获得一对 API 密钥。
- 保持该页面开启，进行下一步。

### 步骤 3：配置并熟悉 TiDB Cloud CLI

- 在 **[终端 1](ssh://monitor1-ssh#1)**，执行以下命令，将“默认区域代码”设置为 `aws-${LAB:REGION_CODE}`。然后按提示分别粘贴 Public Key 和 Private Key。

> [!TIP]
> 粘贴私钥时，终端屏幕不会有任何显示，这是正常现象。

```bash
ti configure --region-code aws-${LAB:REGION_CODE}
```

```output
{
  "profile": "default",
  "region_code": "aws-${LAB:REGION_CODE}",
  "credentials_stored": true
}
```

- 此时，你的 `ti` CLI 已有如下默认配置：
  - 默认区域：aws-${LAB:REGION_CODE}
  - TiDB Cloud 服务管理凭据

> [!NOTE]
> 虽然 ti CLI 已配置了默认区域，后续命令仍会显式用 --region 参数指定区域，以增强意图表达。

- 试着列出指定区域下的所有文件系统。如果账号下没有文件系统，返回空列表也是正确结果。

```bash
ti fs list-file-systems --region aws-${LAB:REGION_CODE}
```

```output
{
  "region_code": "aws-${LAB:REGION_CODE}",
  "file_systems": []
}
```

- 熟悉 `ti` 的在线帮助，任意探索。以下命令涵盖 `ti` 所有帮助形式。`ti` 最多只有两层子命令。

```bash
# 查看 TiDB Cloud CLI 总体帮助。
ti

# 查看 TiDB Cloud CLI 支持的服务和全局参数
ti help

# TiDB Cloud 文件系统的基本功能
ti fs help

# TiDB Cloud 数据库的基本功能
ti db help

# 如何创建 TiDB Cloud 文件系统
ti fs create-file-system help
```

- 上述步骤中，我们以交互方式配置了 `ti`。你也可以用非交互方式完成。看下提示输出。

```bash
ti configure help | grep -i 'non-interactive'
```

```output
[--non-interactive]
  --non-interactive                   使用该选项可避免提示输入值。此时必须同时提供 --tidb-cloud-public-key、--tidb-cloud-private-key 和 --region-code。该参数适合脚本或自动化场景下使用。
```

- 当一个变更资源的命令支持 `--dry-run`，会显示变更计划或校验请求，但不会真的创建/修改资源。例如，以下命令仅预览并不会真的创建文件系统：

```bash
ti fs create-file-system \
  --display-name lab-workspace \
  --dry-run --region aws-${LAB:REGION_CODE}
```

```output
{
  "dry_run": true,
  "command": "ti fs create-file-system",
  "operation": "create_file_system",
  .
  .
  .
    {
      "name": "remote_mutation",
      "status": "skipped",
      "message": "dry-run stopped before sending a mutating remote request"
    }
  ]
}
```

### 步骤 4：创建文件系统

- 使用 `ti fs create-file-system` 创建新文件系统。
- 创建类命令均有 `--wait` 标志，表示创建流程需等待资源可用，便于自动编排。后续会用到此特性。
- 你还可以注意到，`ti` 默认输出 JSON 格式，方便脚本解析；可用 `--query` 配合 JMESPath 语法筛选字段，也可用 `--output text` 调整为更适合人阅读的格式。
- 创建文件系统并捕获 `fs_token` 和 `file_system_id` 到变量。`fs_token` **（保存为** `LAB_FS_TOKEN`**）** 是该文件系统**唯一标识**及**访问凭证**；`file_system_id` **（保存为** `LAB_FS_ID`**）** 仅为唯一标识，不含访问凭证。

> [!TIP]
> 首次创建 TiDB Cloud 文件系统时，过程可能需1分钟左右，请耐心等待。

```bash
read LAB_FS_ID LAB_FS_TOKEN <<< "$(ti fs create-file-system \
  --display-name lab-workspace \
  --region aws-${LAB:REGION_CODE} \
  --wait \
  --query "join(' ', [file_system_id, fs_token])" \
  --output text \
  )"
```

- 命令返回后，检查新建文件系统的 `fs_token`，你的结果会与示例不同。

```bash
echo $LAB_FS_TOKEN
```

```output
drive9_ZXlKaGJHY2lPaUpJV
.
.
.
SzBmUXNtT19rbEZvTjlwZm15
```

- 再检查新建文件系统的 `file_system_id`，你的结果也会不同于示例。

```bash
echo $LAB_FS_ID
```

```output
cd06d327-06ca-4355-9ce5-4bf3cac76bed
```

### 步骤 5：挂载文件系统

- 先创建一个空目录，用于挂载。

```bash
mkdir ~/mnt-module1
```

- 只要有 `fs_token` 即可访问对应文件系统。用 `--fs-token` 挂载新文件系统，利用前面保存好的 `$LAB_FS_TOKEN` 环境变量。

```bash
# 挂载时以参数提供文件系统 token
ti fs mount --region aws-${LAB:REGION_CODE} --mount-path ~/mnt-module1 \
  --fs-token $LAB_FS_TOKEN
```

```output
{
  "status": "mounted",
...
  },
  "write_back_cache": true
}
```

- 使用 `ti fs umount` 卸载文件系统。现在试一下。

```bash
ti fs umount --mount-path ~/mnt-module1 
```

```output
{
  "status": "unmounted",
  "mount_path": "/home/ubuntu/mnt-module1"
}
```

- 再次挂载，这次用 `$TI_FS_TOKEN` 变量挂载。注意 `ti` 命令对环境变量名 `$TI_FS_TOKEN` 有特殊感知，无需额外提供 `--fs-token` 参数。

```bash
# 以 TI_FS_TOKEN 环境变量挂载，可省略 --fs-token
export TI_FS_TOKEN=$LAB_FS_TOKEN
ti fs mount --region aws-${LAB:REGION_CODE} --mount-path ~/mnt-module1
```

```output
{
  "status": "mounted",
...
  },
  "write_back_cache": true
}
```

- 挂载的目录可以像普通目录一样使用。例如，保存一个文本文件。

```bash
echo "Hello TiDB Cloud FS" > ~/mnt-module1/hello-world.txt
cat ~/mnt-module1/hello-world.txt
```

```output
Hello TiDB Cloud FS
```

- 再次卸载该目录。

```bash
# 卸载挂载目录
ti fs umount --mount-path ~/mnt-module1
```

```output
{
  "status": "unmounted",
  "mount_path": "/home/ubuntu/mnt-module1"
}
```

### 步骤 6：为 Hermes 智能体环境准备文件系统凭证

<!-- markdownlint-disable MD032 -->
> [!IMPORTANT]
> - `ti fs mount` 命令仅需文件系统 token。也就是说，即使你的 `ti` CLI 没有事先配置 TiDB Cloud API Key，只要能提供文件系统 token 及区域，挂载就会成功。
> - 这种环境下你无法管理 TiDB Cloud 文件系统，但可正常使用某个特定 TiDB Cloud 文件系统。实际场景下常见于 智能体沙箱等。

- 只需将 `$TI_FS_TOKEN` 变量和 `$TI_REGION_CODE` 传入 Hermes 环境。执行下列命令即可完成。

```bash
echo TI_REGION_CODE=aws-${LAB:REGION_CODE} >> ~/.hermes/.env
echo TI_FS_TOKEN="$LAB_FS_TOKEN" >> ~/.hermes/.env
```

- 确认 `.hermes/.env` 文件内含有 `TI_` 开头变量。

```bash
grep TI_.*= ~/.hermes/.env
```

```output
TI_REGION_CODE=aws-${LAB:REGION_CODE}
TI_FS_TOKEN=XXXXXXXXXXXXXXXXXXXXX
```

- 清理临时环境变量。

```bash
unset LAB_FS_TOKEN LAB_FS_ID TI_FS_TOKEN
```

### 步骤 7：模块小结

- 你已经对 TiDB Cloud CLI `ti` 的基本用法有了初步了解。
- 你创建了新的 TiDB Cloud 文件系统，并将使用凭证写入 Hermes 智能体的环境变量文件。
- 实际使用中，如果丢失现有文件系统的 `fs_token`，可以用 `ti fs generate-file-system-token` 重新生成，或用 `ti fs enable-/disable-/delete-file-system-token` 进行轮换。每个文件系统可有多个 `fs_token`。
- 下一模块，智能体也将学会如何用 `ti` CLI，并能立刻熟练掌握。

请继续前往下一模块。