Format Atlas

指南

配置和密钥应存放在哪里

将普通配置与凭据分开,并根据访问需求为本地开发、CI 和生产环境选择合适的存放方式。

应该选择哪种格式?

根据文件在工作流程中的用途选择格式。

  • 可共享的默认值 → 在仓库中提交不含密钥的示例
  • 开发者本地配置 → 工具支持时使用本地 .env,并确保不纳入 Git 跟踪
  • CI 凭据 → 使用 CI 提供方的密钥存储,并限制访问范围
  • 生产环境与容器 → 使用运行平台的密钥功能,只向需要的服务授权
  • 怀疑发生泄露 → 先撤销或轮换凭据;仅删除文件并不够

区分普通配置与密钥

服务 URL、功能开关等非敏感配置,与密码、API 密钥、私钥等凭据应区别处理。不要将真实凭据写入代码,也不要把含有真实值的文件提交到共享仓库。首先确认应用支持哪些配置方式。

不要将本地 .env 文件纳入 Git

如果工具支持,可将每位开发者的本地值保存在 .env 文件中,并共享只含变量名和占位值的 .env.example。将真实的 .env 加入 .gitignore,并确认它此前没有被 Git 跟踪。Git 忽略规则不是安全的密钥库,也不会清除已有提交历史中的值。

在 CI 中使用密钥存储并遵循最小权限原则

在 GitHub Actions 等 CI 系统中,通过提供方的密钥功能登记凭据,不要将其写入工作流文件。仅向需要的仓库、环境和任务开放访问,并只授予令牌必需的权限;同时避免在日志中输出凭据。日志自动遮蔽并不能保证所有转换后的值或命令输出都会被隐藏。

由生产运行环境提供密钥

生产环境应优先使用托管平台或云平台的密钥存储,并限制可读取各项值的部署和服务。Docker Compose 可以将密钥作为文件挂载给明确获准的服务;具体能力和限制因平台而异,请查阅实际运行环境的文档。在平台支持时,也可考虑使用 OIDC 等短期凭据,减少长期有效密钥的使用。

发现泄露后先撤销或轮换凭据

如果密钥可能出现在提交记录、CI 日志或聊天中,仅删除可见副本并不足够。应先撤销或轮换相关密钥或令牌,再检查访问日志和可能的使用情况。之后再妥善处理仓库历史和日志,并收紧访问控制以防再次发生。

候选格式

.env

适用于: 在支持 .env 文件的工具中加载本地配置值

不太适用于: 未经保护地共享或保存密钥

.gitignore

适用于: 防止尚未跟踪的本地 .env 文件被误加入仓库

不太适用于: 撤销密钥或从 Git 历史中删除已跟踪的值

导出前注意事项

  • 仅使用 .env 和 .gitignore 并不能保证密钥安全;还要检查 Git 跟踪状态、CI 日志、备份和运行环境的密钥存储。
  • 日志遮蔽不一定能隐藏转换后的值或所有命令输出。
  • 怀疑凭据泄露时应撤销或轮换,而不能只删除文件。

指南

参考资料与规范