功能 6：云密钥管理器集成 #

概述 #

Semaphore 目前将所有凭据存储在自己的数据库中。使用云平台的组织需要一种方式，在运行时直接从其云提供商的密钥管理服务中获取密钥，从而避免凭据重复并利用现有的轮换策略。此功能添加了与 AWS Secrets Manager 和 Azure Key Vault 的原生集成，作为 Enterprise 专属功能。

动机 #

• 企业团队已经在 AWS Secrets Manager 或 Azure Key Vault 中管理密钥，具有既定的轮换策略、访问控制和审计跟踪。将这些凭据复制到 Semaphore 的数据库中会创建第二个事实来源，可能会出现不同步的情况。
• 云提供商中的凭据轮换不会自动传播到 Semaphore——每次轮换后，需要有人手动更新每个受影响的密钥库条目。
• 受监管行业的合规和安全策略通常要求密钥永远不能离开云提供商的边界，也不能存储在第三方数据库中。
• Semaphore 内置的密钥库缺乏云密钥管理器开箱即用提供的访问控制、审计粒度和轮换自动化功能。

详细规范 #

Enterprise #

6.1 AWS Secrets Manager 集成 #

**目标：**在运行时从 AWS Secrets Manager 获取密钥，允许团队利用其现有的 AWS 密钥基础设施，而无需在 Semaphore 的数据库中复制凭据。

要求：

• 新的外部密钥后端类型：aws_secrets_manager。
• 认证方式：
  • IAM role（推荐用于 EC2/ECS/EKS 部署）——Semaphore 中不存储凭据。
  • Access key + secret key——存储在 Semaphore 的密钥库中（加密）。
  • Assumed role 配合 external ID——用于跨账户访问。
• 通过 ARN 或名称 + 可选版本/阶段引用密钥。
• 支持 JSON 结构的密钥，使用 field 选择器提取单个值（例如，{"username": "admin", "password": "..."} → 提取 password）。
• 支持自动密钥轮换——当 AWS 轮换密钥时，Semaphore 在下次任务运行时获取新值。
• 配置模型：

{
  "name": "Production AWS",
  "type": "aws_secrets_manager",
  "region": "us-east-1",
  "auth_method": "iam_role",
  "role_arn": "arn:aws:iam::123456789:role/semaphore-secrets",
  "external_id": "optional-external-id"
}

• 密钥库条目引用：

{
  "type": "external",
  "backend": "aws_secrets_manager",
  "secret_name": "production/db_password",
  "field": "password",
  "aws_config_id": 1
}

相关 issues：#2248

6.2 Azure Key Vault 集成 #

**目标：**在运行时从 Azure Key Vault 获取密钥，使使用 Azure 的组织能够集中管理和轮换凭据，而无需将其存储在 Semaphore 中。

要求：

• 新的外部密钥后端类型：azure_key_vault。
• 认证方式：
  • Managed identity（推荐用于 Azure VM/AKS 部署）——Semaphore 中不存储凭据。
  • Service principal 配合 client secret。
  • Service principal 配合证书。
• 通过 vault URL + 密钥名称 + 可选版本引用密钥。
• 支持从 vault 中检索密钥、密钥对和证书。
• 支持自动密钥轮换——当 Azure 轮换密钥时，Semaphore 在下次任务运行时获取新值。
• 配置模型：

{
  "name": "Production Azure",
  "type": "azure_key_vault",
  "vault_url": "https://my-vault.vault.azure.net",
  "auth_method": "managed_identity",
  "tenant_id": "...",
  "client_id": "..."
}

• 密钥库条目引用：

{
  "type": "external",
  "backend": "azure_key_vault",
  "secret_name": "db-password",
  "version": "latest",
  "azure_config_id": 1
}

相关 issues：#2248、#3170

6.3 统一外部密钥引用 #

**目标：**提供一种通用的密钥库条目类型，指向任何受支持的云提供商中的密钥。

要求：

• 新的密钥库类型：“External Reference”，存储密钥的指针（例如 AWS ARN、Azure vault URL + 密钥名称）而非密钥本身。
• 在任务执行时，Semaphore 通过调用云提供商的 API 解析引用并获取当前值。
• 解析后的值永远不会存储在 Semaphore 的数据库中——它仅在任务执行期间存在于内存中。
• 与云密钥管理器的连接在项目或系统级别配置（URL、认证方式、namespace/前缀）。
• 界面中以不同的徽标/图标和后端类型（AWS/Azure）显示外部引用。
• 保存时验证：Semaphore 尝试解析引用，如果密钥不可访问则显示警告（不阻止保存）。

6.4 密钥缓存 #

**目标：**通过在内存中缓存已解析的密钥来减少对云提供商的 API 调用。

要求：

• 可选的短期内存缓存（可配置 TTL，默认 5 分钟），用于减少对云提供商的 API 调用。
• 缓存仅存在于内存中，Semaphore 重启时失效。
• 缓存键由后端配置 ID + 密钥引用组成，因此多个模板使用的同一密钥在每个 TTL 窗口内只获取一次。
• 可以按后端配置禁用缓存（将 TTL 设为 0），用于必须始终获取最新值的密钥（例如在主动轮换期间）。
• 配置：后端配置中的 cache_ttl 字段（例如 "cache_ttl": "5m"）。

数据库架构变更 #

新增表：

• secret_backend ——存储云提供商配置（project_id、type、name、config JSON、created_at、updated_at）

修改的表：

• access_key ——添加列：
  • external_backend_id（integer，nullable，FK 指向 secret_backend）——关联到云提供商配置
  • external_reference（JSON，nullable）——存储密钥指针（ARN、vault URL、密钥名称、field、version）

API Endpoints #

• GET/POST /api/project/{id}/secret-backends ——列出/创建后端配置
• PUT/DELETE /api/project/{id}/secret-backends/{backend_id} ——更新/删除后端
• POST /api/project/{id}/secret-backends/{backend_id}/test ——测试连接和认证
• POST /api/project/{id}/secret-backends/{backend_id}/resolve ——解析密钥引用（用于验证）

配置 #

新增配置选项：

Key	Env Var	Default	描述
secret_cache_ttl	SEMAPHORE_SECRET_CACHE_TTL	5m	已解析外部密钥的默认内存缓存 TTL
secret_resolve_timeout	SEMAPHORE_SECRET_RESOLVE_TIMEOUT	10s	解析密钥时等待云提供商 API 响应的最大时间

You might also like