@aipt/idp-deploy 0.1.4 → 0.1.5

package/docs/features/kubernetes-gitops-deployment-backend/DESIGN.md

@@ -0,0 +1,472 @@
+# Kubernetes GitOps 部署后端 DESIGN
+
+- 状态：implemented-local-foundation
+- 批次：idp-deploy.kubernetes-gitops-deployment-backend@1
+- 依据：2026-08-31 架构复盘确认吸收 `kubernetes-config` 的应用配置、环境覆盖、ApplicationSet 与 Argo CD 收敛能力，但不复制其跨仓 `sed`、可变 tag、明文 Secret 或宽权限实现。
+- 当前实现状态：create/update/remove Plan、Apply、Repository Verify、本机 foundation doctor/verify 和 Portal directory sync 已实现并通过 fixture；生产 Promotion PR Adapter 与远程 Argo Evidence 仍是后续边界。
+
+## 结论
+
+`kubernetes-config` 的能力已经纳入 IDP 架构：Owner 是 `idp-deploy` 的 Kubernetes GitOps Renderer/Repository Adapter，批准后的期望状态存入独立 `idp-gitops`。当前 `idpctl` 已具有应用级 create/update/remove Plan、Apply 与 Repository Verify；Promotion PR 与远程 Argo Evidence 尚未实现，不能把本地 Git commit 冒充生产发布完成。
+
+融合不是把 `kubernetes-config` 整仓复制到 `idp-deploy`，而是保留其有效控制流：
+
+```text
+应用运行合同
+  → 基础部署模板
+  → 环境差异
+  → ApplicationSet
+  → Git Repository State
+  → Argo CD 收敛
+  → 运行态验证
+```
+
+同时统一到现有 Kernel：
+
+```text
+Catalog / ComponentContract
+  → immutable Plan
+  → Precondition + Preimage
+  → Render
+  → GitOps Apply
+  → Argo Verify
+  → Evidence
+```
+
+Compose 与 Kubernetes GitOps 必须调用同一个 Plan、镜像锁、配置安全和 Evidence Kernel，不能形成第二套发布逻辑。
+
+## `kubernetes-config` 当前如何接入一个新应用
+
+以 `kite-website` 为代表，当前实际需要人工完成四类资产。
+
+### 1. 应用基础模板
+
+在 `applications/<app>/<chart>/` 创建 Helm Chart，通常包含：
+
+- `Chart.yaml`；
+- 默认 `values.yaml`；
+- Deployment；
+- Service；
+- Ingress；
+- 可选 HPA、ServiceAccount、Secret/ExternalSecret 与监控资源。
+
+仓库同时存在 Helm、Kustomize 和直接 YAML 多种形态，没有统一的新应用输入合同或生成器。
+
+### 2. 环境覆盖
+
+在下列目录为每个集群/Namespace 保存覆盖值：
+
+```text
+applications/<app>/environments/<cluster>/<namespace>/values.yaml
+```
+
+覆盖项通常包括镜像仓库和 tag、副本数、资源、Ingress、域名、证书 ARN、环境变量、节点架构和自动伸缩。
+
+### 3. Argo CD ApplicationSet
+
+在 `argocd/applicationsets/<app>.yaml` 中列出目标集群、Namespace、Git ref、Chart 路径和环境 values 路径，并定义自动同步、self-heal、prune 与 Namespace 创建策略。
+
+`argocd/bootstrap/kustomization.yaml` 整体包含 `../applicationsets/`；bootstrap Application 跟踪 Git main，因此新增 ApplicationSet 合入后由 Argo CD 创建目标 Application。
+
+### 4. 应用源码仓 Workflow
+
+应用仓的 GitHub Actions 通常执行：
+
+```text
+源码 push
+  → docker build
+  → 推送 ECR tag
+  → checkout kubernetes-config
+  → 读取并替换环境 values.yaml 中的 image.tag
+  → commit/push kubernetes-config main
+  → Argo CD self-heal/sync
+```
+
+`kite_website` 分别使用 `stage` 与 `main` 分支更新 nonprod/prod 环境。该路径能工作，但缺少 OCI digest、不可变 Plan、CAS、并发序列化、统一验证、生产 Promotion PR 和完整恢复证据。
+
+## `kite-website` 完整配置清单
+
+`kite-website` 的部署事实不是一个文件，而是分散在源码仓、GitHub、GitOps 仓和集群控制器中的多类配置。
+
+| 层次 | 位置 | 当前内容 | 生效时间 |
+| --- | --- | --- | --- |
+| 源码公共配置 | `kite_website/.env.development`、`.env.production` | `NEXT_PUBLIC_IMAGE_URL` | Next.js build 时固化进前端产物 |
+| 构建合同 | `kite_website/Dockerfile` | Node 20、依赖安装、`npm run build`、3000 端口 | 镜像构建时 |
+| CI 触发 | `.github/workflows/deploy-stage.yml`、`deploy-prod.yml` | `stage`/`main` push 与手工触发 | GitHub event 时 |
+| CI 凭据 | GitHub Environment/Secrets | AWS access key、ECR 登录、GitOps deploy key | CI Job 运行时 |
+| 制品身份 | ECR tag | `stage-<run>-<sha>` / `prod-<run>-<sha>` | push 镜像时 |
+| 应用默认部署值 | `applications/kite-website/kite-website/values.yaml` | 默认镜像、资源、副本、Service、Ingress、HPA、节点架构、env | Helm render 时，被环境值覆盖 |
+| 环境部署值 | `environments/gokite-nonprod/.../values.yaml`、`gokite-prod/.../values.yaml` | ECR、tag、资源、副本、ALB、域名、证书 ARN、环境名、集群名 | Helm render 时 |
+| Kubernetes 模板 | Chart 的 Deployment、Service、Ingress、HPA | 将 values 转为集群资源 | Argo repo-server render 时 |
+| 应用注册 | `argocd/applicationsets/kite-website.yaml` | 两个 cluster、namespace、Git ref、Chart/valueFiles、sync policy | ApplicationSet reconcile 时 |
+| bootstrap 注册 | `argocd/applicationsets/kustomization.yaml`、`argocd/bootstrap/kustomization.yaml` | 将 `kite-website` ApplicationSet 纳入 bootstrap | bootstrap Application sync 时 |
+| 集群接入 | Argo CD repository/cluster Secret | Git 仓读取权限与目标集群凭据 | Argo controller reconcile 时 |
+| 平台能力 | ExternalDNS、Ingress/ALB、监控等 system-tools | DNS、负载均衡和集群公共服务 | 相应 controller reconcile 时 |
+
+这说明 GitHub Environment 不是应用配置的唯一来源，`kubernetes-config` 也不是全部事实的唯一来源。它们分别承担 CI 执行配置和 Kubernetes 期望状态。
+
+`kite-website` 目前还有几个会影响发布可信度的具体缺口：
+
+- Dockerfile 没有显式 build arg，构建会读取源码中的 `.env.production`；公共配置变化需要重新构建镜像；
+- GitHub Workflow 使用静态 AWS access key，而不是工作负载/OIDC 短期身份；
+- 环境 values 写镜像 tag，不写 OCI digest；
+- Deployment 声明的 container port 与 Service target port 不一致；
+- 没有 liveness、readiness 或 startup probe；
+- 使用普通 Deployment，没有 Rollout/AnalysisTemplate，因此当前不是金丝雀发布；
+- prod/nonprod 的安全上下文、HPA 和资源策略不一致，未由统一 Contract 校验；
+- 域名、AWS account、ACM certificate ARN 与集群名直接硬编码在 values；
+- CI commit GitOps main 后没有等待并核验 Argo/Kubernetes 最终状态。
+
+## 对现有三步理解的校正
+
+### 1. GitHub 环境变量只应承担 CI 配置
+
+“每个应用在 GitHub 项目维护环境变量，Workflow 取值”只对 CI 执行配置成立，例如：
+
+- Registry 地址和构建目标；
+- GitHub OIDC role；
+- GitOps 仓地址；
+- CI 的临时凭据；
+-构建开关。
+
+应用运行配置不应全部放在 GitHub Secrets/Variables。否则运行时配置更新必须重跑 CI，而且 GitHub 会变成部署配置的隐式事实源。
+
+目标体系必须区分：
+
+| 配置类型 | 示例 | Owner/存储 | 更新行为 |
+| --- | --- | --- | --- |
+| 构建配置 | Node 版本、公开前端 build-time URL | 应用源码合同 + CI | 生成新镜像 |
+| 部署配置 | replicas、resources、port、rollout strategy | DeploymentPlan/GitOps Repository State | Argo reconcile |
+| 冷启动运行配置 | 数据库模式、服务 URL、固定业务策略 | 版本化 ConfigRelease/ConfigMap 引用 | 新 Pod rollout |
+| Secret | 密码、Token、私钥、Provider credential | Secret Manager + ExternalSecret | Provider/External Secrets 轮换 |
+| 热更新配置 | 动态阈值、限流、运营参数 | 已批准的成熟 Config Provider | 应用 watch/poll，无镜像重建 |
+| Feature Flag | 灰度开关、受众规则 | OpenFeature-compatible Provider/成熟 Flag 服务 | 按策略动态求值 |
+
+不要因为希望支持热更新就立即自研配置中心。第一阶段默认采用版本化 ConfigMap/Secret 引用和受控 rollout；只有真实应用需要秒级动态配置、推送、历史回滚和多环境治理时，Bench 才发布 Nacos、Apollo 或其他已选成熟 Provider 的 Offering，应用通过 Config Binding 消费。Feature Flag 使用 OpenFeature 兼容 Provider，不把动态业务规则写入 Helm values。
+
+ComponentContract 应声明配置能力：
+
+```yaml
+spec:
+  configuration:
+    buildTimeKeys: [NEXT_PUBLIC_IMAGE_URL]
+    runtime:
+      mode: file
+      reload: restart # restart | watch | dynamic-provider
+    secrets:
+      provider: environment-binding
+```
+
+### 2. GitOps 仓是中央部署登记簿，不等于完整发布工单
+
+把 `kubernetes-config` 理解为“所有应用的中央部署配置和注册表”是正确的。它保存：
+
+- 哪些应用被 Argo 管理；
+- 应用部署到哪些 cluster/namespace；
+- 使用什么模板和环境覆盖；
+- 期望镜像和资源配置；
+- 同步、self-heal 和 prune 策略。
+
+但一个 Git commit 只证明 Repository State 发生变化，不足以单独充当完整金丝雀发布工单。完整发布工单还必须包含：
+
+- Requirement/PR/Acceptance 引用；
+- ReleaseCandidate 和 OCI digest；
+- EnvironmentBinding；
+- 风险与 rollout 策略；
+- 审批事实；
+- Preimage 与冲突前置条件；
+- Analysis 指标和晋级/中止条件；
+- Argo/Kubernetes 最终 Evidence；
+- 数据和配置恢复边界。
+
+因此目标关系是：
+
+```text
+ReleaseCandidate + Approval
+  → DeploymentPlan（发布工单）
+  → GitOps Repository State（批准后的期望状态）
+  → Argo/Kubernetes Runtime State
+  → DeploymentEvidence（实际结果）
+```
+
+GitOps 仓是发布工单 Apply 后的中央登记簿；`idp-deploy` 的不可变 DeploymentPlan 才是完整发布工单。
+
+### 3. Git push 后由 Argo CD 拉取和同步，不是 GitHub 构建钩子发布
+
+`kite-website` 的准确链路是：
+
+```text
+stage/main push
+  → kite_website GitHub Actions
+  → checkout source
+  → 使用 GitHub Secrets 登录 ECR
+  → docker build
+  → push ECR tag
+  → checkout kubernetes-config main
+  → sed 更新对应环境 values.yaml 的 image.tag
+  → commit/push kubernetes-config main
+  → Argo CD 发现 Git revision 变化
+  → bootstrap/ApplicationSet controller reconcile
+  → repo-server 读取 Chart + 环境 values 并执行 Helm render
+  → application-controller 比较 Desired/Live State
+  → automated sync + selfHeal Apply 到目标 cluster/namespace
+  → Kubernetes Deployment 执行普通 RollingUpdate
+  → Service 选择新 Pod
+  → ALB/Ingress 将域名流量送入 Service
+```
+
+`kubernetes-config` 自身的普通应用变更没有“构建发布 Workflow”：
+
+- PR 时 `lint.yaml` 只执行 `kustomize build argocd/bootstrap/`；
+- main push 的 `merge.yaml` 只处理 qugate 两个特殊配置路径；
+- 普通应用的部署执行者是集群中的 Argo CD，而不是 GitHub Actions。
+
+当前链路在 commit/push 后结束，没有证明 Argo Synced/Healthy、Deployment Available、实际镜像 digest、业务 smoke 或金丝雀分析结果。目标 `idp-deploy` 必须补齐等待、验证和 Evidence。
+
+## 当前如何更新应用信息
+
+| 变更 | 当前 `kubernetes-config` 做法 | 当前风险 |
+| --- | --- | --- |
+| 发布新镜像 | 源码 Workflow 用 `sed` 替换环境 values 中的 tag | 可变 tag、并发 push、没有 Plan/CAS |
+| 修改资源/副本 | 直接编辑环境 `values.yaml` | 缺少统一 Schema 和容量证据 |
+| 增加环境 | 新建环境 values，并修改 ApplicationSet list | 人工复制、容易遗漏 Project/Binding |
+| 修改域名/TLS | 直接编辑 Ingress 与云厂商 annotation | 云账号、证书和域名被硬编码 |
+| 修改 Secret | 混用 Secret、SOPS、External Secrets 和 Helm values | 治理不一致，存在明文泄漏风险 |
+| 回滚 | Git revert 旧 tag/YAML，等待 Argo 同步 | 未证明数据库、配置和制品可共同恢复 |
+| 删除应用 | 删除 Git 资产并依赖 prune，或人工 kubectl | 不同 ApplicationSet 的 prune 策略不一致 |
+
+## 目标事实模型
+
+### ComponentContract
+
+应用仓拥有运行合同，不拥有环境实例：
+
+```yaml
+apiVersion: idp.company.io/v1alpha1
+kind: ComponentContract
+metadata:
+  name: example-api
+  version: 1.0.0
+spec:
+  image:
+    platforms: [linux/amd64, linux/arm64]
+    port: 8080
+  health:
+    liveness: /live
+    readiness: /ready
+  runtime:
+    stateless: true
+    runAsUser: 1000
+    runAsGroup: 1000
+    configRootEnv: IDP_CONFIG_DIR
+    mountReadOnly: true
+  dependencies:
+    required: []
+```
+
+合同描述应用怎样运行，不包含真实 cluster、Namespace、域名、Secret 值或云账号。
+`runAsUser`/`runAsGroup` 必须是显式非零 UID/GID；Renderer 不得通过移除 `runAsNonRoot` 或恢复 Linux capabilities 来兼容以 root 启动的镜像。
+
+### EnvironmentBinding
+
+Bench 拥有环境能力和 Binding：
+
+```text
+environment:stage-cn@v1
+  → clusterRef
+  → namespace policy
+  → ingress class
+  → domain zone
+  → certificate issuer
+  → secret store
+  → architecture / quota / rollout capability
+```
+
+`idp-deploy` 只消费经过验证的 Binding，不按仓库名猜测集群和域名。
+
+### ReleaseCandidate
+
+CI 只提交不可变发布候选：
+
+```text
+source commit
+component contract digest
+OCI index digest
+amd64/arm64 evidence
+SBOM/provenance reference
+acceptance evidence
+target environment ref
+requested rollout strategy
+```
+
+应用源码 Workflow 不再 checkout 或写 GitOps 仓。
+
+### DeploymentPlan
+
+`idp-deploy` 生成并持有：
+
+- ReleaseCandidate digest；
+- ComponentContract digest；
+- EnvironmentBinding digest；
+- OCI digest；
+- 目标 Git revision 与目标路径摘要；
+- 渲染资源集合；
+- sync/prune/rollout 策略；
+- 验证与恢复边界。
+
+### Repository State 与 Evidence
+
+GitOps 仓只保存批准后的 Kubernetes 期望状态，不成为 ComponentContract、ReleaseCandidate 或 Approval 的第二事实源。Apply 后的 Evidence 至少关联：
+
+- DeploymentPlan digest；
+- Git commit；
+- Argo Application/ApplicationSet revision；
+- Kubernetes resource UID 集合；
+- 实际运行 OCI digest；
+- readiness、rollout 和 smoke 结果。
+
+## 目标 CLI 体验
+
+以下 create/update/remove/apply/verify 是当前已实现合同；`plan-promote` 仍是目标合同。
+
+### 初始化应用部署配置
+
+```bash
+node bin/idpctl.mjs gitops app plan-create \
+  --component-contract /absolute/project/deploy/component-contract.yaml \
+  --environment-binding /absolute/bindings/example-api.stage-cn.yaml \
+  --release-candidate /absolute/release-candidate.json \
+  --gitops-root /absolute/idp-gitops \
+  --output "$IDP_CONFIG_DIR/plans/example-api-stage.json" \
+  --config-dir "$IDP_CONFIG_DIR"
+
+node bin/idpctl.mjs gitops app apply \
+  --plan "$IDP_CONFIG_DIR/plans/example-api-stage.json" \
+  --config-dir "$IDP_CONFIG_DIR"
+```
+
+`plan-create` 只生成不可变 Plan 和预览，不写 Git。`apply` 必须重新检查 Contract、Binding、ReleaseCandidate、Git HEAD 和目标路径摘要，保存 Preimage 后创建 GitOps 分支/提交或 PR。
+
+### 更新应用版本或配置
+
+```bash
+node bin/idpctl.mjs gitops app plan-update \
+  --component-contract /absolute/project/deploy/component-contract.yaml \
+  --environment-binding /absolute/bindings/example-api.stage-cn.yaml \
+  --release-candidate /absolute/release-candidate.json \
+  --gitops-root /absolute/idp-gitops \
+  --output "$IDP_CONFIG_DIR/plans/example-api-stage-update.json" \
+  --config-dir "$IDP_CONFIG_DIR"
+
+node bin/idpctl.mjs gitops app apply \
+  --plan "$IDP_CONFIG_DIR/plans/example-api-stage-update.json" \
+  --config-dir "$IDP_CONFIG_DIR"
+```
+
+更新不能执行字符串替换；Renderer 必须从完整冻结输入重新确定性生成目标文件，并以 Preimage/CAS 保护人工修改。
+
+### 验证、晋级与移除
+
+```bash
+node bin/idpctl.mjs gitops app verify \
+  --application example-api \
+  --environment stage-cn \
+  --gitops-root /absolute/idp-gitops \
+  --config-dir "$IDP_CONFIG_DIR"
+
+node bin/idpctl.mjs gitops app plan-promote \
+  --application example-api \
+  --from environment:stage-cn@v1 \
+  --to environment:production-cn@v1
+
+node bin/idpctl.mjs gitops app plan-remove \
+  --component-contract /absolute/project/deploy/component-contract.yaml \
+  --environment-binding /absolute/bindings/example-api.stage-cn.yaml \
+  --release-candidate /absolute/release-candidate.json \
+  --gitops-root /absolute/idp-gitops \
+  --output "$IDP_CONFIG_DIR/plans/example-api-stage-remove.json" \
+  --config-dir "$IDP_CONFIG_DIR"
+```
+
+Promotion 必须复用同一个 OCI digest，不能为 production 重建不同镜像。Remove 必须列出将删除和保留的资源、数据边界及恢复方式；只有验证过的 Removal Plan 才能允许 prune。
+
+## GitOps 仓目标布局
+
+不复制 `kubernetes-config` 的 126 个应用和内嵌第三方 Chart。新仓从最小布局开始：
+
+```text
+gitops/
+  bootstrap/
+  projects/
+  applicationsets/
+  applications/
+    <app>/
+      base/
+      overlays/
+        <environment>/
+```
+
+- AppProject 按环境和权限边界收紧，不允许 `sourceRepos: ['*']`、任意 cluster 和任意 cluster resource；
+- 应用模板由 Renderer 生成或引用受版本控制的共享 Chart，不复制整份第三方 Chart；
+- Secret 只使用 External Secrets 和批准的 SecretStore 引用；
+- 镜像只写 OCI digest；
+- 域名、证书、Cluster 和 Namespace 来自 EnvironmentBinding；
+- production 默认通过 PR promotion；
+- Argo CD 负责收敛，Argo Rollouts 负责 canary/blue-green，`idp-deploy` 不自研流量控制器。
+
+## 脚手架与人工验收
+
+本能力已通过正式 Renderer fixture 生成可运行示例，不创建第二套旁路脚手架。固定命令：
+
+```bash
+node bin/idpctl.mjs gitops app plan-create \
+  --component-contract "$PWD/fixtures/gitops-app/component-contract.yaml" \
+  --environment-binding "$PWD/fixtures/gitops-app/environment-binding.yaml" \
+  --release-candidate "$PWD/fixtures/gitops-app/release-candidate.json" \
+  --gitops-root /absolute/idp-gitops \
+  --output "$IDP_CONFIG_DIR/plans/foundation-demo-local-create.json" \
+  --config-dir "$IDP_CONFIG_DIR"
+```
+
+示例必须走正式 ComponentContract、EnvironmentBinding、ReleaseCandidate、Plan、Apply、Argo Verifier 与 Evidence 链路，并在 kind/k3d 中显示中文验收结果。人工检查：
+
+1. 查看 Plan 中的 OCI digest、目标环境和资源集合；
+2. 检查 GitOps diff 不含 Secret、tag 或硬编码云账号；
+3. 确认 Argo Application 已 Synced/Healthy；
+4. 访问应用 `/live` 与 `/ready`；
+5. 验证更新只改变批准字段；
+6. 验证并发修改时 Apply fail-closed；
+7. 执行 Removal Plan，确认数据资源按策略保留或删除。
+
+清理必须使用正式 Remove 命令，不能手工 `kubectl delete namespace`。
+
+## 实施边界与顺序
+
+1. 先定义并测试 ComponentContract、EnvironmentBinding、ReleaseCandidate、DeploymentPlan 和 DeploymentEvidence 的交叉校验。
+2. 实现只读 Renderer 与 `.examples/` fixture，不连接远程仓库。
+3. 使用 kind/k3d + Argo CD 验证 create、update、冲突、失败、恢复和 remove。
+4. 增加 GitOps Repository Adapter，默认创建分支/PR，不直接推 production main。
+5. 增加 Argo Verifier；确有渐进交付需求时采用 Argo Rollouts。
+6. 最后接入真实应用，首个消费者应是无状态 Flow 或 fixture，不让 SmartGo 定义平台合同。
+
+## 不接收的历史实现
+
+- 应用 Workflow 跨仓 checkout 后 `sed` tag；
+- 可变镜像 tag 或 `latest`；
+- Git 中的明文 Secret；
+- AppProject 全仓、全集群和全资源通配权限；
+- 直接删除 Namespace 的定时脚本；
+- 未经 Plan 的 `kubectl` 写入；
+- 复制第三方 Chart 形成长期 vendoring；
+- 按应用仓库名称、语言或项目类型写分支。
+
+## 完成判据
+
+- `idpctl` 的 create/update/promote/verify/remove 调用同一个 Kernel；
+- 每个写入均来自不可变 Plan，具有 Preimage 与 CAS；
+- 公共入口有契约测试和至少一个 fixture consumer；
+- 镜像只有 OCI digest，并证明 amd64/arm64；
+- Secret、域名、证书和集群全部来自 Binding；
+- 自动测试证明冲突、同步失败、恢复和移除；
+- `.examples/` 脚手架证明真实开发体验；
+- Portal、AI 和 CLI 只投影或调用相同接口，不复制 Renderer。

