EpicEnv

一个史诗级的环境管理器，用于修复 git 协作者之间的本地环境变量管理问题。

它类似于 python 虚拟环境 + overlayfs，但针对的是环境变量。

所有环境均经过加密并通过 git 进行管理，并通过邀请系统提供基本权限。

目前仅针对 macOS 和 Linux，但看起来在 Windows 上也能工作？

• EpicEnv
  • 快速入门
    • 安装 EpicEnv
    • 初始化 EpicEnv
    • 叠加环境
    • 设置共享环境变量
    • 添加个人环境变量
    • 邀请协作者
    • 添加无头密钥
    • 加载环境
    • 在环境中运行命令
    • 停用环境
    • 提交 .epicenv 目录
    • 移除变量
  • 动机
  • 安全性
    • 加密
    • 防止个人变量被全局添加
    • 轮换密钥
  • 开发

快速入门

安装 EpicEnv

go install github.com/danthegoodman1/epicenv@latest

初始化 EpicEnv

在你的项目目录中，运行：

epicenv init GITHUB_USERNAME [-e ENVIRONMENT]

epicenv init danthegoodman1
# Creates the default "local" environment

epicenv init danthegoodman1 -e staging
# Creates a "staging" environment

获取你的公共 SSH 密钥时，你的 GitHub 用户名是必需的第一个参数。可以使用 -e 标志指定环境名称，如果未提供，则默认为 "local"。

你可以使用不同的环境将你的本地环境链接到不同的基础设施，例如 staging 和 production。

