From 55bafd1c713261bbe783f905b4c11dded15780a4 Mon Sep 17 00:00:00 2001 From: Codex Date: Fri, 29 May 2026 09:19:06 +0800 Subject: [PATCH] docs: specify postgres and secret distribution --- AGENTS.md | 2 + docs/reference/architecture.md | 5 +- docs/reference/spec-v01-cicd.md | 2 + .../spec-v01-documentation-governance.md | 6 +- docs/reference/spec-v01-postgres.md | 79 ++++++++++++ .../reference/spec-v01-secret-distribution.md | 112 ++++++++++++++++++ docs/reference/spec-v01-services.md | 7 +- 7 files changed, 209 insertions(+), 4 deletions(-) create mode 100644 docs/reference/spec-v01-postgres.md create mode 100644 docs/reference/spec-v01-secret-distribution.md diff --git a/AGENTS.md b/AGENTS.md index 41c4f3f..3aa9ab8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -44,5 +44,7 @@ AgentRun 是面向 UniDesk 与 HWLAB 的共享 Agent 执行基础设施。本仓 - `docs/reference/spec-v01-documentation-governance.md`：v0.1 文档治理、唯一入口、spec 权威和过程材料承载规则。 - `docs/reference/spec-v01-services.md`：v0.1 服务总览、保留对象、deferred 对象和单服务规格索引。 - `docs/reference/spec-v01-cicd.md`：v0.1 分支、workspace、namespace、GitOps、registry、CI/CD 和发布验收规格。 +- `docs/reference/spec-v01-postgres.md`：v0.1 Postgres durable store、schema migration 和 SecretRef 规格。 +- `docs/reference/spec-v01-secret-distribution.md`：v0.1 Code Agent API Key 和运行时 Secret 分发规格。 - `docs/reference/architecture.md`：AgentRun 产品边界、服务架构、MVP 阶段、RESTful API 模型和数据模型。 - `docs/reference/cli.md`：按 `cli-spec` 固化的 CLI 与服务 API 约束。 diff --git a/docs/reference/architecture.md b/docs/reference/architecture.md index d343fb7..e6c4130 100644 --- a/docs/reference/architecture.md +++ b/docs/reference/architecture.md @@ -190,8 +190,9 @@ Event 是 append-only，并按 seq 分页： ## 数据模型方向 -第一版实现可以使用紧凑 schema，但不应把所有事实都隐藏在一个 JSON blob 中。稳定方向是： +`v0.1` 使用 Postgres 作为唯一 durable store；file、sqlite、JSONL 或 Pod 本地目录只能用于临时测试或日志，不作为运行面事实来源。第一版实现可以使用紧凑 schema，但不应把所有事实都隐藏在一个 JSON blob 中。稳定方向是： +- `agentrun_schema_migrations`：migration id、checksum 和 applied timestamp； - `agentrun_runs`：run identity、tenant/project/workspace/backend policy、status 和 timestamps； - `agentrun_commands`：command type、idempotency key、payload hash、state 和 ack timestamps； - `agentrun_events`：按 run 和 seq 索引的 append-only event records； @@ -199,6 +200,8 @@ Event 是 append-only，并按 seq 分页： - `agentrun_backends`：backend profile、capabilities、capacity 和 health； - `agentrun_leases`：当前 ownership 和 expiry。 +Postgres DSN、provider API Key 和未来 tenant credential 的分发边界见 [spec-v01-secret-distribution.md](spec-v01-secret-distribution.md)；source、GitOps、event、trace、日志和 CLI 输出都不得保存 Secret 明文。 + ## 部署方向 AgentRun 从 `v0.1` 开始按版本 lane 滚动，废弃 `dev/prod` 管理口径。`v0.1` 的固定 source workspace 是 `G14:/root/agentrun-v01`，固定 source branch 是 `v0.1`，固定运行目标是 G14 原生 k3s namespace `agentrun-v01`。后续 `v0.2`、`v0.3` 必须拥有自己的 branch、workspace、namespace、GitOps branch、runtime path 和发布验收。 diff --git a/docs/reference/spec-v01-cicd.md b/docs/reference/spec-v01-cicd.md index 9c1a559..fccd922 100644 --- a/docs/reference/spec-v01-cicd.md +++ b/docs/reference/spec-v01-cicd.md @@ -76,6 +76,7 @@ - service id、组件类型和是否参与 `v0.1` runtime。 - replica、resource request/limit、health path、ports、env key、ConfigMap/SecretRef 名称和 key。 - runtime namespace、ServiceAccount、RBAC intent、PVC intent、NetworkPolicy intent。 +- Postgres 和 Code Agent provider 的 SecretRef 名称、key 名称与 mount/env intent；Secret 值不在 source 或 GitOps 中出现。 - public/ingress intent 的声明占位；`v0.1` 默认不要求公网入口。 禁止写入 `deploy/deploy.json` 的内容： @@ -114,6 +115,7 @@ Tekton promotion 可以读取 `deploy/deploy.json` 来 render runtime desired st - `argocd/agentrun-v01` AppProject destination 只能包含 `agentrun-v01`。 - `argocd/agentrun-g14-v01` source 必须指向 `v0.1-gitops:deploy/gitops/g14/runtime-v01`，destination 必须是 `agentrun-v01`。 - `v0.1` Secret、ServiceAccount、RBAC、PVC、ConfigMap 和 runtime config 必须独立命名或 namespace scope；文档、issue、trace 和 report 只记录 SecretRef 名称与 key，不记录值。 +- `agentrun-mgr` 和 runner Job 只能通过 `spec-v01-secret-distribution.md` 定义的 SecretRef 注入 Postgres DSN 和 Code Agent API Key，不得从 `deploy/deploy.json`、artifact catalog 或 generated manifest 中读取明文。 - `agentrun_dev` 和 `agentrun_prod` 不得作为 `v0.1` namespace、Argo destination、Pipeline target 或验收目标。 ## 手动和热修边界 diff --git a/docs/reference/spec-v01-documentation-governance.md b/docs/reference/spec-v01-documentation-governance.md index 62e123d..30dee00 100644 --- a/docs/reference/spec-v01-documentation-governance.md +++ b/docs/reference/spec-v01-documentation-governance.md @@ -27,6 +27,8 @@ - `spec-v01-documentation-governance.md`：文档治理和旧口径迁移。 - `spec-v01-services.md`：服务总览、保留和 deferred 对象。 - `spec-v01-cicd.md`：版本 lane、GitOps、namespace、registry 和发布验收。 +- `spec-v01-postgres.md`：Postgres durable store、schema migration 和 DB SecretRef。 +- `spec-v01-secret-distribution.md`：Code Agent API Key、Postgres DSN 和运行时 Secret 分发。 - 未来新增单服务规格必须使用 `spec-v01-.md`，例如 `spec-v01-agentrun-mgr.md`、`spec-v01-agentrun-runner.md`。 - `v0.2` 或更高版本的规格不得写入 `spec-v01-*`；只能在对应版本 lane 中创建自己的 `spec-v02-*`、`spec-v03-*`。 - 每个可实现规格应包含“测试规格”小节；测试编号写在对应 spec 内，不创建或恢复根目录 `TEST.md`。 @@ -48,11 +50,13 @@ - Runtime namespace：`agentrun-v01`。 - 发布和验收规格：[spec-v01-cicd.md](spec-v01-cicd.md)。 - 服务总览规格：[spec-v01-services.md](spec-v01-services.md)。 +- Postgres durable store 规格：[spec-v01-postgres.md](spec-v01-postgres.md)。 +- Secret/API Key 分发规格：[spec-v01-secret-distribution.md](spec-v01-secret-distribution.md)。 ## 验收标准 - `AGENTS.md` 索引本文和其他 `spec-v01-*` 规格。 -- `docs/reference/` 中存在 `spec-v01-documentation-governance.md`、`spec-v01-services.md` 和 `spec-v01-cicd.md`。 +- `docs/reference/` 中存在 `spec-v01-documentation-governance.md`、`spec-v01-services.md`、`spec-v01-cicd.md`、`spec-v01-postgres.md` 和 `spec-v01-secret-distribution.md`。 - `AGENTS.md` 和 `docs/reference/` 不得把旧 `agentrun_dev`、`agentrun_prod`、`G14:/root/agentrun` 或 `/root/agentrun` 写成当前工作区、namespace、发布目标或验收目标；只允许在废弃说明和历史背景中提及。 - `docs/` 根目录不新增临时 Markdown 报告或 JSON dump。 - 仓库根目录不存在 `TEST.md`；测试场景维护在对应 `spec-v01-*.md` 的“测试规格”小节。 diff --git a/docs/reference/spec-v01-postgres.md b/docs/reference/spec-v01-postgres.md new file mode 100644 index 0000000..da0037b --- /dev/null +++ b/docs/reference/spec-v01-postgres.md @@ -0,0 +1,79 @@ +# v0.1 Postgres Durable Store 规格 + +本文定义 AgentRun `v0.1` 的持久化存储规格。`v0.1` 使用 Postgres 作为唯一 durable store；file、sqlite、JSONL 或 Pod 本地目录只能用于临时测试或日志，不作为运行面事实来源。 + +## 在系统中的职责划分 + +- 保存 `agentrun-mgr` 的 durable facts：runs、commands、events、runners、backends、leases 和 migration ledger。 +- 为 runner claim、command ack、event append、heartbeat 和 terminal status 提供事务边界。 +- 与 `agentrun-v01` namespace 绑定；不复用未来 `v0.2`、`v0.3` 或旧 dev/prod 数据库。 +- 不向公网开放，不允许普通 runner 直连写入不属于自己的 run facts。 + +## 固定命名 + +| 对象 | v0.1 规格 | +| --- | --- | +| Runtime namespace | `agentrun-v01` | +| StatefulSet | `agentrun-v01-postgres` | +| Service | `agentrun-v01-postgres` | +| Database | `agentrun_v01` | +| Runtime user | `agentrun_v01` | +| Data PVC | `agentrun-v01-postgres-data` | +| Postgres Secret | `agentrun-v01-postgres` | +| Manager DB Secret | `agentrun-v01-mgr-db` | +| Manager env key | `DATABASE_URL` | + +Secret 名称和 key 可以在实现时按 Kubernetes 命名限制微调，但必须保持 lane 独立，并在 `deploy/deploy.json` 中只记录 SecretRef 名称和 key，不记录值。 + +## 数据模型方向 + +`v0.1` 稳定表方向： + +- `agentrun_schema_migrations`：migration id、checksum、appliedAt。 +- `agentrun_runs`：run identity、tenant/project/workspace/backend policy、status 和 timestamps。 +- `agentrun_commands`：command type、idempotency key、payload hash、state 和 ack timestamps。 +- `agentrun_events`：按 run 和 seq 索引的 append-only event records。 +- `agentrun_runners`：registered runner identity、placement、heartbeat 和 capability snapshot。 +- `agentrun_backends`：backend profile、capabilities、capacity 和 health。 +- `agentrun_leases`：run ownership、expiry 和 stale recovery marker。 + +第一版实现可以把 backend-specific payload 存在 JSONB 字段中，但 run、command、event、runner、backend 和 lease 的主键、状态、时间戳和索引字段必须是一等列，不能把所有事实塞进一个不可查询 JSON blob。 + +## 访问边界 + +- `agentrun-mgr` 是数据库写入 authority；业务客户端通过 manager REST API 访问 durable facts。 +- runner 不直接读取或写入 Postgres，除非后续 spec 明确引入受限 DB role；`v0.1` 默认 runner 通过 manager API claim/report。 +- CLI 不直接连 Postgres；CLI 调用 manager REST API。 +- Postgres DSN 只通过 [spec-v01-secret-distribution.md](spec-v01-secret-distribution.md) 定义的 Kubernetes SecretRef 注入 `agentrun-mgr`。 +- 日志、event、CLI 输出和 health 只能展示数据库 readiness、schema version、SecretRef 名称或 redacted DSN，不得打印 DSN 明文。 + +## Migration 规则 + +- migration 必须由 source branch 的人写 migration 文件或等价 migration module 定义。 +- CI 可以校验 migration 顺序、checksum 和向前兼容，但不得把 live DB dump 写回 source。 +- 启动时 `agentrun-mgr` 可以执行幂等 migration 或在 migration 缺失时 fail fast；不得静默以空 schema 继续服务。 +- schema migration 记录必须写入 `agentrun_schema_migrations`。 + +## 测试规格 + +### T1 Postgres readiness + +阅读本文和 [spec-v01-secret-distribution.md](spec-v01-secret-distribution.md)，然后在 `agentrun-v01` namespace 中检查 StatefulSet、Service、PVC 和 SecretRef 名称存在；不得输出 Secret 值。 + +### T2 Manager DB health + +阅读本文，然后访问 `agentrun-mgr` health/readiness，确认返回 Postgres reachable、schema migration ready、database adapter 为 Postgres，并且 DSN 被 redacted。 + +### T3 Durable facts round-trip + +阅读本文和 [spec-v01-services.md](spec-v01-services.md)，然后创建 run、command、event 和 terminal status，重启 `agentrun-mgr` 后确认 facts 仍可通过 manager API 查询。 + +## 规格的实现情况 + +| 规格项 | 状态 | 说明 | +| --- | --- | --- | +| Postgres durable store 规格 | 已定义 | 本文为 v0.1 存储权威。 | +| StatefulSet/Service/PVC | 未实现 | 需要后续 GitOps lane 初始化。 | +| migration ledger | 未实现 | 需要后续代码和 schema migration。 | +| manager Postgres adapter | 未实现 | 需要后续 `agentrun-mgr` 实现。 | +| file/sqlite durable store | 不采用 | 只可用于临时本地测试，不作为 v0.1 runtime truth。 | diff --git a/docs/reference/spec-v01-secret-distribution.md b/docs/reference/spec-v01-secret-distribution.md new file mode 100644 index 0000000..7a76979 --- /dev/null +++ b/docs/reference/spec-v01-secret-distribution.md @@ -0,0 +1,112 @@ +# v0.1 Secret 与 API Key 分发规格 + +本文定义 AgentRun `v0.1` 的 Secret 和 Code Agent API Key 分发边界。Code Agent 一定需要上游模型 API Key，但这些值不得进入 Git source、GitOps branch、artifact catalog、event、trace、日志或 CLI 输出。 + +## 设计目标 + +- API Key 只通过 Kubernetes SecretRef 分发到需要它的 manager、runner 或 backend adapter。 +- `deploy/deploy.json` 只记录 SecretRef 名称、key 名称、mount/env intent 和 secret scope，不记录 Secret 值。 +- `v0.1-gitops` 的 rendered manifests 只能引用 Secret 名称和 key，不包含 Secret data。 +- `agentrun-mgr` 保存 run 的 `executionPolicy.secretScope`，但保存的是 credential source reference，不是 credential value。 +- runner 和 backend adapter 只能消费 manager 已授权的 secret scope，不能枚举 namespace 内所有 Secret。 + +## Secret 分类 + +| Secret 类别 | 用途 | 默认消费者 | v0.1 规则 | +| --- | --- | --- | --- | +| Postgres DSN | manager 连接 durable store | `agentrun-mgr` | 只通过 `agentrun-v01-mgr-db/DATABASE_URL` 注入。 | +| Codex/OpenAI-compatible API Key | 真实 Code Agent backend 调上游模型 | runner 或 backend adapter | 只通过 provider profile SecretRef 注入，不写入 run payload。 | +| Git SSH deploy key | Tekton checkout source/GitOps promotion，Argo 读取 GitOps branch | Tekton、Argo CD | 只存在于 `agentrun-ci` 或 `argocd` Secret；不进入 runtime Pod。 | +| Registry credential | push/pull private registry | Tekton、runtime imagePullSecret | 只作为 ServiceAccount/imagePullSecret 引用。 | +| Future tenant credential | tenant 专属工具或外部服务 | runner/backend adapter | 必须先定义 SecretRef 和 secret scope，再允许 run 引用。 | + +## 固定命名建议 + +| 对象 | v0.1 建议 | +| --- | --- | +| Manager DB Secret | `agentrun-v01-mgr-db` key `DATABASE_URL` | +| Provider Secret | `agentrun-v01-provider-codex` key `API_KEY` | +| Provider config Secret | `agentrun-v01-provider-codex` key `BASE_URL` 或 ConfigMap 中非敏感 base URL | +| Tekton Git SSH Secret | `agentrun-ci/agentrun-git-ssh` | +| Argo Git SSH Secret | `argocd/agentrun-git-ssh` | +| Runtime ServiceAccount | `agentrun-v01-mgr`、`agentrun-v01-runner` | + +命名可以在实现时因集群约束调整，但必须满足 lane 独立、用途单一、最小 RBAC 和不跨 `v0.1`/`v0.2` 复用的原则。 + +## Run secretScope 合同 + +Run 的 `executionPolicy.secretScope` 只能包含引用，不包含值。示例形态： + +```json +{ + "providerCredentials": [ + { + "profile": "codex", + "secretRef": { + "namespace": "agentrun-v01", + "name": "agentrun-v01-provider-codex", + "key": "API_KEY" + } + } + ], + "allowCredentialEcho": false +} +``` + +规则： + +- `allowCredentialEcho` 必须固定为 `false`。 +- `secretRef.namespace` 默认只能是 run 所在 lane namespace 或明确批准的 platform namespace。 +- manager 可以保存 `secretRef`，但不得读取 Secret 值后存库。 +- runner/backend adapter 获得 Secret 的方式必须来自 Kubernetes env/file projection 或受限 Secret API 读取；不得通过 run payload、event、CLI 参数或日志传递。 +- SecretRef 不存在或 RBAC 不允许时，run 必须失败为结构化 `failureKind=secret-unavailable` 或等价错误，不得降级成无凭证重试风暴。 + +## 分发路径 + +`v0.1` 默认路径： + +```text +deploy/deploy.json + -> declares SecretRef names and mount/env intent only +Tekton promotion + -> renders SecretRef references into v0.1-gitops manifests +Argo CD + -> syncs workload references to agentrun-v01 +Kubernetes Secret + -> created out-of-band by operator or approved secret-management flow +runner/backend Pod + -> receives API Key via env/file projection +``` + +Secret 创建和轮换不由 source branch 自动生成；source branch 只声明需要哪个 SecretRef。后续如果接入 External Secrets、Vault、SealedSecrets 或 SOPS，必须新增或更新本 spec，明确 controller、source of truth、rotation 和 redaction 规则。 + +## 日志与事件 Redaction + +- event、trace、日志、CLI 输出、health 和 diagnostics 不得打印 Secret 值。 +- `Authorization`、`api_key`、`token`、`password`、URL credential、DSN password 必须 redacted。 +- 可以打印 SecretRef 名称、key 名称、credential source、是否存在、是否被挂载、是否通过 readiness 检查。 +- provider auth 失败只能报告 failure kind、HTTP status 分类和 request id；不得打印请求 header 或 body 中的凭据。 + +## 测试规格 + +### T1 SecretRef render + +阅读本文和 [spec-v01-cicd.md](spec-v01-cicd.md)，然后检查 `deploy/deploy.json` 只包含 SecretRef 名称/key 和 mount/env intent；rendered GitOps manifest 也只包含 SecretRef，不包含 Secret data。 + +### T2 Runner credential projection + +阅读本文，然后启动一个最小 backend runner dry-run，确认 Pod env/file projection 能看到 provider credential，但 event、日志和 CLI 输出只显示 redacted credential source。 + +### T3 Missing secret failure + +阅读本文，然后用一个不存在的 provider SecretRef 创建 run，确认 run 失败为结构化 `secret-unavailable`，不会打印 Secret 值，也不会无限重试。 + +## 规格的实现情况 + +| 规格项 | 状态 | 说明 | +| --- | --- | --- | +| Secret 分发规格 | 已定义 | 本文为 v0.1 API Key 分发权威。 | +| Kubernetes SecretRef 注入 | 未实现 | 需要后续 GitOps/runtime 实现。 | +| provider API Key projection | 未实现 | 需要后续 runner/backend adapter 实现。 | +| redaction 最小规则 | 已定义 | 需要后续代码实现和测试。 | +| 外部 secret manager | 未采用 | 如需 Vault/ExternalSecrets/SOPS，后续单独更新规格。 | diff --git a/docs/reference/spec-v01-services.md b/docs/reference/spec-v01-services.md index 6e07a2e..7e71448 100644 --- a/docs/reference/spec-v01-services.md +++ b/docs/reference/spec-v01-services.md @@ -40,7 +40,8 @@ Runner inbound API 只允许本地或私有诊断，不作为业务客户端入 | Backend adapter | 执行适配层 | 保留，P0 | 统一 backend capability、event normalization、error mapping 和 credential boundary。 | `spec-v01-backend-adapter.md` | | First real backend | 具体 Agent backend | 保留，P0 | `v0.1` 必须至少证明一个真实 Agent backend；默认候选是 Codex。 | `spec-v01-backend-codex.md` | | AgentRun CLI | CLI/Job 工具 | 保留，P0 | JSON 输出、短返回、run/command/event/runner/backend 操作入口。 | `spec-v01-cli.md` | -| Durable store | 数据存储 | 保留，P0 | 保存 runs、commands、events、runners、backends、leases；具体存储可从 file/sqlite/Postgres 起步，但必须有迁移边界。 | `spec-v01-state-store.md` | +| Postgres durable store | 稳定外部服务 | 保留，P0 | 使用 `agentrun-v01-postgres` 保存 runs、commands、events、runners、backends、leases 和 migration ledger；不使用 file/sqlite 作为 v0.1 durable store。 | `spec-v01-postgres.md` | +| Secret distribution | 系统能力 | 保留，P0 | API Key 只通过 Kubernetes SecretRef、ServiceAccount/RBAC 和 runner env/file projection 分发；source、GitOps、logs 和 events 不保存明文。 | `spec-v01-secret-distribution.md` | | Tenant policy boundary | Run schema 合同 | 保留，P0 | 作为 `Run` 的必填字段和最小校验存在，不做独立 policy engine；tenant 的业务授权仍由 UniDesk/HWLAB 判定。 | 并入 `spec-v01-agentrun-mgr.md` | | Observability | 最小事件/日志合同 | 保留，P0 子项 | 作为 manager/runner 的 event、terminal status、failureKind、logPath 和 redaction 最小合同，不拆独立观测系统。 | 并入 `spec-v01-agentrun-mgr.md`、`spec-v01-agentrun-runner.md` | | `agentrun-scheduler` | 长驻调度器 | Deferred | M1-M3 稳定后再实现自动 pending scan、capacity selection 和 runner Job 创建。 | `spec-v01-scheduler.md` | @@ -91,7 +92,7 @@ Run create 的最小字段合同： | `executionPolicy` | 必填或由 manager 显式写入默认值，至少包含 sandbox、approval、timeout、network 和 secret scope。 | | `traceSink` | 字段必须存在；可以为 `null` 或显式 sink，表示标准事件是否需要镜像给 tenant。 | -Manager 负责校验、保存和返回这些字段；runner 只能消费已保存的 run policy，不能自行扩大 workspace、network 或 secret scope。HWLAB live device mutation、UniDesk production deploy、GitHub issue/PR 写入等业务授权仍由 tenant 自己的入口判定，AgentRun 不把这些业务规则内建成通用门禁。 +Manager 负责校验、保存和返回这些字段；runner 只能消费已保存的 run policy，不能自行扩大 workspace、network 或 secret scope。`executionPolicy.secretScope` 只能引用 [spec-v01-secret-distribution.md](spec-v01-secret-distribution.md) 定义的 SecretRef 或 credential source，不能携带 API Key 明文。HWLAB live device mutation、UniDesk production deploy、GitHub issue/PR 写入等业务授权仍由 tenant 自己的入口判定，AgentRun 不把这些业务规则内建成通用门禁。 ## 最小 Observability 合同 @@ -136,6 +137,8 @@ Manager 负责校验、保存和返回这些字段；runner 只能消费已保 | `v0.1` 服务总体规格 | 已定义 | 本文定义服务总览和取舍表。 | | 文档治理规格 | 已定义 | 见 [spec-v01-documentation-governance.md](spec-v01-documentation-governance.md)。 | | CI/CD lane 规格 | 已定义 | 见 [spec-v01-cicd.md](spec-v01-cicd.md)。 | +| Postgres durable store 规格 | 已定义 | 见 [spec-v01-postgres.md](spec-v01-postgres.md)。 | +| Secret 分发规格 | 已定义 | 见 [spec-v01-secret-distribution.md](spec-v01-secret-distribution.md)。 | | `agentrun-mgr` 实现 | 未实现 | 需后续单服务 spec 和代码实现。 | | `agentrun-runner` 实现 | 未实现 | 需后续单服务 spec 和代码实现。 | | 第一真实 backend | 未实现 | 默认候选 Codex，需后续 backend spec。 |