AACWorkflow Docs

秘密隔离（企业）

使用保险库引用而不是明文存储来管理代理环境变量和秘密，提高安全性。

秘密隔离是一个企业功能，将明文环境变量存储替换为安全引用到外部秘密管理器。与其在 AACWorkflow 中直接存储 API 密钥和凭证，不如仅存储引用（例如保险库路径），在任务启动时安全解析并注入代理流程环境。

为什么明文秘密危险

当秘密在数据库中存储为明文时：

  • 意外泄露 — 秘密可能出现在代理记录或日志中（如果模式匹配编辑失败）
  • 泄露半径 — 如果 AACWorkflow 数据库被攻击，所有秘密都暴露
  • 合规差距 — 许多标准（SOC 2、ISO 27001）要求秘密存储在应用数据库外
  • 无审计追踪 — 难以追踪谁访问了哪些秘密及何时

秘密引用如何工作

启用秘密引用后：

  1. 在工作区设置 → 秘密定义秘密引用
  2. 引用指向外部管理器中的秘密（Vault、AWS Secrets Manager、GCP Secret Manager 或服务器环境）
  3. 为引用分配范围 — 哪些代理可以访问、哪些存储库
  4. 代理启动任务时，AACWorkflow解析引用为实际值（仅内存）
  5. 值注入代理流程环境，永不存储在 AACWorkflow 数据库

支持的秘密管理器

AACWorkflow 支持四个秘密解析器后端：

env（默认，内置）

  • 工作原理 — 从服务器环境变量或文件读取秘密
  • 设置 — 设置 AACWORKFLOW_SECRET_PROVIDER=env（或使用默认值）
  • 用例 — 开发、小团队或没有外部秘密管理器
  • 安全性 — 取决于服务器环境隔离

vault（HashiCorp Vault）

  • 工作原理 — 引用指向 Vault KV v2 中的密钥，通过 Vault API 解析
  • 设置 — 配置 VAULT_ADDR 和代理认证（令牌或 Kubernetes 认证）
  • 用例 — 拥有现有 Vault 基础设施的企业
  • 安全性 — Vault 处理静止和传输加密；AACWorkflow 不存储明文

aws_sm（AWS Secrets Manager）

  • 工作原理 — 引用是 AWS Secrets Manager 中秘密的 ARN
  • 设置 — 为 AACWorkflow 配置 AWS 凭证（IAM 角色或密钥）
  • 用例 — AWS 原生部署
  • 安全性 — AWS 加密和审计秘密；每个秘密的细粒度 IAM 策略

gcp_sm（GCP Secret Manager）

  • 工作原理 — 引用是 GCP Secret Manager 中的资源名称
  • 设置 — 为 AACWorkflow 配置 GCP 服务账户凭证
  • 用例 — GCP 原生部署
  • 安全性 — GCP 加密和审计秘密；IAM 策略控制访问

设置秘密引用

步骤 1：配置秘密管理器

选择后端并在 AACWorkflow 服务器上设置相应的环境变量：

# 示例：HashiCorp Vault
export AACWORKFLOW_SECRET_PROVIDER=vault
export VAULT_ADDR=https://vault.example.com
export VAULT_TOKEN=s.xxxxxxxxxxxxxxxx  # 或使用认证方法

# 示例：AWS Secrets Manager
export AACWORKFLOW_SECRET_PROVIDER=aws_sm
export AWS_REGION=us-east-1
# （假设配置了 IAM 角色或 ~/.aws/credentials）

步骤 2：在外部管理器中创建秘密

对于 Vault：

vault kv put secret/aacworkflow/ws-<workspace-id>/OPENAI_API_KEY \
  value=sk-...

对于 AWS Secrets Manager：

aws secretsmanager create-secret \
  --name aacworkflow/ws-<workspace-id>/OPENAI_API_KEY \
  --secret-string sk-...

步骤 3：在 AACWorkflow 中注册引用

  1. 进入工作区设置 → 秘密
  2. 点击添加引用
  3. 填写：
    • 密钥 — 环境变量名称（例如 OPENAI_API_KEY）
    • 提供商 — 选择 vault、aws_sm、gcp_sm 或 env
    • 句柄 — 秘密管理器中的路径或 ARN
    • 范围（可选）— 限制为特定代理或存储库
  4. 点击保存

步骤 4：在代理环境中使用引用

设置代理的环境变量时，可以选择：

  • 字面值 — 存储为明文（仅小的、受信任的值）
  • 秘密引用 — 指向注册的秘密

例如，不是直接粘贴 OpenAI API 密钥，而是设置：

{
  "OPENAI_API_KEY": {"$secretRef": "OPENAI_API_KEY"}
}

任务启动时，AACWorkflow 解析此引用并将实际值注入代理环境。

将秘密限制到代理和存储库

可以限制哪些代理可以访问秘密：

  • 代理 — 代理 UUID 列表；只有这些代理可以解析引用
  • 存储库 — 存储库名称列表；秘密仅在代理处理这些存储库时可用

例如，含 scope.agents = [agent-1, agent-2] 的秘密在 agent-3 尝试使用时出错。

无范围 = 所有人可访问： 若留空范围，工作区中任何代理都可访问秘密。对敏感凭证明确指定范围。

秘密如何被保护

  1. 明文不存储 — 解析值仅在任务执行期间存在于内存
  2. 注入，不暴露 — 秘密通过环境变量传递到代理流程，不在提示或日志中呈现
  3. 保证编辑 — 所有解析值都添加到编辑注册表并从记录中强制删除（结构保证，不是试探法）
  4. 审计追踪 — 每次秘密解析都用上下文记录（代理、任务、时间戳）但不记录值本身
  5. 无需重新部署的轮换 — 在外部管理器轮换秘密在下次任务启动时生效；不需重启 AACWorkflow

向后兼容性

若已使用明文 custom_env 变量，它们继续工作。可以逐步迁移：

  • custom_env 中的现有明文值不受影响
  • 新值可以是引用
  • 在同一代理环境中混合明文和引用

启用新秘密引用时，代理可以立即开始使用它，无需代码更改。

最佳实践

  • 从高风险秘密开始 — API 密钥、数据库密码、令牌。首先迁移这些。
  • 使用范围 — 限制秘密仅到需要它们的代理和存储库
  • 定期轮换 — 每 90 天在外部管理器轮换一次秘密
  • 审计访问 — 在 AACWorkflow（设置 → 审计）和秘密管理器中审查审计日志
  • 使用提供商功能 — 在 Vault 或云提供商中启用加密、版本控制和审计日志

下一步

本页目录

为什么明文秘密危险秘密引用如何工作支持的秘密管理器env（默认，内置）vault（HashiCorp Vault）aws_sm（AWS Secrets Manager）gcp_sm（GCP Secret Manager）设置秘密引用步骤 1：配置秘密管理器步骤 2：在外部管理器中创建秘密步骤 3：在 AACWorkflow 中注册引用步骤 4：在代理环境中使用引用将秘密限制到代理和存储库秘密如何被保护向后兼容性最佳实践下一步