wishforge-ide/docs/reference/deployment-secrets.md
eust-w b38db08eeb docs: align documentation with the code and write it in Chinese
Operations, development and architecture docs, the reference pages and the
component READMEs were rewritten against the code: every documented variable
exists, and the settings operators need (runtime image, Git service, listen
addresses, Runner targets, single-tenant gateway and provisioner bindings) are
documented.

Gaps the docs used to present as working are now stated as such: IDE
workspaces do not clone the project yet (FR-H2), and in Kubernetes mode
dependency installs and image builds have no network path until an egress
proxy and builder access exist. The Kubernetes README describes what the
provisioner creates, what the Runner needs in a target namespace, and the
cluster acceptance that is still outstanding.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 18:01:39 +08:00

68 lines
6.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 部署密钥
应用运行所需的密钥(数据库密码等)由 `@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 子进程注入,以及使用保留的确切密钥版本回滚——旧版本缺失时回滚会被阻止,而不是改用更新的密钥。