平凯数据库快速上手指南

本指南介绍如何快速上手体验平凯数据库。对于非生产环境，你可以选择以下任意一种方式部署平凯数据库：

在单机上部署试用环境（支持 macOS 和 Linux）
在单机上模拟部署生产环境（支持 Linux）

注意

本指南中的平凯数据库部署方式仅适用于快速上手体验，不适用于生产环境。

如需在生产环境部署平凯数据库，请参考在生产环境中部署平凯数据库指南。
如需在 Kubernetes 上部署平凯数据库，请参考快速上手 TiDB Operator。

在单机上部署试用环境

适用场景：利用本地 macOS 或者单机 Linux 环境快速部署平凯数据库试用集群，体验平凯数据库集群的基本架构环境，以及 TiDB、TiKV、PD、监控等基础组件的运行。

注意

试用环境基于平凯数据库的 OPEN CORE 组件部分，即对应的 TiDB -${version}- LTS OPEN CORE 版本。

平凯数据库是一个分布式数据库系统，通过 TiUP Playground，可以快速搭建出一套体验试用的本地环境，步骤如下：

注意

TiUP Playground 部署的试用集群，仅可体验平凯数据库常规的开源 OPEN CORE 功能特性，会缺失部分企业级功能和运维操作能力，不建议用于完整的功能性测试和稳定性测试。

下载并安装 TiUP。

curl --proto '=https' --tlsv1.2 -sSf https://tiup-mirrors.pingcap.com/install.sh | sh

安装完成后会提示如下信息：

Successfully set mirror to https://tiup-mirrors.pingcap.com
Detected shell: zsh
Shell profile:  /Users/user/.zshrc
/Users/user/.zshrc has been modified to add tiup to PATH
open a new terminal or source /Users/user/.zshrc to use it
Installed path: /Users/user/.tiup/bin/tiup
===============================================
Have a try:     tiup playground
===============================================

声明全局环境变量。
注意
- TiUP 安装完成后会提示 Shell profile 文件的绝对路径。
- 在执行以下 source 命令前，需要将 ${your_shell_profile} 修改为 Shell profile 文件的实际位置。
```
source ${your_shell_profile}
```
在当前 session 执行以下命令启动集群。
注意
- 如果按以下方式执行 playground，在结束部署测试后，TiUP 会自动清理掉原集群数据，重新执行命令会得到一个全新的集群。
- 如果希望持久化数据，需要在启动集群时添加 TiUP 的 --tag 参数，详见启动集群时指定 tag 以保留数据。
  tiup playground --tag ${tag_name}
指定平凯数据库 OPEN CORE 版本以及各组件实例个数，命令类似于：
```
tiup playground <cluster-name> --db 2 --pd 3 --kv 3
```
上述命令会在本地下载并启动某个版本的集群（例如 v8.5 LTS 平凯数据库 v7.1.8.5 的 OPEN CORE ）。版本信息可以通过执行 tiup list tidb 来查看。运行结果将显示集群的访问方式：
```
CLUSTER START SUCCESSFULLY, Enjoy it ^-^
To connect TiDB: mysql --comments --host 127.0.0.1 --port 4001 -u root -p (no password)
To connect TiDB: mysql --comments --host 127.0.0.1 --port 4000 -u root -p (no password)
To view the dashboard: http://127.0.0.1:2379/dashboard
PD client endpoints: [127.0.0.1:2379 127.0.0.1:2382 127.0.0.1:2384]
To view the Prometheus: http://127.0.0.1:9090
To view the Grafana: http://127.0.0.1:3000
```
注意
平凯数据库支持在 Apple M1 芯片的机器上运行 tiup playground。
新开启一个 session 以访问平凯数据库。
- 使用 TiUP client 连接平凯数据库：
```
tiup client
```
- 也可使用 MySQL 客户端连接平凯数据库：
```
    mysql --host 127.0.0.1 --port 4000 -u root
```
通过 http://127.0.0.1:9090 访问平凯数据库的 Prometheus 管理界面。
通过 http://127.0.0.1:2379/dashboard 访问 TiDB Dashboard 页面，默认用户名为 root，密码为空。
通过 http://127.0.0.1:3000 访问平凯数据库的 Grafana 界面，默认用户名和密码都为 admin。
（可选）将数据加载到 TiFlash 进行分析。
测试完成之后，可以通过执行以下步骤来清理集群：
- 按下 Control + C 键停掉上述启用的平凯数据库服务。
- 等待服务退出操作完成后，执行以下命令：
```
tiup clean --all
```

