在数据库校验和修复工具中，连接串几乎是最敏感的配置之一。过去为了使用方便，很多配置文件会直接写入数据库明文密码。

gt-checksum v4.0.0 起，srcDSN / dstDSN 中的 password 必须使用 ENC[...] 密文，并新增独立工具 gt-dsn-crypt 生成 32 字节 base64 key 与 AES-256-GCM 密文，让连接串密码保护从"建议项"变成"强约束"。

一、功能简介

$yejr@db160 gt-checksum$ $ cat docs/gt-checksum-v4.0.0-dsn-encrypt-article.md

gt-checksum v4.0.0 新功能解读系列文章（5）：DSN 密文保护------连接串密码不再明文裸奔

在数据库校验和修复工具中，连接串几乎是最敏感的配置之一。过去为了使用方便，很多配置文件会直接写入数据库明文密码。

gt-checksum v4.0.0 起，srcDSN / dstDSN 中的 password 必须使用 ENC[...] 密文，并新增独立工具 gt-dsn-crypt 生成 32 字节 base64 key 与 AES-256-GCM 密文，让连接串密码保护从"建议项"变成"强约束"。

一、功能简介

v4.0.0 新增连接串密码加密能力，核心变化可以概括为三点：

能力	说明
`ENC[...]` 密文格式	`srcDSN` / `dstDSN` 中的 password 必须使用 `ENC[...]` 密文
`gt-dsn-crypt` 工具	独立生成 key、加密 password、解密校验密文
统一日志脱敏	gt-checksum、repairDB、连接池日志均不会完整输出明文 password 或密文

新增工具：gt-dsn-crypt

gt-dsn-crypt 提供三个子命令：

子命令	作用
`gen-key`	生成 32 字节随机 key，并以 base64 输出
`encrypt`	使用 key 将明文 password 加密为 `ENC[...]` 密文
`decrypt`	使用 key 解密 `ENC[...]`，用于校验密文是否正确

典型使用方式：

bash 复制代码

# 1. 生成 32 字节 base64 key
KEY=$(gt-dsn-crypt gen-key)

# 2. 推荐从文件读取 password，避免明文进入 shell history
printf '%s' '数据库密码' > ./password.txt

# 3. 生成 ENC[...] 密文
GT_CHECKSUM_DSN_KEY="$KEY" gt-dsn-crypt encrypt --password-file ./password.txt

# 4. 启动 gt-checksum 时提供同一个 key
GT_CHECKSUM_DSN_KEY="$KEY" gt-checksum -c ./gc.conf

配置文件中的 DSN 变为：

ini 复制代码

srcDSN=mysql|user:ENC[v1:aes256gcm:default:...:...]@tcp(src-host:3306)/information_schema?charset=utf8mb4
dstDSN=mysql|user:ENC[v1:aes256gcm:default:...:...]@tcp(dst-host:3306)/information_schema?charset=utf8mb4

二、功能作用及使用场景深入解读

2.1 为什么要强制加密 DSN password？

在生产环境中，明文数据库密码的风险远比想象中更常见：

场景一：配置文件泄露

gc.conf 通常会被放在运维目录、部署目录或自动化平台中。一旦目录权限配置不当，明文数据库密码就可能被非授权用户读取。

场景二：日志与报错泄露

工具启动失败、参数校验失败、连接池初始化失败时，如果直接打印 DSN，明文 password 可能进入终端日志、CI 日志、工单截图或监控采集系统。

场景三：多人协作与审计

迁移项目通常涉及 DBA、研发、运维、测试多角色协作。配置文件被多人传递时，明文密码会在聊天工具、邮件、文档中扩散，后续很难追踪和回收。

场景四：临时文件与历史命令残留

即使最终配置文件被删除，明文密码仍可能残留在 shell history、备份文件、编辑器 swap 文件中。加密后，即使密文泄露，没有 key 也无法直接还原 password。

因此，v4.0.0 不再只是"建议不要写明文密码"，而是在启动阶段直接校验：DSN password 不是 ENC[...]，程序 fail-fast 退出。

