# 部署密钥 应用运行所需的密钥(数据库密码等)由 `@wishforge/runtime` 中的 `DeploymentSecretBroker` 在部署进程(Runner)中按固定版本从 Vault KV v2 读取并注入。编码执行器、验证器、浏览器与控制面 API 都拿不到它的 Vault 令牌或密钥值。它与模型 BYOK 使用的 Vault Transit 完全独立:`VAULT_ADDR`、`VAULT_TOKEN`、`VAULT_TRANSIT_KEY`、`WF_VAULT_KEY` 不会被当作它的凭据。 控制面只保存**版本引用**(`secretVersionRefs`)与运维审阅过的**策略摘要**(`deploymentSecretPolicyDigest`),不保存密钥内容。策略摘要计入环境与发布的绑定以及签名的 Runner 任务,审批后不能悄悄改变密钥映射。 ## 部署进程的配置 只在部署进程中配置,映射文件与令牌文件以只读方式挂载: ```text WF_DEPLOYMENT_MODE=production WF_DEPLOYMENT_SECRET_MAP_FILE=/run/wishforge/application-secrets.json WF_DEPLOYMENT_VAULT_ORIGIN=https://vault-deployment.example.internal WF_DEPLOYMENT_VAULT_TOKEN_FILE=/run/secrets/deployment-vault-read-token ``` Vault 令牌只授予该环境所需的 KV v2 读取路径,不需要写入、删除、Transit、策略管理或服务商账号权限;令牌丢失或过期时直接失败,不会从用户登录缓存中取凭据。 映射文件示例: ```json { "schemaVersion": 1, "bindings": [{ "tenantId": "tenant-a", "environmentId": "production-a", "ref": "database@version-7", "mount": "applications", "path": "tenant-a/production-a/database", "version": 7, "fields": { "DATABASE_URL": "url", "DATABASE_PASSWORD": "password" } }] } ``` - `fields` 把应用的环境变量名映射到 Vault 对象字段。发布只携带被授权的 `secretVersionRefs`,不携带 Vault 地址、路径、令牌、字段选择或明文。 - 引用名是运维定义的不透明名称;`version` 必须显式给出且为正数,broker 从不读取「最新版本」。 - 路径只接受安全的显式片段;穿越、编码斜杠与调用方给出的 URL 都被拒绝。重复映射、重复的环境变量名以及与公开应用配置冲突的键都被拒绝。`NODE_OPTIONS`、`LD_PRELOAD`、`PATH`、`WF_*`、`DOCKER_*`、`VAULT_*` 等进程控制变量不能通过这里注入。 - 生产中 Vault 地址必须是 HTTPS;只有开发或测试并设置 `WF_DEPLOYMENT_VAULT_ALLOW_LOOPBACK_HTTP=true` 时允许本机回环 HTTP。拒绝重定向。每次读取 10 秒超时,响应不超过 256 KiB;每个引用最多 64 个字段、总计 128 个字段;单个值不超过 16 KiB,总量不超过 128 KiB。版本不存在、已删除、已销毁、不是字符串或版本不符时都以通用错误失败。broker 核对返回的版本、删除时间与销毁标记,而不是把 HTTP 成功当作读到了所需版本(参见 [Vault KV v2 API](https://developer.hashicorp.com/vault/api-docs/secret/kv/kv-v2#read-secret-version))。 ## 公开计划与审批 运维可以在不读取 Vault 令牌、不连接 Vault 的情况下查看计划: ```bash node --import tsx scripts/deployment-secret-plan.ts tenant-a production-a reviewed-release-id database@version-7 ``` 输出包含策略摘要、被授权的引用与版本、应用变量名、确定性的不可变 Secret 名称与环境变量引用方式,不包含 Vault 路径、令牌或密钥值。策略摘要覆盖租户、环境、Vault 地址、挂载/路径/版本与字段映射(不包括令牌轮换)。运维通过环境的受保护配置写入摘要后,才请求或批准发布;引用名不变但路径或字段变化时,摘要随之变化,旧发布无法再读取。broker 在读取 Vault 之后会重新读取映射,并发的映射变化不会替换进行中的读取计划。 控制面接口:创建环境时只接受 `secretVersionRefs` 与 `deploymentSecretPolicyDigest`(有引用时必须提供 `sha256:` 摘要);已有环境通过 `PATCH /v1/environments/:id/deployment-secrets` 修改这两个字段(清空引用时摘要可以为 null)。该接口只允许人类 owner/admin,环境正在部署时拒绝修改,未知字段(包括密钥值)一律拒绝。控制面不读取 Vault 来计算或验证摘要,由部署进程在执行前与自己的公开计划比对。 ## 注入方式 - **Kubernetes**:使用固定的 context 与命名空间,通过 kubectl 的标准输入提交 `immutable: true` 的 Secret(base64 编码,但仍是私密内容),应用以 `valueFrom.secretKeyRef` 引用。复用已有 Secret 前核对命名空间、名称、不可变属性与类型、属主、租户/环境/发布/策略注解与数据;冲突时在应用候选版本之前停止。创建报错时先查询该 Secret 再判断是否已成功;从不强制替换或自动删除 Secret。 - **Compose**:保存的 Compose 文件中只有 `${WF_DEPLOY_APP_SECRET_n:?application-secret-required}` 占位符;真实值只放入执行 Docker Compose 的子进程环境,不写 `.env` 文件、不出现在命令行参数、不改变父进程环境。 - 其他适配器可以使用 `withValues(callback)`。回调不能返回或保留密钥,调用方不能记录其输入;密钥容器在 JSON 序列化和 Node inspect 时只输出脱敏摘要;回调中的异常被替换为通用错误;成功与失败后都会调用 `dispose()` 清零缓冲区(JavaScript 字符串的副本无法保证被擦除)。 - 公开的部署清单、`rendered` 字段、发布记录、证据与日志中都不含密钥内容。演练模式(dry-run)不读取 Vault、不执行命令。 注入意味着目标应用及其容器运行时能拿到这些值:Kubernetes Secret 存储与 Docker 容器配置可能持久化它们,需要静态加密、RBAC 与受保护的守护进程访问。「只在内存中处理」描述的是 WishForge broker 与控制面的边界。 ## 测试与验收边界 单元测试覆盖固定版本、映射漂移、审批摘要要求、作用域、重复键、保留的进程变量、响应大小限制、已删除版本、通用错误与公开/私密序列化;适配器测试覆盖安全的演练、Compose 子进程注入、异常脱敏与释放、Kubernetes 标准输入/命名空间/属主检查,以及读取前的策略漂移。可选的集成测试启动一个只实现 KV v2 读取响应的本机回环服务,核对请求头、版本与拒绝重定向。 这些测试不访问真实的 Vault、客户账号或部署目标。真实验收仍需要:单独开通的 Vault KV v2 挂载与读取策略和 TLS 信任、版本保留、不可变 Kubernetes Secret 的归属、Compose 子进程注入,以及使用保留的确切密钥版本回滚——旧版本缺失时回滚会被阻止,而不是改用更新的密钥。