macalbert/envilder

# 🗝️ Envilder ☁️

一个模型。你的机密信息。所有运行时。
只需定义一次机密映射。即可从 AWS SSM 或 Azure Key Vault 一致地解析它们。

[](https://www.npmjs.com/package/envilder) [](https://npmcharts.com/compare/envilder) [](https://github.com/macalbert/envilder/actions/workflows/tests.yml) [](https://macalbert.github.io/envilder/) [](./LICENSE) ## 为什么选择 Envilder？ 你的新开发人员加入了团队。他们需要环境变量才能在本地运行应用程序。 接下来会发生什么？有人通过 Slack 发送了 API 密钥。还有人翻出了一个 包含过时凭证的 wiki 页面。四十五分钟后，他们的 `.env` 文件“大概是正确的”。 **Envilder 用一条命令解决了这个问题。** 你创建一个 JSON 映射文件，将变量名映射到云端机密路径。Envilder 会从 AWS SSM 或 Azure Key Vault 解析它们。相同的映射文件可以用于本地开发 (CLI)、 CI/CD (GitHub Action) 和应用程序启动 (运行时 SDK)。 ``` envilder --map=param-map.json --envfile=.env ``` 没有 SaaS 中间商。没有供应商锁定。机密信息保留在你的云中。 ## 痛点 - **入职流程耗时数小时，而非几秒。** 每个新开发人员都需要有人解释哪些 机密信息放在哪里。密钥通过 Slack 共享、从 wiki 粘贴，或者从同事的 机器上复制。这不仅缓慢、容易出错，而且不安全。 - **每个环境都有自己的工作流。** 本地开发读取 `.env` 文件。CI/CD 使用 Vault 集成。生产环境有自己的方法。同一个应用程序，却有三种不同的机密工作流。 - **没有唯一的真实数据源。** 没有版本化的契约，开发/预发布/生产环境的配置 就会产生偏差。部署中断。没人知道哪个配置才是正确的。 ## Envilder 如何解决它 - 📋 **一个映射文件搞定一切。** 一个单一的 `param-map.json` 文件定义了你的应用程序 需要哪些机密。它经过 Git 版本控制、可通过 PR 审查，并且在所有环境中保持一致。 - ⚡ **适用于代码运行的所有地方。** 本地开发用 CLI，CI/CD 用 GitHub Action，应用程序 启动用运行时 SDK。相同的文件，相同的结果。 - 🛡️ **你的云，零基础设施。** 机密信息保存在 AWS SSM 或 Azure Key Vault 中。没有 SaaS 代理，没有额外的服务器，无需迁移数据。 ## ⚙️ 功能特性 | 功能 | 描述 | |---------|-------------| | 📋 **声明式映射** | 一个 JSON 文件定义所有机密。经过 Git 版本控制、可进行 PR 审查、支持差异对比 | | ☁️ **多云提供商** | AWS SSM + Azure Key Vault。无供应商锁定 | | 🔌 **运行时 SDK** | 在应用启动时将机密加载到内存中：[.NET](./src/sdks/dotnet/README.md)、[Python](./src/sdks/python/README.md)、[Node.js](./src/sdks/nodejs/README.md)。无需在磁盘上生成 `.env` 文件 | | ⚙️ **GitHub Action** | 在 CI/CD 中拉取机密。相同的映射，零手动配置 | | 🔄 **双向同步** | 将机密拉取到 `.env` 或将值推送回云端 | | 🧱 **零基础设施** | 无服务器、无代理、非 SaaS。使用你已有的云服务 | ## 🚀 快速入门 ### 🎥 观看演示 看看在不到 1 分钟的时间内自动化管理 .env 有多简单：  ### 🏁 开始使用（2 个步骤） **1. 创建映射文件** (`param-map.json`)： ``` { "DB_PASSWORD": "/my-app/db/password", "API_KEY": "/my-app/api-key" } ``` **2. 生成你的 `.env` 文件：** ``` npx envilder --map=param-map.json --envfile=.env ``` 就是这样。你的机密信息已从 AWS SSM 拉取并写入 `.env`。 将 `.env` 添加到 `.gitignore`。映射文件已被版本控制并可在 PR 中审查。 ### 💾 安装 ``` npm install -g envilder ``` ### 🤖 GitHub Action **AWS SSM (默认)：** ``` - name: Configure AWS Credentials uses: aws-actions/configure-aws-credentials@v5 with: role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }} aws-region: us-east-1 - name: Pull secrets from AWS SSM uses: macalbert/envilder/github-action@v0.8.0 with: map-file: param-map.json env-file: .env ``` **Azure Key Vault：** ``` - name: Azure Login uses: azure/login@v2 with: client-id: ${{ secrets.AZURE_CLIENT_ID }} tenant-id: ${{ secrets.AZURE_TENANT_ID }} subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }} - name: Pull secrets from Azure Key Vault uses: macalbert/envilder/github-action@v0.8.0 with: map-file: param-map.json env-file: .env provider: azure vault-url: ${{ secrets.AZURE_KEY_VAULT_URL }} ``` 📖 **[完整的 GitHub Action 文档](./github-action/README.md)** ### 📚 更多资源 - [📖 完整文档](https://envilder.com)：请访问 envilder.com 阅读完整指南 - [Push 命令指南](docs/push-command.md) - [Pull 命令指南](docs/pull-command.md) ## 🗺️ 映射文件格式 映射文件 (`param-map.json`) 是 Envilder 的核心。它是单一的模型，定义了 你的应用程序需要哪些机密以及它们在云提供商中的位置。CLI、GitHub Action 和运行时 SDK 都使用同一个文件。你可以选择性地包含一个 `$config` 部分， 来声明要使用的提供商和设置。 ### 基本格式 (AWS SSM，默认) 当没有 `$config` 时，Envilder 默认使用 AWS SSM Parameter Store： ``` { "API_KEY": "/myapp/prod/api-key", "DB_PASSWORD": "/myapp/prod/db-password", "SECRET_TOKEN": "/myapp/prod/secret-token" } ``` 值是 SSM 参数路径 (例如，`/myapp/prod/api-key`)。 ### 使用 `$config` (显式提供商) 添加一个 `$config` 键来声明提供商及其设置。Envilder 会读取 `$config` 进行配置， 并将其余所有的键用作机密映射： **带 profile 的 AWS SSM：** ``` { "$config": { "provider": "aws", "profile": "prod-account" }, "API_KEY": "/myapp/prod/api-key", "DB_PASSWORD": "/myapp/prod/db-password" } ``` **Azure Key Vault：** ``` { "$config": { "provider": "azure", "vaultUrl": "https://my-vault.vault.azure.net" }, "API_KEY": "myapp-prod-api-key", "DB_PASSWORD": "myapp-prod-db-password" } ``` ### `$config` 选项 | 键 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | `provider` | `"aws"` \| `"azure"` | `"aws"` | 要使用的云提供商 | | `vaultUrl` | `string` | - | Azure Key Vault URL (当 `provider` 为 `"azure"` 时必填) | | `profile` | `string` | - | 用于多账户设置的 AWS CLI 配置文件 (仅限 AWS) | ### 配置优先级 CLI 标志和 GitHub Action 输入始终会覆盖 `$config` 的值： ``` CLI flags / GHA inputs > $config in map file > defaults (AWS) ``` 这意味着你可以在 `$config` 中设置默认的提供商，并在每次调用时覆盖它： ``` # 使用 map 文件中的 $config envilder --map=param-map.json --envfile=.env # 覆盖 map 文件中的 provider 和 vault URL envilder --provider=azure --vault-url=https://other-vault.vault.azure.net --map=param-map.json --envfile=.env ``` ## 🧩 运行时 SDK 除了 CLI 和 GitHub Action 之外，Envilder 还提供了**运行时 SDK**，可以在启动时 将机密直接解析到应用程序的内存中。无需将 `.env` 文件写入磁盘，不会留下任何机密 痕迹。SDK 使用与 CLI 相同的映射文件格式。 ### .NET SDK 通过 NuGet 安装： ``` dotnet add package Envilder ``` 将机密加载到 `IConfiguration` 中，或将它们注入到进程环境中： ``` // Option A: integrate with IConfiguration var config = new ConfigurationBuilder() .AddEnvilder("secrets-map.json") .Build(); var dbPassword = config["DB_PASSWORD"]; // Option B: resolve + inject into environment Envilder.Load("secrets-map.json"); var dbPassword = Environment.GetEnvironmentVariable("DB_PASSWORD"); ``` 📖 **[完整的 .NET SDK 文档](./src/sdks/dotnet/README.md)** ### Python SDK 通过 uv (推荐) 或 pip 安装： ``` uv add envilder # 或 pip install envilder ``` 只需一行代码即可将机密加载到你的应用程序中： ``` from envilder import Envilder # 解析并注入到 os.environ Envilder.load('secrets-map.json') ``` 或者按环境进行路由，其中每个环境指向各自的映射文件： ``` from envilder import Envilder Envilder.load('production', { 'production': 'prod-secrets.json', 'development': 'dev-secrets.json', 'test': None, # no secrets loaded }) ``` 📖 **[完整的 Python SDK 文档](./src/sdks/python/README.md)** ### Node.js SDK 通过 npm 安装： ``` npm install @envilder/sdk ``` 只需一行代码即可将机密加载到你的应用程序中： ``` import { Envilder } from '@envilder/sdk'; // Resolve + inject into process.env const secrets = await Envilder.load('secrets-map.json'); ``` 或者使用流式构建器进行完全控制： ``` import { Envilder, SecretProviderType } from '@envilder/sdk'; const secrets = await Envilder.fromMapFile('secrets-map.json') .withProvider(SecretProviderType.Aws) .withProfile('prod-account') .resolve(); ``` 📖 **[完整的 Node.js SDK 文档](./src/sdks/nodejs/README.md)** ## 🛠️ 工作原理 ``` graph LR A["Mapping Model (param-map.json)"] --> B[Envilder]:::core B --> C["CLI → .env file"] B --> D["GitHub Action → CI/CD"] B --> E["SDK → app memory"] F["AWS SSM / Azure Key Vault"]:::cloud --> B classDef cloud fill:#ffcc66,color:#000000,stroke:#333,stroke-width:1.5px; classDef core fill:#1f3b57,color:#fff,stroke:#ccc,stroke-width:2px; ``` 1. **定义**：创建一个 `param-map.json`，将环境变量名映射到云机密路径 2. **解析**：Envilder 从你的云端 Vault 获取每个机密 3. **交付**：机密以 `.env` 文件 (CLI/GHA) 或内存 (SDK) 的形式送达 4. **推送**：将本地环境中的机密轮换或添加回云端 ## 🔍 Envilder 与其他替代方案对比 Envilder 不是机密管理器。它是一个**配置解析层**，可从你现有的云端 Vault 中 读取数据，并将机密交付到需要的地方 (`.env` 文件、CI/CD、应用程序内存)。 没有 SaaS 后端。没有额外的服务器。 | | Envilder | dotenvx | Infisical | |-|----------|---------|-----------| | **真实数据源** | 你的云端 (SSM / Key Vault) | Git 中加密的 `.env` | Infisical 后端 | | **声明式映射** | ✅ JSON 文件 | ❌ | ❌ | | **多云支持** | ✅ AWS + Azure | ❌ | ✅ | | **运行时 SDK** | ✅ .NET, Python, Node.js | ✅ Node.js | ✅ 6 种以上语言 | | **需要 SaaS** | ❌ | ❌ | 可选 | | **基础设施** | 无 | 无 | 需要服务器 | 有关详细的逐个工具比较，包括 [chamber](https://github.com/segmentio/chamber) 和 [aws-vault](https://github.com/99designs/aws-vault)， 请访问 [envilder.com](https://envilder.com)。 ## 🏁 接下来是什么 Envilder 已经通过 CLI、GitHub Action 以及用于 .NET、Python 和 Node.js 的运行时 SDK 覆盖了从开发到生产的完整生命周期。以下是即将推出的内容： | 状态 | 功能 | |--------|---------| | ✅ | Pull & Push：`.env` 与云端 Vault 之间的双向同步 | | ✅ | 多提供商：AWS SSM + Azure Key Vault | | ✅ | 用于 CI/CD 的 GitHub Action | | ✅ | .NET、Python 和 Node.js SDK | | 🚧 | Go 和 Java SDK | | 🚧 | GCP Secret Manager | | 🚧 | Exec 模式 (注入机密而无需写入磁盘) | 👉 **[包含优先级的完整路线图](./ROADMAP.md)** ## 🤝 贡献 欢迎所有形式的帮助！包括 PR、Issue 和想法。 - 🔧 使用我们的 [Pull Request 模板](.github/pull_request_template.md) - 🧪 尽可能添加测试 - 💬 欢迎反馈和讨论 - 🏗️ 查看我们的 [架构文档](./docs/architecture/README.md) - 🔒 查看我们的 [安全政策](./docs/SECURITY.md) ## 💜 赞助商

由 LocalStack 提供支持。

## 📜 许可证 MIT © [Marçal Albert](https://github.com/macalbert) 参见 [LICENSE](./LICENSE) | [更新日志](./docs/CHANGELOG.md) | [安全政策](./docs/SECURITY.md)

标签：AWS SSM, Azure Key Vault, GitHub Actions, MITM代理, Python, StruQ, 多人体追踪, 大语言模型安全, 密钥分发, 开发效率, 开源, 无SaaS, 无后门, 暗色界面, 本体建模, 本地开发, 机密管理, 环境变量, 网络可观测性, 网络调试, 自动化, 自动化攻击, 自动笔记, 逆向工具, 零供应商锁定