存储加密

大约 4 分钟

TimechoDB 支持对配置文件、权限文件和 TsFile 数据文件进行加密，降低敏感配置、授权信息和业务数据以明文形式落盘所带来的泄露风险。

本页介绍的功能自 V2.0.11.1 起提供。启用前请阅读本页的功能限制，并确认现有备份、恢复和数据导入流程是否支持加密数据。

1. 加密范围

加密对象	保护内容	配置入口
配置文件	ConfigNode、DataNode 的系统配置	`enable_encrypt_config_file`
权限文件	用户、角色和权限相关的持久化文件	`enable_encrypt_permission_file`
TsFile 数据文件	数据库写入的时序数据	`encrypt_type` 及数据加密口令环境变量

TimechoDB 可以分别加密节点配置文件和权限文件。两项功能可以单独启用。

在 iotdb-system.properties 中设置以下参数：

参数	默认值	说明
`enable_encrypt_config_file`	`false`	是否加密配置文件。`true` 表示启用，`false` 表示关闭。加密算法由系统指定，无需额外配置。

配置示例：

enable_encrypt_config_file=true

首次启用前，请在明文 iotdb-system.properties 中完成配置。节点启动成功后，系统将删除该明文文件，并生成对应节点的加密配置文件：

加密配置文件不能直接查看或还原为明文。原明文配置文件将在节点启动成功后被删除。

启用前请确认初始配置正确。启用后，请通过 SET CONFIGURATION 修改配置；不能通过读取加密文件找回原配置内容。

配置文件加密后，请使用 SET CONFIGURATION 修改配置。配置是否立即生效取决于具体参数；需要重启的参数应在修改后重启对应节点。

SET CONFIGURATION "key1" = "value1";

修改指定节点时，可在语句中指定节点 ID。完整语法及参数生效方式请参见运维语句中的更新配置项。

在 iotdb-system.properties 中设置以下参数：

参数	默认值	说明
`enable_encrypt_permission_file`	`false`	是否加密权限文件。`true` 表示启用，`false` 表示关闭。加密算法由系统指定，无需额外配置。

配置示例：

enable_encrypt_permission_file=true

启用权限文件加密后，ConfigNode 将在启动时加密用户、角色和权限文件。

启用 TsFile 加密后，新写入的数据将自动加密，查询时自动解密。现有业务应用不需要修改 SQL 或数据读写代码。

在 iotdb-system.properties 中设置 encrypt_type：

配置值	说明
`org.apache.tsfile.encrypt.UNENCRYPTED`	不加密，为默认值。
`com.timecho.iotdb.commons.encrypt.AES128.AES128`	使用 AES-128 加密实现。
`com.timecho.iotdb.commons.encrypt.SM4128.SM4128`	使用 SM4-128 国密加密实现。

环境变量	是否必需	说明
`user_encrypt_token`	是	用于加密和读取 TsFile 数据的口令。每次启动节点前都必须设置，并且必须与首次启用加密时使用的值一致。
`user_encrypt_token_hint`	否	可选的口令提示。当启动时提供的 `user_encrypt_token` 不正确时，系统显示该提示，帮助用户确认应使用的口令。

警告：必须备份并妥善保存 user_encrypt_token。该口令丢失或填写错误时，节点将无法读取已有加密数据，且无法通过加密文件恢复该口令。

配置 AES-128 示例：

encrypt_type=com.timecho.iotdb.commons.encrypt.AES128.AES128

Linux Bash 环境变量示例：

export user_encrypt_token="<encryption_token>"
export user_encrypt_token_hint="<token_hint>"

Windows PowerShell 环境变量示例：

$env:user_encrypt_token = "<encryption_token>"
$env:user_encrypt_token_hint = "<token_hint>"

环境变量只对当前终端及其启动的进程生效。请在设置环境变量的同一终端中启动 TimechoDB。