使用 Secrets Manager

概览

本指南与 provider 无关。它假设你（或另一位管理员）已经配置了至少一个 Secret Provider Credential。请根据你想走的路径选择设置指南：

使用本指南来：

以下三个 CrewAI Platform 功能在使用 Secrets Manager 时相关：

每个功能都有两个动作级别：read 和 manage。授予 manage 会自动包含 read。

目标	`secret_providers`	`workload_identity_configs`	`environment_variables`
在环境变量中使用已有的 static credentials（不编辑 provider）	`read`	—	`manage`
创建、编辑或删除 static credentials	`manage`	—	`manage`
在 env vars 中使用已有的 Workload Identity-backed credentials	`read`	—	`manage`
创建、编辑或删除 Workload Identity configs（以及引用它们的 credentials）	`manage`	`manage`	`manage`

在 CrewAI Platform 中，进入 Settings → Roles。你可以在这里创建新角色、编辑每个角色的权限，以及把角色分配给组织中的现有成员。
点击 Create Role 创建新角色，或者打开一个现有角色来编辑其权限。
在角色权限编辑器中，按照上表切换相关功能：
- secret_providers：如果这个角色只需要使用已有凭据，选择 read；如果它还需要创建、编辑和删除凭据，则选择 manage。
- environment_variables：选择 manage，这样角色才能创建引用密钥的环境变量。
保存角色。
在同一个 Roles 页面（或组织 Members 列表）中，将该角色分配给相关成员。

一旦有了 provider 凭据，而且你的角色拥有正确权限，你就可以从任何环境变量中引用受管密钥。

在 CrewAI Platform 中，进入 Environment Variables，然后点击 Add Environment Variables。

填写表单：

Key - 环境变量的名称。必须以字母或下划线开头，并且只能包含字母、数字和下划线。通常采用大写，例如 OPENAI_API_KEY。
Value Source - 选择值的来源：
- Direct Value - 你直接输入的明文值。在不需要 provider 时使用。
- Use AWS default（或你对应 provider 的等价项） - 使用当前被标记为该 provider 默认值的凭据。
- A specific named credential - 按名称选择凭据。如果你对同一 provider 有多个凭据（例如 aws-prod 和 aws-staging），并想显式选择其中一个，请使用这个选项。
Secret Name - 你 provider 中密钥的名称。选定凭据后，此字段会提供自动补全：开始输入后，CrewAI Platform 会向你的 provider 查询匹配的密钥名称。

使用 secret-name#json_key 语法可以从结构化（JSON）密钥中提取单个字段。例如，若某个名为 database-credentials 的密钥值为 {"username": "...", "password": "..."}，则可以引用 database-credentials#password 只注入密码。

Note

Azure Key Vault 注释： Azure secret names 不能包含下划线。CrewAI Platform 在调用 Azure 时会自动把你 Secret Name 字段中的下划线转换为连字符（例如 db_password 会被发送为 db-password）。

点击 Create 保存变量。

要进行端到端验证：

Credential path	何时读取密钥	轮换需要做什么
Static credentials（AWS access keys、GCP service account JSON）	在 deploy time 读取 - 值会写入部署镜像	在轮换密钥后重新部署 automation
Workload Identity（OIDC federation，AWS 或 GCP）	在每次 automation kickoff 读取 - 值会从你的云中重新获取	不需要任何操作 - 轮换后的下一次 kickoff 会看到新值

如果部署或运行因密钥相关错误失败，请检查最常见原因：

症状	可能原因
`no credential found`	环境变量引用了某个 provider，但没有选择具体凭据，而且该 provider 类型也没有默认凭据。请在变量上显式选择凭据，或者在 Secret Provider Credentials 页面将某个凭据设为默认。
`secret not found`	Secret Name 中有拼写错误，或者该密钥在凭据指向的 provider 账户/区域中不存在。请重新检查这两处。
轮换后 automation 仍使用旧值（static-credentials path）	旧值已经写入部署的 container image。请重新部署 automation 以拾取轮换后的值。若要彻底避免这一点，请把 credential 切换到 Workload Identity 路径。
轮换后 automation 仍使用旧值（Workload Identity path）	确认自动化上的 env var 引用的是 WI-backed credential（而不是 static-keys credential）。使用 WI 时，轮换后的下一次 kickoff 应该看到新值。如果没有，请检查你的云中密钥是否真的已更新（例如 `aws secretsmanager get-secret-value`）。
`JSON key not found`	当使用 `secret-name#json_key` 时，底层密钥必须是包含该 key 的有效 JSON object。请直接在你的 provider 中读取该密钥进行验证。