帮你快速理解、总结文档立即下载

TDE 透明加密

最近更新时间:2026-11-16 17:18:02
我的收藏
TDE(Transparent Data Encryption,透明数据加密)是 TCHouse-D 提供的存储层静态加密能力,用于防止物理磁盘、备份文件、快照等落盘数据被窃取后导致的明文泄露。TDE 只作用于数据落盘时的加解密,对上层 SQL 完全透明:业务侧的写入、查询、索引、Compaction、备份恢复等操作均无需任何 SQL 改造。

相关概念

密钥体系

TDE 采用三层密钥体系
层级
说明
作用
Root Key(根密钥)
最外层密钥,存放在 FE 本地文件中或托管在腾讯云 KMS 中。
本身不参与数据加解密,仅用于加密 Master Key。全集群唯一。
Master Key(主密钥)
由 Root Key 加密,明文缓存在 FE 内存中。
分 AES256 / SM4 两族,用于加解密 Data Key。
Data Key(数据密钥)
每个 Tablet 一把,密文随 Tablet 元数据持久化。
真正用于加解密数据 Block。
支持的加密算法
AES256:AES-256-CTR,通用推荐。
SM4:SM4-CTR,国密算法。
PLAINTEXT:不加密(默认值,表示该表以明文落盘)。
说明:
Root Key 与 Master Key 的算法由 encryption_algorithm 参数指定。
Data Key 使用的算法由建表时的 tde_algorithm 表属性决定,且一张表只能选一种算法。

Root Key 提供方式

TDE 支持两种 Root Key 提供方式(Root Key Provider):
1. LOCAL:Root Key 存放在 FE 本地文件中,文件内容为 Base64 编码的密钥字节。
2. TENCENT_KMS:Root Key 托管在腾讯云 KMS 中,通过 CMK ID 引用。
两种方式均需在首次使用时通过 SQL 设置 Root Key,具体见 步骤一:设置 Root Key。

使用前提与限制

前置准备

1. 您已创建 TCHouse-D 集群,并具备集群 ADMIN 权限。
2. 根据所选 Root Key 提供方式准备对应资源:
LOCAL 方式:已准备一个用于存放 Root Key 的本地文件,文件内容为 Base64 编码的密钥字节,通过 控制台配置文件 上传成功。
TENCENT_KMS 方式:已在腾讯云 密钥管理系统 KMS 中创建 CMK(用户主密钥),并已获取该 CMK 的 CMK ID、所在地域(Region)及调用密钥所需的 AccessKey / SecretKey。
注意:
安全提示 Root Key 是解密数据的关键。请务必妥善保管 Root Key,并与集群数据分开保管:
LOCAL 方式:请务必独立备份 Root Key 文件,文件一旦丢失,已加密的数据将永久无法解密。
TENCENT_KMS 方式:请为 CMK 开启不可删除保护,并开启 KMS 侧的密钥备份;CMK 被误删或权限变更将导致数据无法解密。

相关限制

1. 只支持建表时指定加密:tde_algorithm 属性只能在建表时生效,ALTER TABLE 无法修改。已有明文表无法在线转为加密表,加密表也无法在线换算法或关闭加密。
2. 分区级加密未支持:ADD PARTITION ... PROPERTIES ("tde_algorithm" = ...) 中的加密属性会被静默忽略,新分区仍继承表级算法。
3. Root Key 只能 SET 一次:ADMIN SET ENCRYPTION ROOT KEY 为一次性操作,更换 Root Key 必须走 ADMIN ROTATE TDE ROOT KEY。
4. Root Key 类型不能互换:ROTATE ROOT KEY 时必须与当前 Root Key 类型一致(LOCAL ↔ TENCENT_KMS 不可互切)。如需更换提供方式,需通过数据导出 + 重建集群完成。
5. 不支持列级加密:加密粒度为表 / Tablet,不支持只加密某一列。

操作步骤

步骤一:设置 Root Key