package/docs/features/kubernetes-gitops-deployment-backend/FOUNDATION-ARCHITECTURE.md

@@ -0,0 +1,201 @@
+# IDP 生产基座与管理界面架构
+
+## 目标
+
+以成熟组件组成从配置、制品、GitOps、渐进交付到观测和恢复的最小生产基座。`idp-deploy` 只自研不可替代的事务 Kernel、跨系统合同和 Verifier，不自研 Kubernetes 控制器、配置中心、认证、监控、DNS、证书或 Secret 系统。
+
+## 本机与阿里云部署决策
+
+当前开发机为 16 GiB 内存，Docker Desktop 配额约 8 GiB。实测 kind 单节点在镜像导入与 Argo 全量收敛期间达到接近宿主全部逻辑核的 CPU 峰值，控制管理器和调度器发生 leader-election 超时；同期节点内存只使用约 2.9–3.6/7.75 GiB。因此瓶颈是本机虚拟化与单节点控制面争用，单纯增加 Docker 内存不能把它变成可靠生产运行面。
+
+确定采用以下分层：
+
+- 本机 kind：按需启动，只运行与生产同构的 GitOps 核心、契约测试、渐进发布和故障恢复演练；不承诺长期可用，不常驻 Prometheus/Grafana/Loki。
+- 共享集成与生产：使用 ACK 托管版 Pro；控制面由云托管，初始 Worker 基线为跨可用区至少 2 个 `4 vCPU / 8 GiB` 节点，经过真实负载测试后再启用弹性或调整规格。要求更高可用时扩为 3 个可用区，不把这个起始规格当作容量结论。
+- 生产遥测：指标使用 ARMS Managed Service for Prometheus，日志使用 SLS，展示使用托管 Grafana；OpenTelemetry 保持厂商中立入口。ACK 默认 ApplicationSet 不再自建 Prometheus/Grafana/Loki。
+- 云资源只能由真实账号、Region、VPC、RAM/RRSA 和预算 Binding 驱动；当前机器没有阿里云凭据，因此只完成 production profile 渲染与 fail-closed 合同，不宣称已经创建 ACK 资源。
+
+采用 ACK 的依据是其托管控制面和生产适用性；ARMS Prometheus 提供 ACK 集成且无需自管时序库存储。参考：[ACK 集群类型](https://www.alibabacloud.com/help/en/ack/ack-managed-and-ack-dedicated/user-guide/ack-cluster-overview/)、[ARMS Managed Service for Prometheus](https://www.alibabacloud.com/help/en/arms/prometheus-monitoring/product-overview/what-is-prometheus)、[ACK 与 KMS Secret 集成](https://www.alibabacloud.com/help/en/kms/key-management-service/user-guide/integrate-kms-secrets-into-ack)。
+
+## 基座服务清单
+
+## 系统所有权
+
+| 系统 | 唯一职责 | 明确不拥有 |
+| --- | --- | --- |
+| Flow | 需求、工作项、参与者（人或 AI）、状态和验收结果的产品事实；把已验收工作转成发布提案 | GitOps 仓库、Kubernetes 写入、镜像构建、Secret 值 |
+| Tech | 可追溯知识、需求上下文、设计/代码/运行证据的检索与关系投影 | 需求状态机、发布审批、任意运维命令 |
+| Dyyto | 工程能力采用 Kernel、Catalog、脚手架、Plan/Apply/Verifier；Workbench 与 CLI 是正式消费者 | Portal、AI Runtime、业务 Studio、部署控制器 |
+| Bench | 消费者能力合同和 EnvironmentBinding；把集群、Namespace、Ingress、DNS、TLS、Secret、Registry、Rollout、Observability 九类环境事实绑定给消费者 | 应用发布状态机、云资源实际值、GitOps 收敛 |
+| idp-deploy | ConfigRelease、ReleaseCandidate、DeploymentPlan、Preimage/CAS、GitOps Renderer/Repository Adapter、DeploymentEvidence | 需求管理、通用配置中心、Kubernetes 控制器、云控制台 |
+| idp-gitops | 已批准部署目标状态与版本锁，是 Argo 的唯一 desired-state 输入 | 审批数据库、构建系统、Secret 值、运行事实 |
+| Portal | Catalog、统一导航、审批入口、跨系统只读摘要与深链 | 复制 Argo/Grafana/云控制台、Secret 编辑、任意 YAML/kubectl |
+| Studios | 从 Dyyto `apps` 迁出的独立产品与业务应用；各自拥有领域模型、代码和发布候选 | Dyyto 工程 Kernel 与平台部署合同 |
+
+Flow 的准确定位不是单纯“需求管理平台”，而是人和 AI 共用的工作交付控制面。AI 可以成为受指派参与者，读取批准的上下文、提交代码/证据和发起验收，但不拥有另一套发布通道。`idp-deploy` 也不是金丝雀 UI 集合体，而是发布事务内核；真正的持续收敛和渐进发布分别由 Argo CD 与 Argo Rollouts 执行。
+
+## 人与 AI 的完整交付闭环
+
+```text
+Flow Requirement / Assignment
+  → Tech 提供可追溯知识与约束
+  → 人或 AI 使用同一 Dyyto Catalog/Scaffold/Plan/Apply
+  → 应用仓分支与 PR
+  → CI 测试、扫描、SBOM、Provenance、OCI digest
+  → Acceptance Evidence 回写 Flow/Tech
+  → Flow 生成 Release Proposal
+  → ReleaseCandidate + ConfigRelease
+  → idp-deploy 生成不可变 DeploymentPlan
+  → GitOps PR / 受保护分支
+  → Argo CD 收敛 + Argo Rollouts 渐进发布
+  → readiness / smoke / SLO analysis
+  → DeploymentEvidence 回写 Portal、Flow、Tech
+```
+
+人和 AI 的差异只在执行者身份、交互方式和风险策略，不在事实模型：二者都必须产出相同的代码 diff、测试证据、Acceptance 和 ReleaseCandidate。人工可以直接开发或复核 AI 提案；AI 可以自动完成低风险任务并发起 PR，但不能绕过仓库权限、不可变 Plan、分支保护和运行期 Verifier。
+
+当前不缺少一套新的“全能中台”，缺少的是三个外部适配闭环：Git Provider PR/Branch Protection、真实 ACK/ACR/KMS/DNS/观测 Binding、远程 Argo/Kubernetes Evidence 回收。若 Flow 出现跨天等待、重试、补偿和大量并发 Agent，再采用 Temporal 作为 Flow 的耐久执行底座；在此之前不自研工作流引擎。动态配置只有出现秒级推送、灰度配置和独立生命周期时才引入 Nacos/Apollo/OpenFeature Provider，冷启动配置继续使用 ConfigRelease + SecretBinding + GitOps。
+
+### M1：安全 GitOps 最小闭环
+
+| 能力 | 采用系统 | Owner | 是否常驻 | 管理入口 |
+| --- | --- | --- | --- | --- |
+| 统一入口 | Backstage Portal | Portal | 是 | Portal Web |
+| 需求/PR/审批 | 现有 Git Provider | 外部系统 | 是 | Git Provider Web |
+| 构建 | GitHub Actions/GitLab CI | 应用项目 | 按任务 | CI Web |
+| OCI/npm 制品 | 企业 Registry；本地 Verdaccio | Registry Provider | 是 | Registry Web/CLI |
+| 发布事务 | idp-deploy Kernel | idp-deploy | CLI/Job | Portal 投影 + CLI |
+| 期望状态 | GitOps Repository | idp-deploy Apply | 否 | Git Provider Web |
+| 状态收敛 | Argo CD + ApplicationSet | 平台运维 | 是 | Argo CD Web |
+| 运行环境 | Kubernetes | 平台运维 | 是 | kubectl；可选只读 Headlamp |
+
+M1 默认只支持 `RollingUpdate`，必须有 OCI digest、readiness、DeploymentEvidence 和失败恢复；不把普通滚动发布称作金丝雀。
+
+### M2：生产网络、Secret 与观测
+
+| 能力 | 采用系统 | 说明 | 管理入口 |
+| --- | --- | --- | --- |
+| Secret 投影 | External Secrets Operator | 从企业 Secret Manager 读取，Git 不保存值 | Secret Manager Web；Argo 只显示引用/状态 |
+| TLS | cert-manager | 使用批准的 Issuer/ClusterIssuer | Argo CD + Grafana 告警，不另建证书 UI |
+| DNS | ExternalDNS | 只允许批准的 zone 与 owner-id | DNS Provider Web；Argo 显示声明 |
+| Ingress/Gateway | 现有 Ingress Controller 或 Gateway API 实现 | 不在应用 values 写云账号和证书 ARN | Argo CD + Provider Web |
+| 遥测 | OpenTelemetry Collector | 应用统一 OTLP 出口 | 无独立业务 UI |
+| 指标 | ARMS Managed Service for Prometheus；本地可选 Prometheus | 发布分析和 SLO 的事实来源，生产不自管时序库 | ARMS/托管 Grafana |
+| 展示 | 托管 Grafana；本地可选 Grafana | Dashboard、Explore、告警 | Grafana Web |
+| 日志 | 阿里云 SLS；本地可选 Loki | 生产优先托管，避免常驻重存储栈 | SLS/托管 Grafana |
+| 告警 | Alertmanager 或企业告警平台 | 告警路由，不承担需求审批 | Grafana/Alertmanager Web |
+
+### M3：渐进交付
+
+| 能力 | 采用系统 | Owner | 管理入口 |
+| --- | --- | --- | --- |
+| Canary/Blue-Green | Argo Rollouts | 平台运维提供模板，应用选择策略 | Argo CD Rollouts 扩展/CLI |
+| 指标分析 | AnalysisTemplate + Prometheus | idp-deploy 绑定批准模板 | Argo CD + Grafana |
+| 人工晋级 | Git Provider Approval 或 Portal 动作 | 需求/发布 Owner | Portal/Git Provider |
+| 自动中止 | Argo Rollouts | 指标或健康失败即中止 | Argo CD |
+
+### 按需能力，不进入默认基座
+
+| 能力 | 引入条件 | 优先方案 | 专业界面 |
+| --- | --- | --- | --- |
+| 动态配置中心 | 秒级推送、历史回滚、配置灰度和多应用共享参数成为真实需求 | Nacos/Apollo 等经评估 Provider | Provider 自带 Web；Portal 只做深链和摘要 |
+| Feature Flag | 请求级受众规则与实验需要独立生命周期 | OpenFeature + 已选 Provider | Provider Web |
+| 长任务编排 | AI 任务跨重启、等待审批、需补偿和多日运行 | Temporal | Temporal Web |
+| 云资源声明 | 频繁自动创建云资源且人工 Terraform 成为瓶颈 | Terraform Controller/Crossplane | 对应 Controller/Cloud Web |
+| 策略引擎 | 多集群统一策略无法由 RBAC/Schema/Branch Protection覆盖 | Kyverno 或 OPA Gatekeeper | Policy Report 投影，不自建 UI |
+
+## 配置体系
+
+```text
+Build Config          应用仓/CI，变化后生成新镜像
+Deployment Config     DeploymentPlan/GitOps，Argo reconcile
+ConfigRelease         非敏感运行配置摘要，restart/watch/dynamic-provider
+SecretBinding         Bench Binding → Secret Manager → ExternalSecret
+Feature Flag          OpenFeature Provider，按需引入
+```
+
+GitHub Secrets 只保存 CI 必需的短期接入配置；生产优先使用 OIDC/workload identity，避免长期云 Access Key。应用运行 Secret 不通过 CI 写入 GitOps 仓。
+
+## 发布链
+
+```text
+Requirement / PR / Acceptance
+  → CI build/test
+  → OCI digest + SBOM/provenance
+  → ConfigRelease
+  → ReleaseCandidate
+  → idp-deploy DeploymentPlan
+  → GitOps PR/Repository State
+  → Argo CD sync
+  → Deployment 或 Rollout
+  → readiness/smoke/analysis
+  → DeploymentEvidence
+  → Portal/Tech 投影
+```
+
+所有环境使用同一 OCI digest做 Promotion，不为 production 重建镜像。
+
+## 管理界面划分
+
+Portal 是统一导航、审批和只读摘要入口，但不是所有专业操作的替代 UI。
+
+### Portal 必须提供
+
+- 软件和应用 Catalog；
+- ComponentContract、ConfigRelease、ReleaseCandidate、DeploymentPlan 与 Evidence 关系；
+- 环境、Binding 和部署状态摘要；
+- 需求、PR、Acceptance 和发布审批入口；
+- Argo、Grafana、Registry、Git、配置 Provider 的受控深链；
+- 中文错误、降级状态和审计时间线。
+
+### 保留的专业界面
+
+| 界面 | 主要用户 | 允许操作 | Portal 集成方式 |
+| --- | --- | --- | --- |
+| Git Provider | 开发者、审批人 | Issue、PR、CI、GitOps PR | 状态摘要 + 深链 |
+| Argo CD | 发布工程师、值班人员 | Diff、Sync、Rollback/Rollout 诊断 | 应用状态 + 深链；生产写权限受 RBAC |
+| Grafana | 开发者、SRE | Dashboard、Explore、告警调查 | SLO/发布指标摘要 + 深链 |
+| Registry Console | 发布工程师、安全人员 | 制品、digest、扫描、保留策略 | 制品摘要 + 深链 |
+| Secret Manager | 极少数安全/运维人员 | Secret 创建、轮换、撤销 | Portal 不展示值，只显示 Binding/轮换状态 |
+| Cloud/DNS Console | 平台运维 | Zone、负载均衡、配额和异常诊断 | 资源引用 + 深链 |
+| 配置中心 UI（按需） | 运营、服务 Owner | 动态配置审批、灰度、回滚 | ConfigRelease 摘要 + 深链 |
+| Temporal Web（按需） | Agent/流程运维 | 长任务诊断、重试和事件历史 | Assignment 状态 + 深链 |
+| Kubernetes 只读 UI（可选） | SRE | 资源诊断 | 默认不安装 Kubernetes Dashboard；确有需求再部署只读 Headlamp |
+
+### 不建设的界面
+
+- 第二个自研 Kubernetes Dashboard；
+- 第二个自研 Grafana/日志查询界面；
+- 在 Portal 中显示或编辑 Secret 值；
+- 绕过 DeploymentPlan 的任意 YAML 编辑器；
+- 允许任意 Shell/kubectl 的运维页面；
+- 复制 Argo CD 的完整 Sync/Rollout 控制面。
+
+## 权限模型
+
+- Portal 普通用户只读运行状态；发布动作生成 Proposal/Plan，不直接执行任意命令；
+- Git Provider 负责代码和 GitOps PR 审批；
+- Argo CD Project、Kubernetes RBAC 和 Namespace 限制实际写范围；
+- production Sync/Promote/Abort 只允许发布角色；
+- Secret Manager 与 Cloud Console 使用独立最小权限；
+- 所有 Portal 深链必须携带资源 identity，不拼接未验证 URL。
+
+## 当前落地状态与后续顺序
+
+1. 已完成：`ConfigRelease`、`ReleaseCandidate`、`DeploymentEvidence`、`DeploymentPlan` Schema、运行时校验与 fixture。
+2. 已完成：Bench `EnvironmentBinding` 的 Kubernetes/Ingress/DNS/TLS/Secret/Registry/Rollout/Observability 能力字段与 fail-closed validator；Ingress class 不依赖集群隐式默认值。
+3. 已完成：独立 `idp-gitops`、idp-deploy Renderer/Repository Adapter、本地 kind + Argo CD/ApplicationSet fixture。
+4. 已完成本机轻量 profile：ingress-nginx、External Secrets、cert-manager、ExternalDNS inmemory/dry-run、OpenTelemetry Collector；Prometheus/Grafana/Loki 只保留本地显式验收，ACK production 默认采用 ARMS Prometheus、SLS 与托管 Grafana。
+5. 已完成：Argo Rollouts canary/blue-green 模板与真实 Rollout fixture；生产指标阈值仍需绑定真实 SLO。
+6. 已完成：Portal 基座管理入口、只读健康摘要与专业界面深链合同。
+7. 后续唯一生产边界：接入企业 Git Provider PR、ACK/ACR/Secret Manager/DNS/托管观测 Binding，并生成远程 Argo/Kubernetes DeploymentEvidence。
+
+## 仍不宣称完成
+
+- 尚未接入生产 Git Provider 的 PR/Branch Protection Adapter；
+- 尚未接入真实 ACK、ACR、阿里云 DNS、Secret Manager 与托管观测账号；
+- 尚未实现跨环境 `plan-promote` 和远程 Argo/Kubernetes Evidence 收集；
+- 动态配置 Provider 仍按真实业务需求引入，不以“基座完整”为由预装；
+- Portal 保持只读摘要和专业界面深链，不增加任意 YAML/Secret 编辑器。
+
+这些能力只有在真实 fixture、失败恢复、移除和专业界面权限验证完成后才能标记可用。