这将创建一个 .epicenv 目录，并将 .epicenv/*/personal 添加到你的 .gitignore。

Overlay Environments

Overlay 环境允许你创建继承自基础环境并覆盖特定变量的环境。这对于诸如拥有一个使用本地运行的 S3 兼容存储桶的 local 用于开发环境，同时拥有一个使用共享只读 S3 存储桶的 testing 环境用于受控测试的场景非常有用。

epicenv init -e testing --overlay local

叠加层可以任意深度地堆叠：

epicenv init -e agent-testing --overlay testing

这会创建一个链：local → testing → agent-testing

当你加载 agent-testing 时，变量通过堆叠每一层来解析：

1. 加载 local 密钥
2. 应用 testing 覆盖
3. 应用 agent-testing 覆盖

示例：

# Set base values in local
epicenv set DB_HOST localhost -e local
epicenv set S3_BUCKET s3://local-bucket -e local
epicenv set LOG_LEVEL debug -e local

# Override S3 in testing
epicenv set S3_BUCKET s3://test-bucket -e testing

# Override LOG_LEVEL in agent-testing
epicenv set LOG_LEVEL info -e agent-testing

# Loading agent-testing gives:
# DB_HOST=localhost (from local)
# S3_BUCKET=s3://test-bucket (from testing)
# LOG_LEVEL=info (from agent-testing)

行为：

• 覆盖层从其根环境继承加密密钥和用户
• 邀请用户加入覆盖层会将其添加到根环境（并带有警告）
• 个人密钥也会堆叠，每一层都可以添加或覆盖
• 从覆盖层中移除变量仅从该层移除。如果它存在于下层，它仍然可见

设置共享环境变量

你可以使用以下命令设置单个变量：

epicenv set KEY [VALUE] -e myenv

如果省略该值，则将通过隐藏的 stdin 提示输入该值：

epicenv set MYVAR -e myenv

MYVAR> 🔑

您还可以通过以下方式导入现有的 .env 文件：

epicenv import PATH

如果某行包含未加引号的尾部 #personal 注释，例如：

shared_thing="this val is shared"
personal_thing="this val is personal" #personal

然后它将被自动添加为个人变量。如果您有一个现有的 .env 文件需要导入，其中包含许多混合的共享和个人环境变量，这非常方便。EpicEnv 会在导入个人值时记录日志。

带引号的值可以包含字面量 #personal 而无需标记为个人，例如 shared_thing="foo #personal"。

epicenv envfile 为 EpicEnv 导入/导出以及支持单引号、双引号和反引号引号值的 dotenv 解析器（如 Node dotenv）输出带引号的 .env 值。它不打算被 shell 直接 source。个人值会带有尾部的 #personal 注释。包含所有引号分隔符类型的值使用 EpicEnv 兼容的回退转义，这可能无法通过每个第三方 dotenv 解析器精确往返。

导入将覆盖现有值，使用下面提到的个人标志冲突规则。

添加个人环境变量

对于类似数据库或 AWS 凭据的内容，您将希望使用（并强制使用）本地凭据。

epicenv set KEY VALUE -e myenv -p

这将把环境变量标记为个人变量，防止其被提交到 git。

如果将来有人加载环境而未设置自己的个人值，他们将在控制台中看到一个警告，提示他们缺少部分环境配置。

如果他们尝试将个人环境变量作为共享环境变量写入（省略 -p），EpicEnv 将识别此操作并假定其意图为个人变量，同时抛出警告（详见安全部分）。

如果他们尝试将共享环境变量作为个人变量写入，系统将拒绝该操作，并要求用户 rm 该变量以将其更改为个人变量。

邀请协作者

协作者通过其 GitHub 用户名进行邀请。 他们的账户必须至少添加 1 个 RSA 密钥，可在 github.com/{username}.keys 处查看。

epicenv invite danthegoodman1

你可以取消他们的邀请

epicenv uninvite danthegoodman1

这将重新加密所有值，并移除其访问权限。

注意，如果有人离开您的团队，您仍然需要轮换您的密钥！

添加无头密钥

您还可以使用 --path 选项直接从文件添加公钥（与 GitHub 用户无关）：

epicenv invite keyname --path /path/to/public_key.pub

这些“无头密钥”可以像 GitHub 用户一样进行管理：

epicenv uninvite keyname

这对于 CI/CD 系统、服务账户或其他需要访问环境变量的自动化系统非常有用。

加载环境变量

source .epicenv/myenv/activate

你的本地 shell 将解密并将变量加载到环境中！

你也可以运行此命令，在从 GitHub 拉取更改时更新本地环境。

使用环境变量运行命令

你可以在不将环境加载到 shell 的情况下，注入环境变量并运行命令：

epicenv run [--] [command] [args...]
epicenv -e staging run ./my-binary

使用 -- 将 epicenv 标志与命令的标志分隔开。

这适用于：

• 使用特定环境运行一次性命令
• 不希望修改 shell 环境的 CI/CD 流水线
• 需要以不同环境运行的脚本

示例：

# Run tests with local environment
epicenv run go test ./...

# Run a binary with staging environment
epicenv -e staging run ./my-binary

# Use in shell scripts (use -- when command has flags)
epicenv -e production run -- bash -c 'echo $DATABASE_URL'

# Pass flags to the subcommand
epicenv run -- ./my-binary --help

停用环境

您可以停用环境，这将使环境变量恢复到其先前状态（先前值或未设置）。

epic-deactivate

如果您已处于某个环境中，切换或刷新时会自动执行 deactivate。

提交 .epicenv 目录

git add .epicenv/*
git commit -m "add epicenv"

删除变量

您可以使用以下命令删除全局变量和个人变量：

epicenv rm KEY -e myenv

动机

当多人协作开发生产系统时，本地环境管理往往非常棘手。

像 kubeseal 这样的优秀管理系统可以将加密后的密钥直接保存在 git 中，但针对本地环境管理的类似工具却十分匮乏。

考虑到每位开发者都有（或至少应该有）自己特定的环境值，例如数据库凭据，团队成员很容易在保持本地运行项目所需的环境变量最新方面掉队。

这种情况会不断恶化，最终导致所有人都把 staging 部署当作自己的开发环境，而已经八个月没有人能在本地运行该服务了。

EpicEnv 旨在解决这一问题。

EpicEnv 将你的环境加密后存储在 git 中，并在你激活环境时进行解密。你可以共享某些变量，并在需要时替换开发者特定的（“个人”）变量（例如 DB 或 AWS 凭据）。

环境变量使用你 github.com/{username}.keys 中的 RSA 密钥进行加密，你可以“邀请”协作者加入该环境。

git 中的所有内容都是加密的，因此无需管理本地 .env 文件，也无需防止它们被提交。

这对于主播来说也非常有用，因为他们再也不必担心意外打开 .env 文件，从而向观众泄露生产环境的密钥 >.<

事实上，能够流式传输 Tangia 开发正是这一想法的起源，因为我（曾经）恰好在我的本地 .env 文件中解密了非常敏感的环境变量 😬

安全性

加密

变量使用 AES GCM 模式进行加密，对称密钥使用每位协作者的 RSA 密钥进行加密。

防止个人变量被全局添加

如果你尝试对标记为个人的变量执行 epicenv set，该 set 操作将更新个人变量，而不是将其添加到全局变量中，以防止个人值通过 git 泄露。

当发生这种情况时，会抛出警告。

要将个人变量共享，首先 rm 该个人变量，然后再次将其设置为共享。反之亦然，用于将共享变量设为个人。

轮换密钥

我们明确地不会在你取消协作者邀请时更改用于解密环境变量的对称密钥，以强制你在有人离开你的团队时轮换密钥!!!!!!!!!!

开发

需要：

git tag -a v#.#.# -m "some patch notes"
git push origin v#.#.#