在使用 TDE 之前,必须先设置 Root Key。Root Key 只允许设置一次,重复设置会报错;后续如需更换,请使用 步骤四:轮转 Root Key。
LOCAL 方式:登录 腾讯云数据仓库 TCHouse-D 控制台,进入集群详情 > 修改配置 > 配置文件上传。
TENCENT_KMS 方式:
ADMIN SET ENCRYPTION ROOT KEY PROPERTIES (
"type" = "TENCENT_KMS",
"encryption_algorithm" = "AES256",
"cmk_id" = "kms-cmk-xxxx",
"region" = "ap-guangzhou",
"endpoint" = "kms.tencentcloudapi.com",
"ak" = "<AccessKey>",
"sk" = "<SecretKey>"
);
参数说明:
参数
说明
type
Root Key 提供方类型,支持 TENCENT_KMS
encryption_algorithm
根密钥加密算法,支持 AES256 / SM4
cmk_id
KMS CMK ID
region
KMS 所在地域
endpoint
KMS 服务 endpoint
ak / sk
调用 KMS 所需的 AccessKey / SecretKey
执行成功后,系统会生成 AES256 与 SM4 两把 Master Key(version = 1),并启动 Master Key 定时轮转线程。

步骤二:查看密钥状态

设置 Root Key 后,可查看当前密钥状态:
SHOW ENCRYPTION ROOT KEY;
SHOW ENCRYPTION MASTER KEYS;
说明:
1. 以上命令均需 ADMIN 权限。
2. 返回值将会有如下安全脱敏措施:
ak 仅显示前 4 位 + ****+ 后 4 位。
sk 绝不返回。
Master Key 的明文不会返回。
Master Key 密文仅保留前 8 位,其余以 **** 显示。

步骤三:创建加密表

在 CREATE TABLE 语句中通过 tde_algorithm 表属性指定加密算法:
CREATE TABLE t_enc (
id BIGINT,
val VARCHAR(64)
)
DUPLICATE KEY(id)
DISTRIBUTED BY HASH(id) BUCKETS 3
PROPERTIES (
"replication_num" = "3",
"tde_algorithm" = "AES256"
);
说明:
tde_algorithm 支持 AES256 / SM4 / PLAINTEXT。
未指定时使用集群配置项 doris_tde_algorithm 的默认值(默认 PLAINTEXT)。
加密表的写入、查询、索引、Compaction 均完全透明,SQL 无需改动。

步骤四:轮转 Root Key(可选)

如需更换 Root Key,可使用以下命令。更换后 Master Key 明文不变,仅使用新 Root Key 重新加密,对数据读取完全透明,历史数据无需重新加密。
注意:
轮转时必须与当前 Root Key 类型保持一致(LOCAL↔ TENCENT_KMS 不可互切)。
1. LOCAL → LOCAL:在控制台重新上传 Root Key 文件。
2. TENCENT_KMS → TENCENT_KMS:更换 CMK。
ADMIN ROTATE TDE ROOT KEY PROPERTIES (
"doris_tde_key_provider" = "TENCENT_KMS",
"doris_tde_key_id" = "kms-cmk-yyyy",
"doris_tde_key_ak" = "<AK>",
"doris_tde_key_sk" = "<SK>",
"doris_tde_key_endpoint" = "kms.tencentcloudapi.com",
"doris_tde_key_region" = "ap-guangzhou"
);
参数说明:
参数
说明
doris_tde_key_provider
Root Key 提供方类型,需与当前类型一致(TENCENT_KMS)
doris_tde_key_id
新的 KMS CMK ID
doris_tde_key_ak / doris_tde_key_sk
调用 KMS 所需的 AccessKey / SecretKey
doris_tde_key_endpoint
KMS 服务 endpoint
doris_tde_key_region
KMS 所在地域
注意:
轮转 Root Key 前,请确认新的 Root Key 已备份妥当(LOCAL 方式为密钥文件、KMS 方式为 CMK 及其备份)。轮转过程会对密钥进行完整校验,校验通过后才会生效,以避免半成功状态。

后续操作

权限说明