2.2 `ENC[...]` 密文格式是什么？

v4.0.0 使用统一的密文格式：

text 复制代码

ENC[v1:aes256gcm:<kid>:<nonce_b64url>:<ciphertext_b64url>]

各字段含义如下：

字段	说明
`v1`	密文格式版本
`aes256gcm`	加密算法：AES-256-GCM
``	key id，默认 `default`，为后续密钥轮换预留
``	随机 nonce，使用 base64 URL-safe 编码
``	密文和认证标签，使用 base64 URL-safe 编码

示例：

text 复制代码

ENC[v1:aes256gcm:default:REPLACE_NONCE:REPLACE_CIPHERTEXT]

需要注意的是，只加密 password 片段，不会加密 host、port、库名、charset、SSL 参数等连接配置信息。例如：

ini 复制代码

# 加密前（v4.0.0 起不再支持）
srcDSN=mysql|user:plain_password@tcp(src-host:3306)/information_schema?charset=utf8mb4

# 加密后
srcDSN=mysql|user:ENC[v1:aes256gcm:default:...:...]@tcp(src-host:3306)/information_schema?charset=utf8mb4

这种设计兼顾了安全性和可运维性：密码被保护起来，但连接目标、库名和参数仍然可见，便于排查配置问题。

2.3 AES-256-GCM：同时保证保密性和完整性

gt-dsn-crypt 使用 Go 标准库中的 AES-GCM 实现：

go 复制代码

block, _ := aes.NewCipher(key)
gcm, _ := cipher.NewGCM(block)
nonce := make([]byte, gcm.NonceSize())
rand.Read(nonce)
ciphertext := gcm.Seal(nil, nonce, []byte(password), nil)

这里有几个关键点：

key 必须是 32 字节：对应 AES-256。
每次加密都会生成随机 nonce ：同一个 password 用同一个 key 加密两次，也会得到不同的 ENC[...] 密文。
GCM 自带认证标签：解密时会校验密文是否被篡改。如果 key 错误或密文被修改，会返回解密失败，而不是输出错误的 password。

这意味着 ENC[...] 不只是"混淆字符串"，而是具备认证加密能力的密文格式。

2.4 key 从哪里来？

v4.0.0 的 key 管理遵循两个原则：不内置默认 key，不从配置文件读取 key。

key 来源只有两种：

来源	优先级	说明
`--key`	最高	命令行参数，覆盖环境变量
`GT_CHECKSUM_DSN_KEY`	次高	未指定 `--key` 时读取该环境变量

示例：

bash 复制代码

# 使用环境变量
GT_CHECKSUM_DSN_KEY="$KEY" gt-checksum -c ./gc.conf

# 使用 --key 覆盖环境变量
gt-checksum -c ./gc.conf --key "$KEY"

repairDB 和 gt-dsn-crypt 也使用同样的 key 机制：

bash 复制代码

# repairDB 使用环境变量
GT_CHECKSUM_DSN_KEY="$KEY" repairDB -conf ./gc.conf ./fixsql

# repairDB 使用 --key
repairDB -conf ./gc.conf --key "$KEY" ./fixsql

# gt-dsn-crypt encrypt 使用 --key
gt-dsn-crypt encrypt --key "$KEY" --password-file ./password.txt

v4.0.0 不支持密钥文件 ，也不支持把 key 写在 gc.conf 中。这是为了避免"密码加密了，但解密 key 又和配置文件放在一起"的伪安全。

2.5 启动阶段 fail-fast：明文密码直接拒绝

gt-checksum 在读取配置时会立即解析 srcDSN / dstDSN，并调用统一的连接串解析逻辑，要求连接串中 必须使用密文。

因此：

password 是 ENC[...]：加载 key 并解密
password 是明文：直接报错退出
password 为空：直接报错退出
key 缺失或 key 长度不是 32 字节：直接报错退出
密文格式错误、版本不支持、认证失败：直接报错退出

