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 --outputconfig_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-literaldatabase-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 found1. 私钥文件不在~/.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文件设置diffejson并配置 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。