使用加密密码文件运行 Dumpling 和 TiDB Lightning

Dumpling 和 TiDB Lightning 支持从加密文件中读取数据库密码，避免在命令行或配置文件中填写明文密码。使用时需要准备两个文件：

密钥文件：用于加密和解密数据库密码。
加密密码文件：由 tidb-credential 工具生成，保存加密后的数据库密码。

本文介绍如何生成这两个文件，并用于导出和导入数据。该功能只保护数据库连接密码，不加密导出或导入的数据文件。

获取 tidb-credential

你可以通过 TiUP 获取 tidb-credential，也可以从企业版发布包中获取安装包并手动部署。

使用 TiUP 联网部署（推荐）

执行如下命令安装 TiUP 工具：
```
curl --proto '=https' --tlsv1.2 -sSf https://tiup-mirrors.pingcap.com/install.sh | sh
```
安装完成后，你需要新开一个终端，或按照 TiUP 输出的提示执行 source ~/.bashrc，使 TiUP 路径生效。配置文件也可能是 ~/.profile，以 TiUP 输出为准。已安装 TiUP 的用户可以跳过此步骤。
安装 TiUP tidb-credential 组件：
```
tiup install tidb-credential
```

注意

tidb-credential 需要使用包含该组件的企业版 TiUP 镜像。如果提示找不到组件，请先设置 TiUP 镜像。可用版本可以通过 tiup list tidb-credential 查看，安装和运行指定版本的方法参见 TiUP 组件管理。

手动部署

从企业版发布包中获取所使用版本的 tidb-credential 安装包。以下以 Linux amd64 架构为例，将 ${version} 替换为安装包的版本号；使用 arm64 架构时，将包名中的 amd64 替换为 arm64。

解压安装包即可获得 tidb-credential 可执行文件：

tar -zxvf tidb-credential-${version}-linux-amd64.tar.gz
chmod +x tidb-credential

手动部署后，使用 ./tidb-credential 运行工具。下文以 TiUP 部署方式为例；手动部署时，将命令中的 tiup tidb-credential 替换为 ./tidb-credential 即可。

准备工具

准备支持加密密码文件功能的 Dumpling 或 TiDB Lightning，并将可执行文件所在目录加入 PATH。可以通过以下命令确认工具提供所需的参数：

tiup tidb-credential encrypt --help
dumpling --help
tidb-lightning --help

其中，Dumpling 应提供 --password-encrypted-file 和 --password-key-file，TiDB Lightning 应提供 --tidb-password-encrypted-file 和 --tidb-password-key-file。如果提示未知参数，请更换为支持本功能的版本。

以下示例使用 OpenSSL 生成密钥，并假设所有命令都在同一工作目录执行。请根据实际环境修改数据库地址、用户名和文件路径。

生成密钥文件

首次使用时，执行以下命令创建密钥文件。请妥善保存密钥，不要覆盖仍在使用的密钥文件。

mkdir -p ./credentials
chmod 700 ./credentials
umask 077
openssl rand -hex 16 > ./credentials/password.key

密钥文件需要包含 32 个十六进制字符，末尾可以有一个换行符（LF）。文件权限必须为 0400 或 0600，否则工具会拒绝读取。以上命令创建的密钥文件权限为 0600。

生成加密密码文件

执行以下命令，按提示输入数据库密码并再次确认。输入时不会显示密码。

tiup tidb-credential encrypt \
  --key-file ./credentials/password.key \
  --output ./credentials/db-password.enc

其中，--key-file 指定上一步的密钥文件，--output 指定新建的加密密码文件。生成的加密密码文件权限为 0600。如果输出路径已经存在，命令会报错，不会覆盖原文件。

tidb-credential 也支持从标准输入读取密码，适用于脚本调用。此时不会二次确认，并会保留输入中的所有字节，包括末尾换行；请确保输入内容与数据库密码完全一致。

生成文件不会修改数据库账户的密码。Dumpling 需要源数据库用户的密码，TiDB Lightning 需要目标数据库用户的密码；如果两者不同，请分别生成加密密码文件。

在 Dumpling 中使用

通过 --password-encrypted-file 和 --password-key-file 指定两个文件。例如，使用 db_user 用户将 app 数据库导出到 ./export：

dumpling \
  -h 127.0.0.1 -P 4000 -u db_user \
  --password-encrypted-file ./credentials/db-password.enc \
  --password-key-file ./credentials/password.key \
  --filter 'app.*' --filetype sql -F 256MiB -o ./export

使用加密密码文件时，请移除原命令中的非空 -p 或 --password 参数。其他导出参数和所需数据库权限不变，详见使用 Dumpling 导出数据。

在 TiDB Lightning 中使用

使用配置文件

在配置文件的 [tidb] 部分填写 password-encrypted-file 和 password-key-file，并移除原有的非空 password 配置。以下 tidb-lightning.toml 示例使用逻辑导入模式：

[tidb]
host = "127.0.0.1"
port = 4000
user = "db_user"
password-encrypted-file = "./credentials/db-password.enc"
password-key-file = "./credentials/password.key"

[mydumper]
data-source-dir = "./export"

[tikv-importer]
backend = "tidb"

执行以下命令开始导入：

tidb-lightning --config ./tidb-lightning.toml

使用命令行参数

也可以直接通过命令行指定加密密码文件和密钥文件：

tidb-lightning \
  --backend tidb \
  --tidb-host 127.0.0.1 --tidb-port 4000 --tidb-user db_user \
  --tidb-password-encrypted-file ./credentials/db-password.enc \
  --tidb-password-key-file ./credentials/password.key \
  -d ./export

请移除原命令中的非空 --tidb-password 参数。命令行中指定的文件路径会覆盖配置文件中对应的路径，但不会自动清除配置文件中的明文密码。

tidb-lightning-ctl 也支持这两个命令行参数。在需要使用 [tidb] 连接密码的操作中，例如使用默认连接信息访问 MySQL 断点数据库时，会读取加密密码文件。如果显式配置了 [checkpoint].dsn，其中的密码仍按 DSN 使用，不受加密密码文件保护。

使用注意事项

加密密码文件和密钥文件必须同时配置，且不能与非空的明文密码配置混用。配置错误或解密失败时，工具会报错，不会回退到明文密码。
两个文件都必须是运行工具的操作系统用户可读取的普通文件。相对路径以工具进程的工作目录为基准，而不是配置文件所在目录；在脚本或服务中运行时，建议使用绝对路径。
妥善保管密钥文件。能够同时读取密钥文件和加密密码文件的人可以解密数据库密码。
数据库密码变更后，请使用新密码生成另一个加密密码文件，更新配置路径，再启动新的导出或导入任务。正在运行的任务不会自动重新读取文件。