Backstage安全大师：配置覆盖与秘密信息管理的推荐指南

6 月 25, 2026

—

大家好！今天，我们将深入探讨一个核心主题，它能让您在运营Backstage时同时兼顾安全性和灵活性：“默认值覆盖（Overrides）和秘密信息（Secrets）管理的推荐方式”。🛡️

Backstage作为一个大型开发者门户，其配置文件中很可能包含敏感的API密钥或令牌。我们将为您整理出安全管理这些信息并根据不同环境应用不同配置的最佳方法！💡

🏗️ Backstage配置系统结构：app-config.yaml

Backstage的所有配置默认都在app-config.yaml文件中管理。然而，配置必须根据生产环境（Production）、预发布环境和本地开发环境而有所不同，最重要的是，需要安全保护的数据绝不能以明文形式存储在此文件中。 🚫

🌟 步骤1：按环境配置覆盖（Overrides）

Backstage支持一种分层配置（Hierarchical Configuration）方式，即通过叠加多个配置文件来使用。

✅ 按环境分离文件

推荐的做法是将基本配置放在app-config.yaml中，并将特定环境需要更改的内容写入单独的文件中。

app-config.yaml: 所有环境共享的基本配置 🏠
app-config.production.yaml: 仅在生产服务器上应用的覆盖配置 🚀
app-config.local.yaml: 开发者个人本地环境配置（建议Git忽略）💻

🔐 步骤2：秘密信息（Secrets）管理的标准做法：环境变量（Environment Variables）

在Backstage中管理密码、令牌、API密钥等敏感信息的最推荐方式是使用环境变量。

📝 在YAML文件中引用环境变量

不要直接在YAML文件中写入秘密信息，而是使用${ }语法来引用系统环境变量。

YAML

backend:
  auth:
    keys:
      - secret: ${BACKEND_SECRET} # 从环境变量读取 🔑
  database:
    connection:
      password: ${POSTGRES_PASSWORD}

💡 为什么选择环境变量？

安全性： 秘密信息不会暴露在源代码（Git）中。
灵活性： 即使部署相同的代码，也可以根据基础设施设置（Kubernetes Secrets、AWS Secrets Manager等）注入不同的值。
标准： 这是云原生环境中应用最广泛的安全合规方式。☁️

🛡️ 步骤3：运行时环境变量注入策略

环境变量的实际注入方式会影响安全级别。

1. 本地开发环境

可以使用.env文件或在shell中直接导出（export）。但是，.env文件必须添加到.gitignore中！⚠️

2. Kubernetes环境

创建Secrets资源，并将其映射为容器的环境变量来使用。

3. 云专用安全服务

使用AWS Secrets Manager、HashiCorp Vault、Azure Key Vault等专业工具，在部署管道（CI/CD）过程中动态注入环境变量，这是最强大的安全模型。🔒

🔍 步骤4：通过visibility设置保护前端

Backstage的部分配置会传递给前端（浏览器）。此时必须注意防止敏感信息泄露。

默认值： 大多数后端配置不会暴露给前端。
暴露控制： 只有明确标记为visibility: frontend的配置才能被浏览器读取。绝不能将此设置用于包含秘密信息的字段！🙅‍♂️

💡 总结：安全检查清单

禁止明文存储： 您是否避免了在app-config.yaml中直接写入API密钥？❌
利用环境变量： 您是否积极使用了${VAR_NAME}语法？✅
Git管理： 您是否已配置Git以忽略包含敏感信息的.local.yaml或.env文件？🛡️
最小权限： 您是否为每个环境变量分配了仅具有所需最小权限的令牌？🔑

🏁 结论：灵活安全的Backstage运营

Backstage推荐的配置管理核心原则是：“默认值通过文件共享，差异通过文件覆盖，秘密信息通过环境变量隐藏。”

建立好这个体系，即使服务规模扩大，您也可以稳定运营平台，无需担心安全事故。现在就检查您的app-config.yaml吧！🚀