配置管理

控制应用程序行为方式的一切 - 无需触及任何逻辑代码。

核心类比

角色
🧠 代码 大脑——逻辑
🧬 配置 DNA——行为规则
⚙️ 结果 相同的代码 + 不同的配置 = 完全不同的行为

如果 DNA 很混乱 → 即使是健康的大脑也会表现出不可预测的行为。

01 — 配置实际涵盖什么

配置经常被误认为只是“秘密”。事实上，它控制的更多：

应用程序设置

  • 端口号
  • 日志级别（debug / info / error）
  • 连接池大小
  • 超时持续时间

数据库配置

  • 主机和端口
  • 用户名/密码
  • 数据库名称
  • 连接字符串

外部服务

  • 电子邮件 API（例如 SendGrid）
  • 付款（例如 Stripe）
  • 身份验证（例如职员）
  • 云存储

功能标志

  • 仅为测试版用户启用功能
  • A/B 测试和逐步推出
  • 终止开关可立即禁用有缺陷的功能

业务规则

  • 最大订单限制
  • 会话到期时间
  • 折扣门槛
  • 速率限制

性能和日志记录

  • 缓存大小
  • 重试限制
  • 队列并发
  • 日志详细程度（开发中的调试，产品中的错误）

02 — 环境及其优先级

相同的代码库部署到所有三个 - 仅配置更改。

开发 — 优化速度和可见性

  • 调试日志打开
  • 本地数据库/沙箱API
  • 详细的错误消息
  • 启用热重载

Staging — 镜子生产，削减成本

  • 镜子生产设置
  • 基础设施占地面积更小
  • 用于质量保证和集成测试
  • 在上线前发现问题

生产 — 可靠性和安全性第一

  • 仅错误级别日志
  • 实时 API 和真实数据
  • 秘密定期轮换
  • 严格的访问控制

03 — 配置混乱：出了什么问题

当没有结构化的方式来管理配置时，事情就会很快崩溃。

❌ 硬编码值

值分散在多个文件中，更新期间很容易丢失，无法跨环境重用。

1
2
3
// Bad
const dbUrl = "mongodb://localhost";
const apiKey = "abc123";

❌ 安全漏洞

  • API 密钥推送到 GitHub
  • .env 文件意外提交
  • 在整个团队中公开的凭据
1
git add .env   # ← never do this

**现实世界的风险：**未经授权的 API 访问、数据泄露、滥用付费服务造成的经济损失。

❌ 跨环境的不一致

  • “它可以在我的机器上运行”综合症
  • 不同的开发人员使用不同的配置值
  • 生产环境变量缺失或错误

❌ 无启动验证

  • 应用程序在配置错误或丢失的情况下静默启动
  • 生产中出现不可预测的故障
  • 没有明确的事实来源，调试变成一场噩梦

04 — 存储策略

环境变量 （标准方法）

在运行时注入。完全保密源代码。

  • 工具：dotenv、.env 文件

配置文件 （用于结构化、记录的配置）

YAML 或 TOML 优于 JSON — 它们支持注释，这有助于团队文档编写。

  • 示例：config.yaml、settings.toml

云原生保管库 （适用于大规模、安全的环境）

集中、可审计、支持秘密轮换。

  • AWS 参数存储
  • HashiCorp 金库
  • Azure 密钥保管库

05 — 系统方法：最佳实践

01 — 集中配置

使用 .env 文件或配置模块作为单一事实来源。任何价值都不应该存在于两个地方。

1
2
3
DB_URL=mongodb://cluster.example.com
API_KEY=xyz123
LOG_LEVEL=info

02 — 切勿对秘密进行硬编码

1
2
3
4
5
// ❌ Bad
const apiKey = "12345";

// ✅ Good
const apiKey = process.env.API_KEY;

03 — 启动时验证 — 提前失败

如果缺少所需的配置值，则会在启动时大声崩溃。一个明显的启动错误比凌晨 2 点神秘的生产故障要好得多。

  • TypeScript：使用 Zod
  • Go：使用 Go 验证器

04 — 每个环境单独的配置

为每个环境维护不同的配置文件。切勿在开发和生产中共享相同的 .env 。
.env.development
.env.staging
.env.生产

05 — 最低权限和秘密轮换

只有“需要”秘密的人员和服务才可以访问它。定期旋转钥匙以限制任何泄漏的爆炸半径。

06 — 对结构进行版本控制，而不是秘密

提交 .env.example ，其中包含所有变量名称但空白值。任何新入职的人都知道要填写什么——而不会暴露真正的秘密。
.env.example → 提交此 ✓
.env → gitignore 这个 ✓

一行外卖

配置是控制你的应用程序的——相同的代码，不同的配置，完全不同的行为。如果没有纪律，它就会成为隐藏错误、安全漏洞和部署失败的第一大根源。