注意

TiUP Playground 默认监听 127.0.0.1，服务仅本地可访问；若需要使服务可被外部访问，可使用 --host 参数指定监听网卡绑定外部可访问的 IP。

在单机上模拟部署生产环境

适用场景：希望用单台 Linux 服务器，体验平凯数据库最小的完整组件拓扑的集群，并模拟生产环境下的部署步骤。

本节介绍如何参照 TiUP 最小拓扑的一个 YAML 文件部署平凯数据库集群。

准备环境

准备平凯数据库的本地安装包

最小规模的平凯数据库集群拓扑包含以下实例：

注意

下表中拓扑实例的 IP 为示例 IP。在实际部署时，请替换为实际的 IP。

实例	个数	IP	配置
TiKV	3	10.0.1.1 10.0.1.1 10.0.1.1	避免端口和目录冲突
TiDB	1	10.0.1.1	默认端口全局目录配置
PD	1	10.0.1.1	默认端口全局目录配置
TiFlash	1	10.0.1.1	默认端口全局目录配置
Monitor	1	10.0.1.1	默认端口全局目录配置

部署平凯数据库集群的主机软件和环境要求如下：
- 需要使用部署主机的 root 用户及密码
- 关闭防火墙或者开放平凯数据库集群的节点间所需端口
- 目前 TiUP Cluster 支持在 x86_64（AMD64）和 ARM 架构上部署平凯数据库集群
```
- 在 AMD64 架构下，建议使用 RedHat Enterprise Linux 8.4、Rocky Linux 9.1、银河麒麟高级服务器V10 SP1/SP2/SP3、统信服务器V20、OpenEuler 22.03 LTS SP1/SP3 及以上版本 Linux 操作系统
- 在 ARM 架构下，建议使用 RedHat Enterprise Linux 8.4、Rocky Linux 9.1、银河麒麟高级服务器V10 SP1/SP2/SP3、统信服务器V20、OpenEuler 22.03 LTS SP1/SP3 及以上版本 Linux 操作系统
```
  注意
  根据 CentOS Linux EOL，CentOS Linux 7 的上游支持已于 2024 年 6 月 30 日终止。为了服务仍在使用 CentOS Linux 7 的用户，平凯数据库 v7.1.8 依然支持 CentOS Linux 7。然而，由于 CentOS Linux 7 已到达 EOL，强烈建议用户参考该系统的官方声明和安全建议，将生产环境迁移到平凯数据库支持的操作系统版本，如 Rocky Linux 9.1 及以上版本。
  根据 Red Hat Enterprise Linux Life Cycle，Red Hat Enterprise Linux 7 的 Maintenance Support 于 2024 年 6 月 30 日终止。从 v7.1.8 开始，平凯数据库已结束对 Red Hat Enterprise Linux 7 的支持，建议使用 Rocky Linux 9.1 及以上的版本。如果将运行在 Red Hat Enterprise Linux 7 上的平凯数据库集群升级到 v7.1.8 或之后版本，将存在导致集群不可用的风险。升级前，请务必检查你的操作系统版本。

实施步骤

下载并安装 TiUP：
注意：
你可以使用 Linux 系统的任一普通用户或 root 用户登录主机，以下步骤以 root 用户为例。
```
curl --proto '=https' --tlsv1.2 -sSf https://tiup-mirrors.pingcap.com/install.sh | sh
```
声明全局环境变量：
注意
TiUP 安装完成后会提示对应 Shell profile 文件的绝对路径。在执行以下 source 命令前，需要将 ${your_shell_profile} 修改为 Shell profile 文件的实际位置。
```
source ${your_shell_profile}
```
安装 TiUP 的 cluster 组件：
```
tiup cluster
```
如果机器已经安装 TiUP cluster，需要更新软件版本：
```
tiup update --self && tiup update cluster
```
由于模拟多机部署，需要通过 root 用户调大 sshd 服务的连接数限制：
- 修改 /etc/ssh/sshd_config 将 MaxSessions 调至 20。
- 重启 sshd 服务：
```
service sshd restart
```
联系官方获取平凯数据库的安装包，将安装包发送到中控节点，解压安装包。
注意
本节以 amd64 环境下的平凯数据库为例，在实际部署时，请替换为实际运行环境的平凯数据库版本。
执行本地安装包解压配置，并设置本地镜像库：
```
tar -xzvf tidb-server-${version}-linux-amd64.tar.gz
tar -xzvf tidb-toolkit-${version}-linux-amd64.tar.gz
sh tidb-server-${version}-linux-amd64/local_install.sh && \
source /PATH/tidb/.bash_profile
```
查看镜像库：
```
tiup mirror show
```