这种 fail-fast 设计可以把风险拦截在任务启动阶段，避免校验或修复运行到一半才发现连接串不可用。

2.6 MySQL 与 Oracle DSN 都支持

v4.0.0 的连接串加密不只支持 MySQL-family，也支持 Oracle。

MySQL-family：

ini 复制代码

srcDSN=mysql|user:ENC[v1:aes256gcm:default:...:...]@tcp(src-host:3306)/information_schema?charset=utf8mb4
dstDSN=mysql|user:ENC[v1:aes256gcm:default:...:...]@tcp(dst-host:3306)/information_schema?charset=utf8mb4

Percona Server、GreatSQL、MariaDB 等 MySQL-family 数据源同样使用 mysql| 驱动前缀。

Oracle legacy DSN：

ini 复制代码

srcDSN=oracle|scott/ENC[v1:aes256gcm:default:...:...]@ora-host:1521/orclpdb1

Oracle godror key-value DSN：

ini 复制代码

srcDSN=oracle|user="scott" password="ENC[v1:aes256gcm:default:...:...]" connectString="ora-host:1521/orclpdb1"

Oracle legacy 格式中，解密后的 password 会按路径片段做转义，避免 / 等特殊字符破坏 user/password@host 的结构；key-value 格式则会保留或补齐引号，避免空格和特殊字符导致解析错误。

2.7 日志统一脱敏：不让密文变成另一种泄露

只加密配置文件还不够。如果程序启动后把解密后的 DSN 打印到日志里，风险仍然存在。

v4.0.0 对 gt-checksum、repairDB、MySQL/Oracle 连接池日志做了统一脱敏处理：

text 复制代码

