EJSON：基于JSON的配置文件加密与密钥管理方案详解
1. 项目概述：为什么我们需要EJSON？
在团队协作开发中，配置文件的管理一直是个让人头疼的问题。我们经常需要把数据库密码、API密钥、第三方服务的访问令牌这类敏感信息写进配置文件里，比如config.json或.env。直接提交到代码仓库？那无异于把自家大门的钥匙挂在网上。手动管理，每次部署前再替换？效率低下且极易出错，尤其是在微服务和自动化部署的今天。
这就是 EJSON 要解决的核心痛点。它不是一个全新的加密算法，而是一套基于 JSON 格式的、专门为开发者设计的密钥管理和文件加密方案。简单来说，它让你可以安全地将加密后的敏感配置和公开的非敏感配置一起，放心地提交到 Git 仓库中。只有持有对应私钥的团队成员或部署服务器，才能解密并读取其中的秘密。最近在搜索“git生成ssh密钥并添加到github”的朋友，可能正在为安全的远程仓库访问做准备，而 EJSON 解决的，是代码仓库内“数据”本身的安全问题，两者结合，能构建起从代码推送到配置管理的完整安全链条。
今天，我就以一个多年全栈开发者的视角，带你彻底拆解 EJSON 的核心功能。我们不只讲命令，更要讲清楚每个步骤背后的设计逻辑、安全考量，以及我在实际团队中落地这套方案时踩过的坑和总结的经验。从密钥对的生成、管理，到文件的加密、解密全流程，让你不仅能“照着做”，更能“懂得为什么这么做”。
2. EJSON 核心设计与思路拆解
2.1 EJSON 文件的结构：明暗数据的分离艺术
EJSON 文件本身就是一个合法的 JSON 文件，这是它最巧妙的设计之一。一个典型的加密后 EJSON 文件长这样：
{ “_public_key”: “a0b1c2d3e4f5...（公钥）”， “database”: { “host”: “localhost”， “port”: 5432 }， “secrets”: { “_encrypted”: [ { “_public_key”: “a0b1c2d3e4f5...”， “encrypted_value”: “EJ[1:加密后的密文...]”， “encrypted_key”: “EJ[1:加密后的密钥...]” } ] } }你可以看到，文件清晰地分成了三个部分：
_public_key：用于加密这个文件的公钥。这是一个全局声明，告诉所有人“请用这个公钥对应的私钥来解密”。- 明文部分：如
database对象。这部分是非敏感配置，所有人可见，直接参与应用运行。 secrets部分：这是核心。它包含一个_encrypted数组，里面是若干个加密对象。每个加密对象都包含：encrypted_key: 加密后的密钥。这里加密的其实是一个随机生成的对称密钥（如 AES-256-GCM 的密钥）。encrypted_value: 用上面那个对称密钥加密后的实际敏感数据。_public_key: 用于加密这个对称密钥的公钥。这里有个关键点：这个公钥可以和文件顶层的_public_key不同。这意味着，你可以用多个接收者的公钥来加密同一份敏感数据，实现一对多的安全共享。
设计逻辑解读：为什么用“非对称加密对称密钥，对称加密数据”的混合模式？因为非对称加密（如 RSA）计算慢，但适合密钥交换；对称加密（如 AES）速度快，适合加密大量数据。EJSON 采用这种“信封加密”模式，兼具了安全性和性能。每次加密敏感字段时，都会生成一个全新的随机对称密钥，即使加密同一个值两次，得到的密文也完全不同，提升了安全性。
2.2 密钥体系：个人、项目与部署密钥
理解 EJSON 的密钥体系是正确使用它的前提。这里容易和 Git SSH 密钥混淆，它们是两套独立但可以协同的体系。
- 个人密钥对：这是开发者的身份凭证。每个团队成员生成自己的一对 EJSON 密钥（公钥+私钥）。公钥提交到项目仓库（或由管理员收集），私钥必须严格保密，存放在本地（如
~/.ejson/keys）。当你要加密一个字段给特定同事看时，就需要使用他的公钥。 - 项目公共密钥：通常，一个项目会有一个或多个“部署公钥”。这些公钥对应的私钥不掌握在任何个人手中，而是放在持续集成/持续部署（CI/CD）环境或生产服务器上。这样，CI 流水线或生产服务器就能自动解密配置文件，而无需介入人工。
- 与 Git SSH 密钥的关系：这是两个维度。Git SSH 密钥用于认证“你是谁”，从而决定你能否向代码仓库推送代码。EJSON 密钥用于加密“数据是什么”，决定你能否解密配置文件。一个负责仓库访问安全，一个负责仓库内容安全。在团队中，通常要求成员既配置好 SSH 密钥推送代码，也配置好 EJSON 密钥加解密配置。
3. 核心细节解析与实操要点
3.1 密钥生成：不仅仅是ejson keygen
安装 EJSON 工具（通常通过各语言包管理器，如gem install ejson或go install）后，第一步就是生成密钥。命令很简单：
ejson keygen这会在当前目录生成两个文件：public_key和private_key。但这里有几个至关重要的细节，直接关系到安全根基：
私钥的存储：绝对不要将
private_key提交到任何版本控制系统。生成后，你应该立即将其移动到安全的位置。EJSON 的默认查找路径是~/.ejson/keys目录。正确的操作是：mkdir -p ~/.ejson/keys # 假设生成的公钥是 abc123... mv private_key ~/.ejson/keys/abc123...这样，当你解密时，EJSON 会自动根据密文中的公钥标识，在
~/.ejson/keys目录下寻找对应的私钥。公钥的命名与分发：生成的
public_key文件内容就是一串字符串，如abc123...。这个字符串本身就是公钥。你需要将它安全地分发给项目管理员，或者按照团队约定，添加到项目的public_keys目录或某个配置清单中。公钥可以公开。密钥的强度与轮换：EJSON 默认使用 Curve25519 算法生成密钥对，这是目前公认安全且高效的椭圆曲线算法。对于长期项目，应建立密钥轮换机制。例如，每年或在有成员离职时，生成新的部署密钥对，并用新旧公钥重新加密所有敏感字段，然后安全地废弃旧私钥。
3.2 文件加密：理解ejson encrypt的幕后工作
加密的命令是ejson encrypt config.ejson。但在这之前，你需要准备一个config.ejson的明文文件。这个文件格式有讲究：
{ “_public_key”: “项目部署公钥或你的个人公钥”， “database_password”: “MySuperSecretPassword123!”， “api_key”: “sk_live_...” }当你执行加密命令时，EJSON 会：
- 读取
_public_key字段。 - 为每一个需要加密的字段（即所有非
_开头的顶级字段，除非配置了白名单）生成一个唯一的随机对称密钥。 - 用对称密钥加密该字段的值。
- 用
_public_key对应的公钥（实际上是用这个公钥加密上一步的对称密钥）。 - 将原字段替换为
secrets结构，并将明文字段名作为key的一部分进行加密存储。
实操心得：一个常见的误区是，认为
_public_key填谁的公钥，就用谁的私钥解密。没错，但更关键的是，这个公钥决定了谁“有能力”解密。在团队中，我们通常在这里填写“项目部署公钥”，这样服务器和所有持有部署私钥备份的运维人员都能解密。如果这里填了你的个人公钥，那只有你能解密，别人和服务器都解不了，会导致部署失败。所以，除非是纯个人使用的文件，否则这里通常指向共享的部署公钥。
3.3 多接收者加密：团队协作的关键
EJSON 的强大之处在于支持用多个公钥加密同一份数据。假设你有 Alice 和 Bob 两个队友，并且项目部署公钥是deploy_key。你希望加密一个 API 密钥，让 Alice、Bob 和部署服务器都能解密。
你不需要加密三次。EJSON 允许你在_public_key数组中指定多个公钥：
{ “_public_key”: [“alices_public_key”， “bobs_public_key”， “deploy_public_key”]， “stripe_api_key”: “sk_live_...” }执行ejson encrypt后，在生成的secrets._encrypted数组中，对于stripe_api_key这个字段，你会看到三个加密对象，分别使用了 Alice、Bob 和部署的公钥加密了同一个对称密钥。这样，三者中任何一方用自己的私钥，都能解密出对称密钥，进而解密出原始的 API 密钥。
这个功能完美解决了团队中权限分层的问题：开发者用个人密钥解密开发配置，部署系统用部署密钥解密生产配置。
4. 实操过程与核心环节实现
4.1 完整工作流：从零开始保护一个项目配置
让我们模拟一个真实项目“AwesomeSaaS”的配置保护流程。
步骤一：生成并托管项目部署密钥项目技术负责人（或运维）在安全的离线环境中生成部署密钥对。
ejson keygen # 生成 public_key: 789def...， private_key: (保密)将公钥789def...写入项目根目录的deploy.pub文件，并提交到 Git。私钥通过安全的渠道（如硬件加密 U 盘、密钥管理服务如 HashiCorp Vault、AWS KMS）分发给 CI/CD 系统和生产服务器管理员，并存入服务器的~/.ejson/keys/目录。
步骤二：开发者准备明文配置开发者在项目根目录创建config.ejson：
{ “_public_key”: “789def...”， “environment”: “development”， “log_level”: “debug”， “database”: { “host”: “localhost”， “name”: “awesome_saas_dev”， “password”: “dev_db_pass123” // 这是要加密的敏感信息 }， “stripe_secret_key”: “sk_test_...” // 这也是要加密的敏感信息 }注意，environment和log_level我们打算保持明文，database.password和stripe_secret_key需要加密。
步骤三：加密配置文件运行加密命令：
ejson encrypt config.ejson命令执行后，会生成config.ejson文件（原文件会被覆盖，建议用版本控制工具查看差异）。内容变为：
{ “_public_key”: “789def...”， “environment”: “development”， “log_level”: “debug”， “database”: { “host”: “localhost”， “name”: “awesome_saas_dev” }， “secrets”: { “_encrypted”: [ { “_public_key”: “789def...”， “encrypted_value”: “EJ[1:CiphertextForDBPass...]”， “encrypted_key”: “EJ[1:EncryptedSymmetricKey...]” }， { “_public_key”: “789def...”， “encrypted_value”: “EJ[1:CiphertextForStripeKey...]”， “encrypted_key”: “EJ[1:EncryptedSymmetricKey...]” } ] } }可以看到，敏感字段被移到了secrets部分，database对象里只剩下了非敏感的host和name。现在，这个config.ejson文件可以安全地提交到 Git 仓库。
步骤四：在应用中使用解密后的配置在本地开发时，开发者需要解密。首先确保你的私钥（如果是项目部署密钥，通常开发者不持有；如果是个人密钥加密的字段，则需要）在~/.ejson/keys/目录下。然后，在应用启动脚本中，通常这样集成：
# 在启动应用前解密，生成一个临时明文文件 ejson decrypt config.ejson --output=config_decrypted.json # 然后让应用读取 config_decrypted.json # 或者，更优雅的方式是使用库直接解密（如Ruby的 `EJSON::RAILS` 插件）在生产环境，CI/CD 流水线或启动脚本会做同样的事，使用预先配置好的部署私钥进行解密。
4.2 与现有配置管理工具的集成
EJSON 并非要取代 Ansible、Chef、Kubernetes Secrets 等工具，而是可以与它们互补。
与 Kubernetes 集成：你可以将解密后的整个 JSON 内容，或者单个密钥值对，创建为 Kubernetes Secret。也可以在 CI/CD 中使用
ejson decrypt命令，将解密后的值通过管道传递给kubectl create secret。# 示例：将解密后的某个值存入 K8s Secret DATABASE_PASS=$(ejson decrypt config.ejson | jq -r ‘.database.password’) kubectl create secret generic app-secrets --from-literal=database-password=“$DATABASE_PASS”与环境变量集成：很多应用从环境变量读取配置。你可以写一个简单的包装脚本，先用 EJSON 解密，然后将解密出的键值对导出为环境变量。
# decrypt_and_export.sh eval “$(ejson decrypt config.ejson | jq -r ‘to_entries | map(”export \(.key)=\(.value | tostring)“) | .[]’)” # 然后在此脚本环境中启动你的应用
5. 常见问题与排查技巧实录
在实际落地 EJSON 的几年里，我遇到了不少坑。下面这个表格总结了一些典型问题及解决方案，希望能帮你节省大量排查时间。
| 问题现象 | 可能原因 | 排查步骤与解决方案 |
|---|---|---|
运行ejson decrypt时报错No private key found | 1. 私钥文件不在~/.ejson/keys/目录。2. 私钥文件名不正确。 3. 私钥文件权限过于开放。 | 1.检查路径：ls -la ~/.ejson/keys/，确认存在以公钥命名的文件。2.检查文件名：私钥文件名必须是完整的公钥字符串。用 cat config.ejson查看_public_key值，确保文件名与之完全一致。3.检查权限： chmod 600 ~/.ejson/keys/确保目录权限为 700，密钥文件权限为 600。 |
解密成功，但得到的值是null或错误 | 1. 明文字段名在加密后发生了改变或重复。 2. 解密后字段的访问路径不对。 | 1.检查加密过程：确保加密前的.ejson文件格式正确，没有嵌套在多层对象里导致 EJSON 误判。建议加密前先用ejson preview命令查看哪些字段会被加密。2.使用 jq 工具精确提取：`ejson decrypt config.ejson |
| 在 CI/CD 中解密失败 | 1. CI 环境没有安装ejson命令行工具。2. 部署私钥没有正确设置到 CI 的环境变量或密钥管理中。 3. 私钥内容格式错误（如多了换行符）。 | 1.在 CI 脚本中安装工具：如apt-get install ejson或gem install ejson。2.安全注入私钥：将私钥内容存入 CI 系统的Secret Variable或Vault，在运行脚本时写入临时文件： echo “$EJSON_PRIVATE_KEY” > /tmp/priv && EJSON_KEYDIR=/tmp ejson decrypt ...。3.检查私钥格式：私钥应该是单行字符串。确保从保管处复制时没有多余空格或换行。 |
| 加密文件后，Git 差异显示整个文件都是变更 | 这是正常现象。因为 EJSON 加密后，敏感字段被替换为完全随机的密文和加密密钥，即使原明文只改了一个字符，密文也会完全不同。 | 使用.gitattributes优化：对.ejson文件设置diff=ejson，并配置 Git 使用ejson diff工具。这样git diff时会显示明文的差异，而不是混乱的密文。配置方法需参考 EJSON 文档安装相应的 diff 包装器。 |
| 团队成员无法解密我加密的文件 | 加密时使用的_public_key不是该团队成员的公钥，或者该成员的公钥没有被包含在加密所用的公钥列表中。 | 1.检查加密文件的公钥：确认文件中的_public_key字段包含所有需要解密的成员的公钥。2.使用多公钥加密：在明文中使用公钥数组，确保涵盖所有接收者。 3.团队规范：建立团队规范，约定使用统一的“项目公钥”进行加密，个人公钥仅用于加密临时共享的、非核心的敏感信息。 |
独家避坑技巧：
- 版本控制友好化：如前所述，一定要配置 Git 的 diff 包装器。否则每次加密后查看变更简直是噩梦，你无法知道到底改了哪个配置项。
- 密钥备份策略：项目部署私钥必须有安全的、离线备份。我曾经历过服务器硬盘损坏导致私钥丢失的事故。建议使用物理介质（如打印成二维码存放在保险柜）或专业的硬件安全模块（HSM）进行备份。
- 逐步迁移：对于已有大量明文配置的项目，不要试图一次性全部加密。应该逐个服务、逐个环境进行迁移。先加密最敏感的生产环境数据库密码和 API 密钥，确保 CI/CD 解密流程跑通，再逐步覆盖其他环境和配置项。
- 将 EJSON 解密集成到应用启动层：与其在外部脚本解密生成文件，不如在应用框架初始化时直接集成 EJSON 解密库（如果所用语言有的话）。这样配置读取逻辑更内聚，也避免了在磁盘上遗留临时明文文件的安全风险。例如在 Rails 中，可以使用
ejson-railsgem，它会在应用启动时自动解密config/secrets.ejson。