合并镜像库：

ls -ld tidb-server-${version}-linux-amd64
ls -ld tidb-toolkit-${version}-linux-amd64

cd tidb-server-${version}-linux-amd64/
cp -rp keys ~/.tiup/
tiup mirror merge ../tidb-toolkit-${version}-linux-amd64

建议关闭 TiUP 的遥测功能：
```
tiup telemetry disable
```

按下面的配置模板，编辑配置文件，命名为 tidb-topo.yaml。

注意

user: "root"：表示通过 root 系统用户来做集群的内部管理，正式环境建议用普通用户来管理，如 tidb 默认使用 22 端口通过 ssh 登录目标机器
replication.enable-placement-rules：设置这个 PD 参数来确保 TiFlash 正常运行
host：设置为本部署主机的 IP

配置模板如下：

tiup cluster template > tidb-topology.yaml

注意

以下拓扑实例的 IP 为示例 IP。在实际部署时，请替换为实际的 IP。

# # Global variables are applied to all deployments and used as the default value of
# # the deployments if a specific deployment value is missing.

global:
 user: "root"
 ssh_port: 22
 deploy_dir: "/tidb-deploy"
 data_dir: "/tidb-data"

# # Monitored variables are applied to all the machines.
monitored:
 node_exporter_port: 9100
 blackbox_exporter_port: 9115

server_configs:
 tidb:
   instance.tidb_slow_log_threshold: 300
 tikv:
   readpool.storage.use-unified-pool: false
   readpool.coprocessor.use-unified-pool: true
 pd:
   replication.enable-placement-rules: true
   replication.location-labels: ["host"]
 tiflash:
   logger.level: "info"

pd_servers:
 - host: 10.0.1.1

tidb_servers:
 - host: 10.0.1.1

tikv_servers:
 - host: 10.0.1.1
   port: 20160
   status_port: 20180
   config:
     server.labels: { host: "logic-host-1" }

 - host: 10.0.1.1
   port: 20161
   status_port: 20181
   config:
     server.labels: { host: "logic-host-2" }

 - host: 10.0.1.1
   port: 20162
   status_port: 20182
   config:
     server.labels: { host: "logic-host-3" }

tiflash_servers:
 - host: 10.0.1.1

monitoring_servers:
 - host: 10.0.1.1

grafana_servers:
 - host: 10.0.1.1

执行集群部署命令：
```
tiup cluster deploy <cluster-name> <version> ./tidb-topology.yaml --user root -p
```
- 参数 <cluster-name> 表示设置集群名称
- 参数 <version> 表示设置集群版本，例如 v7.1.8-5.2。可以通过 tiup list tidb 命令来查看当前支持部署的平凯数据库版本
- 参数 -p 表示在连接目标机器时使用密码登录
注意
如果主机通过密钥进行 SSH 认证，请使用 -i 参数指定密钥文件路径，-i 与 -p 不可同时使用。
按照引导，输入”y”及 root 密码，来完成部署：
```
Do you want to continue? [y/N]:  y
Input SSH password:
```
启动集群：
```
tiup cluster start <cluster-name>
```
访问集群：
- 安装 MySQL 客户端。如果已安装 MySQL 客户端则可跳过这一步骤。
```
yum -y install mysql
```
- 访问平凯数据库，密码为空：
```
mysql -h 10.0.1.1 -P 4000 -u root
```
- 访问平凯数据库的 Grafana 监控：
  通过 http://{grafana-ip}:3000 访问集群 Grafana 监控页面，默认用户名和密码均为 admin。
- 访问平凯数据库的 Dashboard：
  通过 http://{pd-ip}:2379/dashboard 访问集群 TiDB Dashboard 监控页面，默认用户名为 root，密码为空。
- 执行以下命令确认当前已经部署的集群列表：
```
tiup cluster list
```
- 执行以下命令查看集群的拓扑结构和状态：
```
tiup cluster display <cluster-name>
```

探索更多

如果你刚刚部署好一套平凯数据库本地测试集群，你可以继续：

学习平凯数据库 SQL 操作
学习迁移数据到平凯数据库

如果你准备好在生产环境部署平凯数据库，你可以继续：

如果你想使用 TiFlash 作为数据分析的解决方案，可参阅以下文档：