mysql|user:******@tcp(src-host:3306)/information_schema?charset=utf8mb4
oracle|scott/******@ora-host:1521/orclpdb1
oracle|user="scott" password="******" connectString="ora-host:1521/orclpdb1"

也就是说，无论 DSN 中原本是明文、ENC[...] 密文，还是运行时已解密后的真实 password，日志里都会被替换为 ******。

三、功能使用演示

3.1 生成 key

bash 复制代码

$ gt-dsn-crypt gen-key
Is7oYfqpCNZc6mD8kKY/yFevgYrjU//y4SM2K40yzM4=

$ export GT_CHECKSUM_DSN_KEY="Is7oYfqpCNZc6mD8kKY/yFevgYrjU//y4SM2K40yzM4="

这是一个 base64 编码后的 32 字节随机 key。生产环境建议把它放入安全的密钥管理系统，或通过环境变量注入任务进程。

3.2 生成 password 密文

推荐把数据库 password 写入临时文件，再使用 --password-file 加密：

bash 复制代码

$ printf '%s' 'GreatSQL@2026!' > ./password.txt

$ GT_CHECKSUM_DSN_KEY="$KEY" gt-dsn-crypt encrypt --password-file ./password.txt
ENC[v1:aes256gcm:default:Qk1...:8dF...]

也可以直接使用 --password：

bash 复制代码

gt-dsn-crypt encrypt --key "$KEY" --password 'GreatSQL@2026!'

但这种方式可能被 shell history 记录，生产环境不推荐。

3.3 写入 gc.conf

ini 复制代码

srcDSN=mysql|user:ENC[v1:aes256gcm:default:Qk1...:8dF...]@tcp(10.0.0.1:3306)/information_schema?charset=utf8mb4
dstDSN=mysql|user:ENC[v1:aes256gcm:default:9mA...:rK2...]@tcp(10.0.0.2:3306)/information_schema?charset=utf8mb4

tables=db.*
checkObject=data
datafix=file

注意：源端和目标端可以使用同一个 key 生成密文，也可以通过 kid 记录不同的 key id。但运行时当前实现需要提供能解开配置中密文的 key。

3.4 启动 gt-checksum

bash 复制代码

$ GT_CHECKSUM_DSN_KEY="$KEY" gt-checksum -c ./gc.conf

Initializing gt-checksum
Reading configuration files
Opening log files
Checking configuration options
gt-checksum: Starting table checks
...

或者使用 --key：

bash 复制代码

$ gt-checksum -c ./gc.conf --key "$KEY"

3.5 repairDB 使用密文 dstDSN

repairDB 只连接目标端，因此只读取并解密 dstDSN：

ini 复制代码

dstDSN=mysql|user:ENC[v1:aes256gcm:default:9mA...:rK2...]@tcp(10.0.0.2:3306)/information_schema?charset=utf8mb4
fixFileDir=./fixsql

执行修复：

bash 复制代码

$ GT_CHECKSUM_DSN_KEY="$KEY" repairDB -conf ./gc.conf ./fixsql

[REPAIR] Processing: table.db.orders.INSERT-1.sql ... OK
...

3.6 解密校验

如果需要确认某个密文对应的 password 是否正确，可以使用 decrypt：

bash 复制代码

$ GT_CHECKSUM_DSN_KEY="$KEY" gt-dsn-crypt decrypt --ciphertext 'ENC[v1:aes256gcm:default:Qk1...:8dF...]'
GreatSQL@2026!

解密命令建议仅在本地临时验证时使用，避免把明文输出到共享终端、CI 日志或工单系统。

3.7 明文 password 报错示例

如果配置文件仍然使用明文 password：

ini 复制代码

srcDSN=mysql|user:plain_password@tcp(10.0.0.1:3306)/information_schema?charset=utf8mb4

启动时会直接失败：

bash 复制代码

$ gt-checksum -c ./gc.conf

gt-checksum: invalid srcDSN password: dsn password must use ENC[...] ciphertext

如果没有提供 key：

bash 复制代码

$ gt-checksum -c ./gc.conf

gt-checksum: invalid srcDSN password: dsn encryption key is required

四、最佳实践及使用约束

4.1 最佳实践

1. 生产环境统一使用 --password-file 加密

相比 --password，--password-file 可以避免 password 进入 shell history：

bash 复制代码

printf '%s' '数据库密码' > ./password.txt
GT_CHECKSUM_DSN_KEY="$KEY" gt-dsn-crypt encrypt --password-file ./password.txt
rm -f ./password.txt

2. key 不要与 gc.conf 放在一起

不要把 key 写入配置文件，也不要把 key 文件和 gc.conf 放在同一目录打包传递。推荐使用：

CI/CD secret
Kubernetes Secret
操作系统环境变量
企业密钥管理系统

3. 使用 --key 覆盖临时环境变量

当同一台机器上需要执行多个不同项目的校验任务时，可以用 --key 显式指定当前任务的 key，避免误用环境变量中的旧 key：

bash 复制代码

gt-checksum -c ./gc-prod.conf --key "$PROD_DSN_KEY"

4. 日志可以共享，配置和 key 不能共享

v4.0.0 已经对 DSN 日志做了统一脱敏，因此日志文件相对更安全。但配置文件中的 ENC[...] 密文和运行时 key 仍然应按敏感信息管理。

5. 定期轮换 key 和密文

如果项目成员变更、配置文件曾经外发，建议重新生成 key，并重新生成 srcDSN / dstDSN 密文。ENC[...] 中的 kid 字段可用于记录 key id，方便人工追踪密钥版本。

6. 配合 SSL 加密连接使用

DSN 密文保护的是"静态配置文件中的 password"，SSL 保护的是"运行时网络传输中的数据"。两者解决的问题不同，生产环境建议同时启用：

ini 复制代码

srcDSN=mysql|user:ENC[...]@tcp(src-host:3306)/information_schema?charset=utf8mb4
dstDSN=mysql|user:ENC[...]@tcp(dst-host:3306)/information_schema?charset=utf8mb4
srcSslMode=VERIFY_CA
dstSslMode=VERIFY_CA

4.2 使用约束

1. 明文 password 不再兼容

v4.0.0 起，srcDSN / dstDSN 的 password 必须使用 ENC[...]。旧版本配置如果仍然使用明文 password，需要先迁移为密文格式，否则启动即失败。

2. key 必须是 base64 编码后的 32 字节随机值

gt-dsn-crypt gen-key 生成的 key 可以直接使用。如果手动生成 key，必须保证 base64 解码后长度正好为 32 字节，否则会报错：

text 复制代码

dsn encryption key must be base64 encoded 32 bytes

3. 不支持密钥文件

工具不提供 --key-file 参数，也不会从配置文件中读取 key。key 只能通过 --key 或 GT_CHECKSUM_DSN_KEY 提供。

4. 密文只保护 password，不保护完整 DSN

ENC[...] 只加密 password，host、port、库名、charset、SSL 参数等仍然以明文保留在配置文件中。这是为了保留必要的可运维信息。如果连接目标本身也属于敏感信息，需要通过配置文件权限和部署系统进行额外保护。

5. key 丢失后无法恢复 password

AES-256-GCM 是对称加密。没有正确 key，无法解密 ENC[...]。因此 key 必须妥善备份和管理；如果 key 丢失，只能重新获取数据库 password 并重新生成密文。

6. decrypt 命令会输出明文

gt-dsn-crypt decrypt 是为了本地校验密文是否正确，输出结果就是明文 password。不要在共享终端、CI pipeline、公开日志中执行该命令。

五、总结

gt-checksum v4.0.0 的 DSN 密文保护能力，把连接串密码安全提升到了默认强制级别。配置文件中不再允许明文 password，启动时必须通过 --key 或 GT_CHECKSUM_DSN_KEY 提供 32 字节 base64 key，程序在内存中解密后连接数据库，并对所有 DSN 日志输出统一脱敏。

围绕这一能力，v4.0.0 形成了一套完整闭环：

gt-dsn-crypt gen-key：生成 32 字节随机 key
gt-dsn-crypt encrypt：生成 AES-256-GCM ENC[...] 密文
gt-dsn-crypt decrypt：本地解密校验
gt-checksum --key / GT_CHECKSUM_DSN_KEY：运行时解密 srcDSN / dstDSN
repairDB --key / GT_CHECKSUM_DSN_KEY：运行时解密 dstDSN
日志统一脱敏：避免明文或密文再次泄露

一句话总结 ：srcDSN=mysql|user:ENC[...]@...，让数据库密码不再出现在配置文件和日志里。

相关阅读

gt-checksum v4.0.0 新功能解读系列文章（1）：断点续传------大任务中断不再从头跑

gt-checksum v4.0.0 新功能解读系列文章（2）：自定义数据类型映射------适配复杂迁移场景

gt-checksum v4.0.0 新功能解读系列文章（3）：反向回滚 SQL------修复可审计、可回退

gt-checksum v4.0.0 新功能解读系列文章（4）：反向回滚 SQL------修复可审计、可回退

gt-checksum v4.0.0 发布：可续跑、可回滚、可审计的数据校验与修复能力全面升级

gt-checksum 使用手册

gt-checksum v4.0.0 新功能解读系列文章（5）：DSN 密文保护——连接串密码不再明文裸奔

一、功能简介

gt-checksum v4.0.0 新功能解读系列文章（5）：DSN 密文保护------连接串密码不再明文裸奔

一、功能简介

新增工具：gt-dsn-crypt

二、功能作用及使用场景深入解读

2.1 为什么要强制加密 DSN password？

2.2 ENC[...] 密文格式是什么？

2.3 AES-256-GCM：同时保证保密性和完整性

2.4 key 从哪里来？

2.5 启动阶段 fail-fast：明文密码直接拒绝

2.6 MySQL 与 Oracle DSN 都支持

2.7 日志统一脱敏：不让密文变成另一种泄露

三、功能使用演示

3.1 生成 key

3.2 生成 password 密文

3.3 写入 gc.conf

3.4 启动 gt-checksum

3.5 repairDB 使用密文 dstDSN

3.6 解密校验

3.7 明文 password 报错示例

四、最佳实践及使用约束

4.1 最佳实践

4.2 使用约束

五、总结

2.2 `ENC[...]` 密文格式是什么？