在飞牛NAS上搭建自己的代码仓库并实现外部访问
2026/7/27 9:53:51
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[...]，用于校验密文是否正确 |
典型使用方式：
# 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 变为：
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.2ENC[...]密文格式是什么？
v4.0.0 使用统一的密文格式：
ENC[v1:aes256gcm:<kid>:<nonce_b64url>:<ciphertext_b64url>] |
各字段含义如下：
| 字段 | 说明 |
|---|---|
v1 | 密文格式版本 |
aes256gcm | 加密算法：AES-256-GCM |
| `` | key id，默认default，为后续密钥轮换预留 |
| `` | 随机 nonce，使用 base64 URL-safe 编码 |
| `` | 密文和认证标签，使用 base64 URL-safe 编码 |
示例：
ENC[v1:aes256gcm:default:REPLACE_NONCE:REPLACE_CIPHERTEXT] |
需要注意的是，只加密 password 片段，不会加密 host、port、库名、charset、SSL 参数等连接配置信息。例如：
# 加密前（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 实现：
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时读取该环境变量 |
示例：
# 使用环境变量 |
GT_CHECKSUM_DSN_KEY="$KEY" gt-checksum -c ./gc.conf |
# 使用 --key 覆盖环境变量 |
gt-checksum -c ./gc.conf --key "$KEY" |
repairDB 和 gt-dsn-crypt 也使用同样的 key 机制：
# 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 是明文：直接报错退出