ADMIN SET ENCRYPTION ROOT KEY、ADMIN ROTATE TDE ROOT KEY、SHOW ENCRYPTION ROOT KEY、SHOW ENCRYPTION MASTER KEYS 均要求 ADMIN 全局权限。
普通用户执行上述命令会得到 Access denied 错误。
创建加密表、查询加密表沿用普通表的权限模型,加密对权限模型透明。

明文表转加密表

如需将已有明文表转为加密表,可参考以下变通方式:
CREATE TABLE t_new (...) PROPERTIES ("tde_algorithm" = "AES256");
INSERT INTO t_new SELECT * FROM t_old;
ALTER TABLE t_old RENAME t_old_bak;
ALTER TABLE t_new RENAME t_old;

观测与运维

关键指标(Prometheus)

指标
说明
doris_fe_tde_rotate_master_key_success
Master Key 轮转成功次数
doris_fe_tde_rotate_master_key_failed
Master Key 轮转失败次数
doris_fe_tde_rotate_root_key_success
Root Key 轮转成功次数
doris_fe_tde_rotate_root_key_failed
Root Key 轮转失败次数
doris_fe_tde_kms_call_failed
KMS 调用失败次数

关键日志(fe.log)

日志
说明
TDE is enabled, loading master keys
FE 启动加载 Master Key
Load master key successfully
单把 Master Key 解密加载成功
Rotate master key successfully
Master Key 自动轮转成功
Rotate root key successfully
Root Key 轮转成功
failed to load master key ... FE will exit
CRC 校验失败,FE 主动退出防止误用

备份与灾备建议

1. LOCAL 方式:Root Key 文件必须独立备份,并与集群数据分开保管;丢失即数据永久不可解密。
2. TENCENT_KMS 方式:CMK 必须开启不可删除保护,并开启 KMS 侧的密钥备份。
3. Master Key 明文只存在于 FE 内存中,落盘内容均为密文,依赖 Root Key 才能解密。
4. 备份恢复跨集群时,目标集群必须能访问同一 Root Key(LOCAL 方式为同一密钥文件、KMS 方式为同一 CMK),否则恢复后无法解密。

更多限制说明

1. WAL 加密独立开关:Group Commit 的 async_mode 会将数据先落到 WAL 文件再刷 Rowset,WAL 是否加密由独立的 BE 配置 enable_wal_tde 控制,默认关闭。若同时使用加密表 + Group Commit async_mode,且要求 WAL 也加密,需在所有 BE 节点显式开启 enable_wal_tde = true。普通同步写入与 sync_mode Group Commit 不涉及 WAL,不受该开关影响。
2. CRC 校验失败会导致 FE 退出:FE 启动加载 Master Key 时若发现 CRC 校验不匹配,会直接退出,这是防御性设计。排障时请优先确认 Root Key 是否可用(LOCAL 方式为密钥文件、KMS 方式为 CMK 是否被误删或权限变更)、镜像(image)是否为最新。
3. 密钥导出能力受限:任何接口都不返回密钥明文,加密表数据无法通过 SQL 显式导出为明文或重新加密的形式。
4. 不支持自定义 IV / Nonce:由 BE 自动派生,用户不可控。
5. 写入路径固定为先压缩再加密:不支持切换顺序。

常见问题

Q1:忘了先 SET Root Key 就建加密表?

会报错 Root key not set 或建表失败。先执行 ADMIN SET ENCRYPTION ROOT KEY 再建表即可。

Q2:SHOW ENCRYPTION MASTER KEYS 返回空?

未 SET Root Key 时返回空结果;SET 之后至少会有 2 把(AES256 v1 + SM4 v1)。

Q3:FE 主备切换后加密表能否继续读写?

可以。所有密钥变更都会同步给 Follower,新主切换完成后即可继续服务。

Q4:master 能作为列名吗?

可以。master 已加入非保留字列表,SELECT master FROM t; 或 CREATE TABLE t (master INT) 均可正常使用。

Q5:加密后性能损耗多少?

CTR 模式的 AES256 / SM4 的 CPU 开销约为 5% ~ 10%,可通过 AES-NI 指令集硬件加速大幅降低。