background-agents密钥管理一文读懂Global、Repo、Environment三层作用域设计【免费下载链接】background-agentsAn open-source background agents coding system项目地址: https://gitcode.com/GitHub_Trending/ba/background-agentsbackground-agents是一款开源的后台智能体编码系统open-source background agents coding system让 AI Agent 在云端沙箱中自主完成编码任务。而本文聚焦它的安全基石——密钥管理Secrets Management通过Global全局、Repo仓库、Environment环境三层作用域设计把 API Key、数据库连接串等敏感凭据加密存储并在沙箱启动时按需注入既灵活又安全。 为什么需要三层作用域不同凭据的服务范围完全不同模型 API Key 是所有会话共用的数据库连接串往往只属于某个仓库而多仓库协作时凭据又需要按环境统一策展。单一的全局密钥池会导致密钥满天飞——项目 A 的 Stripe Key 被项目 B 的会话意外读到。background-agents 用三层作用域把凭据隔离到最小可见范围作用域存放位置Web 界面生效范围典型用途GlobalSettings → Secrets作用域选All Repositories (Global)所有会话ANTHROPIC_API_KEY、DEEPSEEK_API_KEY等通用模型 KeyRepoSettings → Secrets选中具体仓库从该仓库启动的会话DATABASE_URL、STRIPE_SECRET_KEY等项目专属凭据EnvironmentSettings → Environments → 打开环境 →Secrets标签从该环境启动的会话多仓库环境统一策展的凭据 核心原则Global 是底座Repo/Environment 是覆盖。层级越低的密钥覆盖面越窄越安全。 三个作用域分别怎么用Global所有会话的公共底座每个会话都先继承全部 Global 密钥再叠加自己的作用域。最常见的场景是模型 API Key——例如使用 Claude 模型时把ANTHROPIC_API_KEY存为 Global 密钥之后所有会话开箱即用无需重复配置。Repo仓库专属凭据数据库连接串、云服务 Access Key 等只应出现在特定项目里。将DATABASE_URL存到某仓库的 Repo 作用域只有从该仓库发起的会话才能看到它其他仓库的会话完全不可见。Environment多仓库环境的策展层当一次会话涉及多个仓库Environment 模式时环境内各成员仓库的 Repo 密钥不会流入会话——只有 Global 该 Environment 自己的密钥。这是刻意设计凭据按环境策展curated避免某个仓库的密钥悄悄扩散到所有包含它的环境。需要复用某仓库密钥时可以在 Environment 的Secrets标签页导入Import选择来源仓库、勾选 Key值在控制面侧直接复制密文原样搬运明文永不经过浏览器。注意导入是拷贝而非引用——之后轮换仓库里的值需要重新导入或手动更新环境密钥。 一次会话到底拿到哪些密钥这是三层设计的精华。一次会话的最终密钥 Global 会话目标session target的密钥合并规则如下单仓库会话Web 选择器、Slack、GitHub、Linear 发起Global 该仓库 Repo 密钥Environment 会话Global 该环境密钥成员仓库的 Repo 密钥不参与多仓库会话选择器选Multiple repositoriesGlobal 每个所选仓库的密钥键名冲突时主仓库列表中第一个获胜优先级Precedence同名键时Repo / Environment 密钥覆盖 Global 密钥。查看某仓库密钥时继承的 Global 键以只读形式展示并带 Global 徽章若你在 Repo 层覆盖了 Global 键Global 条目还会标注是哪个作用域覆盖的——冲突透明可查。合并发生在控制面内部源码见 user-env-resolver.ts先解密各作用域再由mergeSecretSources按优先级合并并审计最后才注入沙箱环境变量。✍️ 最快上手3 步添加密钥打开Settings → Secrets顶部下拉选择作用域Global 或某仓库环境密钥在 Settings → Environments 的对应标签点击Add secret输入键名自动转大写如my_api_key→MY_API_KEY和值点击Save完成 ✅小贴士支持粘贴.env文件整个KEYvalue文本块直接粘进输入框自动解析为多行适合批量导入更新值旧值以••••••••打码显示输入新值保存即更新留空保存则保持原值新密钥只对新启动的沙箱生效运行中的会话需重启才能拾取️ 安全机制值永远不留存于浏览器保障说明静态加密所有密钥三个作用域统一使用REPO_SECRETS_ENCRYPTION_KEY以AES-256-GCM加密后才写入数据库值永不回显保存后 API 只返回键名与时间戳值在 UI 中永久打码用时才解密仅在沙箱创建时于控制面解密作为环境变量注入随沙箱销毁而消失系统变量优先控制面注入的系统变量如SANDBOX_ID、PATH永远覆盖同名用户密钥导入走密文仓库 → 环境的密钥导入直接拷贝密文明文不经由控制面中转三层存储分别由 global-secrets.ts、repo-secrets与 environment-secrets.ts 实现共用 scoped-secrets.ts 中的校验与加解密管线。⚖️ 限制与保留键约束上限每作用域密钥数50键名长度256 字符格式[A-Za-z_][A-Za-z0-9_]*单个值大小16 KB每作用域值总大小64 KB单会话合并后总大小128 KB超出则启动失败并提示各作用域占用字节数另有一组保留键不可作为密钥使用SANDBOX_ID、CONTROL_PLANE_URL、GITHUB_APP_TOKEN、PATH等防止用户密钥覆盖系统变量定义见 secrets-validation.ts。 常见问题排查Model not found先检查所选模型供应商的鉴权模式API Key 模式下确认对应 KeyOPENAI_API_KEY/XAI_API_KEY/ANTHROPIC_API_KEY等已存到会话所在作用域。密钥没出现在沙箱里依次检查① 作用域是否存对了Global / Repo / Environment② 键名是否撞了保留键③ 是否重启了会话④从 Environment 发起的会话不读取成员仓库的 Repo 密钥——需把 Key 加入环境或在环境 Secrets 页导入。 延伸阅读官方密钥文档最权威、最详细docs/SECRETS.md环境存储与级联删除environments.ts数据库迁移0004_create_global_secrets.sql、0033_environments.sql密钥校验与合并上限secrets-validation.ts一句话总结Global 打底、Repo 管项目、Environment 管多仓库同名键低层覆盖高层——用最小可见范围管好每一把钥匙就是 background-agents 密钥管理的全部哲学。【免费下载链接】background-agentsAn open-source background agents coding system项目地址: https://gitcode.com/GitHub_Trending/ba/background-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考