tiup: refine description about tiup playground --tag (#19283)

quick-start-with-tidb.md

@@ -67,6 +67,15 @@ TiDB 是一个分布式系统。最基础的 TiDB 测试集群通常由 2 个 Ti
 
 3. 在当前 session 执行以下命令启动集群。
 
+    > **注意：**
+    >
+    > - 如果按以下方式执行 playground，在结束部署测试后，TiUP 会自动清理掉原集群数据，重新执行命令会得到一个全新的集群。
+    > - 如果希望持久化数据，需要在启动集群时添加 TiUP 的 `--tag` 参数，详见[启动集群时指定 `tag` 以保留数据](/tiup/tiup-playground.md#启动集群时指定-tag-以保留数据)。
+    >
+    >     ```shell
+    >     tiup playground --tag ${tag_name}
+    >     ```
+
     - 直接执行 `tiup playground` 命令会运行最新版本的 TiDB 集群，其中 TiDB、TiKV、PD 和 TiFlash 实例各 1 个：
 
         {{< copyable "shell-regular" >}}
@@ -97,9 +106,7 @@ TiDB 是一个分布式系统。最基础的 TiDB 测试集群通常由 2 个 Ti
 
         > **注意：**
         >
-        > + 支持 v5.2.0 及以上版本的 TiDB 在 Apple M1 芯片的机器上运行 `tiup playground`。
-        > + 以这种方式执行的 playground，在结束部署测试后 TiUP 会清理掉原集群数据，重新执行该命令后会得到一个全新的集群。
-        > + 若希望持久化数据，可以执行 TiUP 的 `--tag` 参数：`tiup --tag <your-tag> playground ...`，详情参考 [TiUP 参考手册](/tiup/tiup-reference.md#-t---tag-string)。
+        > v5.2.0 及以上版本的 TiDB 支持在 Apple M1 芯片的机器上运行 `tiup playground`。
 
 4. 新开启一个 session 以访问 TiDB 数据库。
 
@@ -184,6 +191,15 @@ TiDB 是一个分布式系统。最基础的 TiDB 测试集群通常由 2 个 Ti
 
 3. 在当前 session 执行以下命令启动集群。
 
+    > **注意：**
+    >
+    > - 如果按以下方式执行 playground，在结束部署测试后，TiUP 会自动清理掉原集群数据，重新执行命令会得到一个全新的集群。
+    > - 如果希望持久化数据，需要在启动集群时添加 TiUP 的 `--tag` 参数，详见[启动集群时指定 `tag` 以保留数据](/tiup/tiup-playground.md#启动集群时指定-tag-以保留数据)。
+    >
+    >     ```shell
+    >     tiup playground --tag ${tag_name}
+    >     ```
+
     - 直接运行 `tiup playground` 命令会运行最新版本的 TiDB 集群，其中 TiDB、TiKV、PD 和 TiFlash 实例各 1 个：
 
         {{< copyable "shell-regular" >}}
@@ -211,11 +227,6 @@ TiDB 是一个分布式系统。最基础的 TiDB 测试集群通常由 2 个 Ti
         To view the Grafana: http://127.0.0.1:3000
         ```
 
-        > **注意：**
-        >
-        > + 以这种方式执行的 playground，在结束部署测试后 TiUP 会清理掉原集群数据，重新执行该命令后会得到一个全新的集群。
-        > + 若希望持久化数据，可以执行 TiUP 的 `--tag` 参数：`tiup --tag <your-tag> playground ...`，详情参考 [TiUP 参考手册](/tiup/tiup-reference.md#-t---tag-string)。
-
 4. 新开启一个 session 以访问 TiDB 数据库。
 
     + 使用 TiUP `client` 连接 TiDB：

tiup/tiup-playground.md

@@ -23,52 +23,10 @@ tiup playground ${version} [flags]
 - 因为该命令也没有指定各组件的个数，默认情况下，它会启动由 1 个 TiDB、1 个 TiKV、1 个 PD 和 1 个 TiFlash 实例构成的最小化集群
 - 在依次启动完各个 TiDB 组件后，playground 会提醒集群启动成功，并告诉你一些有用的信息，譬如如何通过 MySQL 客户端连接集群、如何访问 [TiDB Dashboard](/dashboard/dashboard-intro.md) 等
 
-playground 的命令行参数说明：
-
-```bash
-Flags:
-      --db int                     设置集群中 TiDB 节点的数量（默认为1）
-      --db.host host               指定 TiDB 的监听地址
-      --db.port int                指定 TiDB 的端口号
-      --db.binpath string          指定 TiDB 二进制文件的位置（开发调试用，可忽略）
-      --db.config string           指定 TiDB 的配置文件（开发调试用，可忽略）
-      --db.timeout int             指定 TiDB 最长等待超时时间，单位为秒。若配置为 0，则永不超时。
-  -h, --help                       打印帮助信息
-      --host string                设置每个组件的监听地址（默认为 127.0.0.1），如果要提供给别的电脑访问，可设置为 0.0.0.0
-      --kv int                     设置集群中 TiKV 节点的数量（默认为1）
-      --kv.binpath string          指定 TiKV 二进制文件的位置（开发调试用，可忽略）
-      --kv.config string           指定 TiKV 的配置文件（开发调试用，可忽略）
-      --mode string                指定 playground 的运行模式，取值选项为 'tidb'（默认）和 'tikv-slim'
-      --pd int                     设置集群中 PD 节点的数量（默认为1）
-      --pd.host host               指定 PD 的监听地址
-      --pd.binpath string          指定 PD 二进制文件的位置（开发调试用，可忽略）
-      --pd.config string           指定 PD 的配置文件（开发调试用，可忽略）
-      --pd.mode string             指定 PD 的工作模式，取值选项为 'ms'。指定该参数代表启用 PD 微服务模式。
-      --scheduling int             设置集群中 Scheduling 节点的数量（默认为 1），只能在 pd.mode 为 'ms' 的时候设置
-      --scheduling.host host       指定 Scheduling 节点的监听地址
-      --scheduling.binpath string  指定 Scheduling 节点上二进制文件的位置（开发调试用，可忽略）
-      --scheduling.config string   指定 Scheduling 节点的配置文件（开发调试用，可忽略）
-  -T, --tag string                 设置 playground 的 tag 信息
-      --ticdc int                  设置集群中 TiCDC 节点的数量（默认为 0）
-      --ticdc.binpath string       指定 TiCDC 二进制文件的位置（开发调试用，可忽略）
-      --ticdc.config string        指定 TiCDC 的配置文件（开发调试用，可忽略）
-      --tiflash int                设置集群中 TiFlash 节点的数量（默认为 1）
-      --tiflash.binpath string     指定 TiFlash 的二进制文件位置（开发调试用，可忽略）
-      --tiflash.config string      指定 TiFlash 的配置文件（开发调试用，可忽略）
-      --tiflash.timeout int        指定 TiFlash 最长等待超时时间，单位为秒，若配置为 0，则永不超时。
-      --tiproxy int                设置集群中 TiProxy 节点的数量
-      --tiproxy.binpath string     指定 TiProxy 的二进制文件位置
-      --tiproxy.config string      指定 TiProxy 的配置文件
-      --tiproxy.host host          Playground 的 TiProxy host。如果没有提供，TiProxy 会使用 host 参数作为它的 host
-      --tiproxy.port int           Playground 的 TiProxy 端口。如果没有提供，TiProxy 会使用 6000 作为它的端口
-      --tiproxy.timeout int        TiProxy 最长等待超时时间，单位为秒，若配置为 0，则永不超时（默认为 60）。
-      --tso int                    设置集群中 TSO 节点的数量（默认为 1），只能在 pd.mode 为 'ms' 的时候设置
-      --tso.host host              指定 TSO 节点的监听地址
-      --tso.binpath string         指定 TSO 节点上二进制文件的位置（开发调试用，可忽略）
-      --tso.config string          指定 TSO 节点的配置文件（开发调试用，可忽略）
-  -v, --version                    显示 playground 的版本号
-      --without-monitor            设置不使用 Prometheus 和 Grafana 的监控功能。若不添加此参数，则默认开启监控功能。
+可以使用以下命令查看 playground 的命令行参数说明：
 
+```shell
+tiup playground --help
 ```
 
 ## 使用示例
@@ -131,12 +89,12 @@ tiup playground --db.binpath /xx/tidb-server
 tiup playground --db 3 --pd 3 --kv 3
 ```
 
-### 启动集群时指定 tag
+### 启动集群时指定 `tag` 以保留数据
 
 Playground 集群在命令行退出时，会默认清空所有的集群数据。如果想要启动一个数据不被自动删除的 Playground 集群，需要在启动时指定集群 tag，指定后可以在 `~/.tiup/data` 路径下找到该集群的数据。在集群启动时指定 tag 的方法如下：
 
 ```shell
-tiup playground --tag <tagname>
+tiup playground --tag ${tag_name}
 ```
 
 以这种方式启动的集群，在集群关闭以后，数据文件会保留。下一次可以继续使用该 tag 启动集群，从而使用从上一次集群关闭时的数据。