指南
配置和密钥应存放在哪里
将普通配置与凭据分开,并根据访问需求为本地开发、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 和 .gitignore 并不能保证密钥安全;还要检查 Git 跟踪状态、CI 日志、备份和运行环境的密钥存储。
- 日志遮蔽不一定能隐藏转换后的值或所有命令输出。
- 怀疑凭据泄露时应撤销或轮换,而不能只删除文件。
指南
参考资料与规范
- The Twelve-Factor App — The Twelve-Factor App: Config
- Git Project — gitignore — Specifies intentionally untracked files to ignore
- Docker — Manage sensitive data securely with secrets
- Docker — Best practices for working with environment variables in Docker Compose
- GitHub — Using secrets in GitHub Actions
- GitHub — Secure use reference