Skip to main content

Dotenvx全局秘钥存储格式变更,更好地支持后续特性

· 2 min read
Libing Chen
Java程序员,兼全栈、Rust和AI开发

dotenvx的秘钥之前都是保存在项目目录下的.env.keys文件中,其格式如下:

DOTENV_PRIVATE_KEY=c4e79fecc6bfeb1fe3bf4d783ddf3303xxx
DOTENV_PRIVATE_KEY_TEST=82056174ece6e87e76084c224ayyyy
DOTENV_PRIVATE_KEY_PERF=fc9067f0a82c022fedbc221a169zzzzz

但是考虑到当下的AI编程大潮下,将.env.keys文件放在项目目录下,会被AI Agent或者AI IDE扫描,容易造成秘钥泄露, 所以个人决定接入全局秘钥存储文件,并且将其放在$HOME/.dotenvx/.env.keys.json文件中,这样就不再需要.env.keys文件, 私钥的查询都是走全局的.env.keys.json文件。 此外dotenvx命令行还提供了dotenvx --seal命令,对次文件进行加密保存,保证安全。

注意:如果你还是担心.env.keys.json文件泄露,企业版dotenvx提供了操作系统的key-chain和KeePass集成,这样进一步保证了秘钥的安全。

刚开始设计全局存储的时候,并没有特别考虑文件格式,就是一个普通的json文件,仅保存公钥和私钥的映射关系。 但是随着dotenvx的功能越来越多,同时也需要对接云端备份,之前文件格式就无法满足更多的一些要求,所以需要一个新的文件格式,样例如下:

{
"version": "0.1.0",
"metadata": {
"uuid": "09f406f9-82bc-4c0a-910b-259c60cd84f6"
},
"keys": {
"023cf16fd02bdb0d938d31e6b5876": {
"public_key": "023cf16fd02bdb0d938d31e6b5876",
"private_key": "0967931055d80d414c366bc3",
"path": "/Users/user1/PycharmProjects/py-demo/.env",
"group": null,
"name": null,
"profile": null,
"comment": null,
"timestamp": "2025-08-16T20:57:50.304166+08:00"
}
}
}

.env.keys.json文件的格式主要包括三部分:

  • 版本号:主要标识当前文件格式的版本,如果后续文件格式有升级,可以通过版本号进行区分。
  • 元数据:主要包括文件的UUID等信息,这个主要方便后续的文件交换和备份等,当前uuid是必须的字段,用于唯一标识一个.env.keys.json文件。
  • keys:主要是公钥和私钥的映射关系,同时不包括一些密钥对的元信息,如group,path等

借助新的文件格式,.env.keys.json文件可以承载更多的信息,如云端备份、KeePass对接等,同时包括私钥的审计,这样特性的实现就方便很多啦。

新的格式要求SDK、命令行工具和JetBrains IDE插件都需要进行升级,才能支持新的文件格式。SDK可能还有一些兼容问题,建议进行升级。