docs(gitops): document ljwx deployment flow

README.md

@@ -5,6 +5,7 @@ GitOps 配置仓库，使用 ArgoCD 管理 Kubernetes 集群。
 ## Start Here
 
 - 新进程/新项目/老项目统一接入入口：`docs/START-HERE-GITOPS-ONBOARDING.md`
+- LJWX 业务部署权威流程：`docs/ljwx-business-deployment-flow.md`
 - 自动扫描当前仓库是否已接入：`bash scripts/ops/scan-gitops-context.sh --repo "$PWD"`
 
 ## Platform Blueprint
@@ -44,11 +45,11 @@ GitOps 配置仓库，使用 ArgoCD 管理 Kubernetes 集群。
 
 ## 生产发布闭环（当前口径）
 
-1. 服务仓在 GitHub / EU Runner 构建，并把候选镜像 push 到 `harbor.eu.lingjingwanxiang.cn`（EU Harbor）。
+1. 服务仓在 GitHub / Runner 构建，并把候选镜像 push 到 profile 指定的 candidate registry；当前标准优先 GHCR。
 2. 服务仓上传 `ReleaseBundle` artifact，并向 `ljwx-release-state` 发 `repository_dispatch`。
 3. `ljwx-release-state` 生成 `Event -> ReleaseBundle -> ReleaseRequest -> DeployResolution`。
 4. `deploy-controller-v2` 从 `ljwx-release-state` 拉取 resolution，并作为 `ljwx-deploy` 的唯一写入者更新 overlay。
-5. 如目标为 `prod`，controller 负责把镜像复制到 `https://harbor.omniverseai.net/` 后再提交 overlay。
+5. 如目标为 `prod`，controller 按 `release/services*.yaml` 的 `deployImage` 和 resolution 的 `copyRequired` 决定是否复制镜像；`deployImage` 为 GHCR 且 `copyRequired=false` 时不经过本地 Harbor。
 6. controller 把 `ReleaseResult` 回写到 `ljwx-release-state`；legacy promoter/smoke CronJob 已 suspend，不再作为默认发布入口。
 
 ## 组件

docs/ljwx-business-deployment-flow.md

@@ -0,0 +1,264 @@
+# LJWX 业务部署流程
+
+本文把当前 GitOps v2 链路整理成 LJWX 业务服务的标准部署流程。目标是让任意业务仓按同一套方式交付到 k3s，并通过域名对外提供服务。
+
+## 1. 环境分层
+
+LJWX 业务服务按三个 profile 管理：
+
+| Profile | 用途 | 入口 | 部署方式 |
+| --- | --- | --- | --- |
+| `dev` | 本地开发 | 服务仓 | 直接启动后端/前端，快速调试业务代码 |
+| `test` | 集成验证 | 服务仓 | `docker compose` 启动依赖和服务，再跑 Playwright / API E2E |
+| `prod` | 生产交付 | GitHub Actions + GitOps | workflow 构建镜像，发布 `ReleaseBundle`，由 GitOps controller 写 deploy overlay，ArgoCD 同步到 k3s |
+
+`dev` 和 `test` 可以直接操作本地运行环境；`prod` 的长期状态只能来自 Git。
+
+`test` profile 不进入 `ljwx-deploy`，它只是服务仓本地 `docker compose` 集成验证概念。`ljwx-deploy` 当前长期管理的是 `cluster/` 下的 dev 类 Application 和 `cluster-prod/` 下的 prod Application。
+
+## 2. 仓库职责
+
+| 仓库 | 职责 |
+| --- | --- |
+| 业务仓，如 `ljwx-platform` | 业务代码、Dockerfile、`.gitops/service.yaml`、GitHub workflow、ReleaseBundle 生成 |
+| `ljwx-release-state` | 接收并保存 `Event` / `ReleaseBundle` / `ReleaseRequest` / `DeployResolution` / `ReleaseResult` |
+| `ljwx-deploy` | 唯一的 k8s desired state 仓库：service map、namespace、runtime contract、overlay、ArgoCD Application |
+| k3s + ArgoCD | 只负责拉取 `ljwx-deploy` 中声明的 desired state 并同步到集群 |
+
+服务仓不直接写 `ljwx-deploy` overlay，也不直接 `kubectl apply` prod 业务资源。
+
+## 3. 标准 GitOps v2 链路
+
+标准链路：
+
+```text
+业务仓 commit
+  -> GitHub workflow
+  -> build multi-arch image to GHCR
+  -> ReleaseBundle
+  -> ljwx-release-state
+  -> DeployResolution
+  -> deploy-controller-v2
+  -> ljwx-deploy overlay commit
+  -> ArgoCD sync
+  -> k3s rollout
+  -> ReleaseResult / E2E evidence
+```
+
+关键规则：
+
+1. 业务仓只发布事实和请求：镜像 digest、组件、目标环境、bundle 信息。
+2. `deploy-controller-v2` 是唯一允许修改 `apps/*/overlays/*/kustomization.yaml` 的自动化写入者。
+3. ArgoCD 只监听 `ljwx-deploy` 的 Git 变更；集群内手工 patch 只能用于临时排障，必须回写 GitOps 才算完成。
+4. 镜像以 digest 部署，避免 tag 漂移。
+
+当前 `deploy-controller-v2` 在仓内主要以脚本集合存在，而不是一个单独目录名的服务：
+
+- `scripts/gitops_v2/apply_resolutions.py`：把 `DeployResolution` 应用到 overlay。
+- `scripts/gitops_v2/copy_resolution_images.py`：按 `copyRequired` 执行需要的 prod 镜像复制。
+- `scripts/gitops_v2/profile_matrix.py`：解析 `target_env` / `target_profile`。
+- `scripts/gitops_v2/render_shadow_diff.py`：渲染 resolution 对 overlay 的影响。
+
+这些脚本可由 workflow / controller 调度执行；生产语义上仍称为 `deploy-controller-v2`，因为 overlay commit 必须由这条 controller 路径产生。
+
+`ReleaseBundle` 的 schema 和真实样例在 `ljwx-release-state` 仓内：
+
+- `schemas/release-bundle.schema.json`
+- `bundles/lingjingwanxiang__ljwx-platform/lingjingwanxiang/ljwx-platform-25745384295-bf4f1ba.json`
+
+## 4. 镜像策略
+
+当前 LJWX 优化后的默认策略是：
+
+1. 业务镜像构建后推送到 GHCR。
+2. `release/services*.yaml` 中的 `deployImage` 决定最终写入 overlay 的运行镜像仓库。
+3. 如果 `deployImage` 是 GHCR，并且 release resolution 中 `copyRequired=false`，则不复制到本地 Harbor。
+4. 本地 Harbor 只作为显式需要 Harbor 部署镜像的服务目标；不是所有 prod 发布的必需前置条件。
+
+以 `ljwx-platform` 为例，三个 prod service mapping 都应保持 GHCR deploy image：
+
+| service | deploy image |
+| --- | --- |
+| `ljwx-platform` | `ghcr.io/lingjingwanxiang/ljwx-platform/ljwx-platform` |
+| `ljwx-platform-admin-ui` | `ghcr.io/lingjingwanxiang/ljwx-platform/ljwx-platform-admin-ui` |
+| `ljwx-platform-screen` | `ghcr.io/lingjingwanxiang/ljwx-platform/ljwx-platform-screen` |
+
+这 3 个 component 在 `release/services.yaml` 中各自有 service mapping 和 GHCR 镜像引用，但共享同一个 overlay：`apps/ljwx-platform/overlays/prod/kustomization.yaml`。这是 `multi-image-service` 模板模式，参考 `factory/onboarding/service-templates.yaml`。
+
+这类服务的 namespace 需要有 `ghcr-pull` / `regcred` 等 pull secret，但不需要 Harbor 账号密码参与镜像复制。
+
+## 5. 新业务服务接入
+
+### 5.1 服务仓配置
+
+服务仓需要具备：
+
+- `.gitops/service.yaml`
+- `.github/workflows/release-to-gitops.yml`，这是当前标准 prod 路径
+- 每个组件的 Dockerfile
+- 可验证的健康检查路径
+
+旧的 `build-and-enqueue.yml` 已废弃；如果业务仓里还存在 `.github/workflows/build-and-enqueue.yml.disabled`，不要重新启用，新接入直接使用 `release-to-gitops.yml` 或等价的 GitOps v2 workflow。
+
+多组件服务应使用一个 bundle 管理所有组件，避免三个组件各自独立推进导致版本不一致。
+
+### 5.2 deploy 仓映射
+
+在 `ljwx-deploy` 中登记或生成：
+
+- `factory/onboarding/services.catalog.yaml`
+- `release/services.yaml`
+- `release/services.local-k3s.yaml`
+- `release/services.orbstack-k3s-cn.yaml`
+- `apps/<service>/base/*`
+- `apps/<service>/overlays/<env>/kustomization.yaml`
+- `apps/<service>/overlays/<env>/runtime-contract/*`
+- `cluster-prod/<service>-prod-application.yaml`
+- `cluster-prod/kustomization.yaml`
+
+已有复杂 ingress 的服务可以设置 `generate_ingress: false`，保留手写 ingress，但仍要登记 runtime contract 和 service map。
+
+## 6. 生产发布步骤
+
+以 `ljwx-platform` 为例：
+
+1. 确认代码已合入生产分支，并完成常规验证。
+2. 触发生产 workflow：
+
+   ```bash
+   gh workflow run release-to-gitops.yml \
+     -R lingjingwanxiang/ljwx-platform \
+     --ref main \
+     -f target_env=prod \
+     -f target_profile=prod-planned
+   ```
+
+   `prod-planned` 来自 `platform/assembly/env-matrix.yaml#profiles.prod-planned`，由 `scripts/gitops_v2/profile_matrix.py` 解析；如需新增或调整 profile，先改 profile matrix，再同步相应 service map / smoke targets。
+
+3. 完成 GitHub Environment `production` approval。
+4. workflow 编译后端、type-check 前端、构建 backend/admin/screen 三个 GHCR 镜像。
+5. workflow 生成一个 `ReleaseBundle` 并发送到 `ljwx-release-state`。
+6. `deploy-controller-v2` 根据 `DeployResolution` 更新 `ljwx-deploy` 对应 prod overlay。
+7. ArgoCD 自动同步 `cluster-prod` 中声明的 Application。
+8. k3s rollout 完成后进行公网和业务 E2E 验证。
+
+## 7. 验证清单
+
+### 7.1 GitOps 状态
+
+```bash
+kubectl -n argocd get applications.argoproj.io \
+  ljwx-deploy cluster-prod-bootstrap <app-name> -o wide
+```
+
+当前生产链路实际 Application 名可用以下命令核对：
+
+```bash
+kubectl -n argocd get applications.argoproj.io -o name
+```
+
+`ljwx-platform` 当前涉及的固定名称是：
+
+- `application.argoproj.io/ljwx-deploy`
+- `application.argoproj.io/cluster-prod-bootstrap`
+- `application.argoproj.io/ljwx-platform`
+
+期望：
+
+- `SYNC STATUS=Synced`
+- `HEALTH STATUS=Healthy`
+- `REVISION` 指向最新 `ljwx-deploy` commit
+
+如果 ArgoCD 还未刷新，可临时触发 hard refresh：
+
+```bash
+kubectl -n argocd patch application <app-name> --type merge \
+  -p '{"metadata":{"annotations":{"argocd.argoproj.io/refresh":"hard"}}}'
+```
+
+### 7.2 k3s 资源状态
+
+```bash
+kubectl -n <namespace> get deploy,pod,ingress,certificate -o wide
+```
+
+期望：
+
+- Deployment `READY=1/1`
+- Pod `Running`
+- Ingress host 正确
+- Certificate `Ready=True`
+- 镜像为期望的 GHCR digest
+
+### 7.3 公网入口
+
+```bash
+curl -I https://<host>/
+curl -sS https://<backend-host>/actuator/health/readiness
+```
+
+对 `ljwx-platform`：
+
+```bash
+curl -I https://platform-admin.omniverseai.net/
+curl -I https://platform-screen.omniverseai.net/
+curl -sS https://platform-backend.omniverseai.net/actuator/health/readiness
+```
+
+期望 backend readiness 返回：
+
+```json
+{"status":"UP"}
+```
+
+### 7.4 业务 E2E
+
+最少验证：
+
+1. Playwright 打开公网 admin 域名。
+2. 使用测试账号登录。
+3. 页面进入 `/dashboard`。
+4. Console 无业务错误。
+5. 关键 API 返回 `http=200` 且业务 code 为 `200`。
+6. 大屏静态页和已认证大屏 API 均可访问。
+
+## 8. 数据库与 runtime secret
+
+生产部署前必须确认：
+
+- `runtime-app` / DB / Redis / MQTT 等 Secret 已存在。
+- Secret 只在集群或 Secret 管理系统中维护，不入 Git。
+- 如果服务已退役 Flyway，生产库必须按项目约定补齐 baseline DDL。
+
+`ljwx-platform` 当前需要注意：
+
+- 历史 `V*.sql` 是冻结快照。
+- 运行 schema 还依赖 `db/baseline/init-care/*.sql` 和 `db/baseline/init-platform/*.sql`。
+- 新库或 schema 漂移库需要按业务仓 `<业务仓>/scripts/reset-database.sh` 中的顺序应用，例如 `ljwx-platform/scripts/reset-database.sh`。
+
+## 9. 故障定位顺序
+
+1. workflow 是否成功：编译、type-check、镜像构建、ReleaseBundle 发布。
+2. `ljwx-release-state` 是否生成 `DeployResolution`。
+3. `deploy-controller-v2` 是否提交了 `ljwx-deploy` overlay。
+4. ArgoCD Application 是否 `Synced/Healthy`，revision 是否最新。
+5. k3s pod 是否能拉 GHCR 镜像。
+6. Ingress class、TLS issuer、certificate 是否正确。
+7. 应用日志是否有 schema/runtime secret/配置错误。
+8. 用 Playwright 做真实公网浏览器验证。
+
+回滚、节点重建、知识库重发等操作不要散落在临时命令里，详细步骤见 `runbooks/`：
+
+- `runbooks/rollback.md`
+- `runbooks/node-rebuild.md`
+- `runbooks/knowledge-republish.md`
+
+## 10. 禁止事项
+
+- 禁止把 prod desired state 只留在集群 live patch。
+- 禁止服务仓直接改 deploy overlay。
+- 禁止把 Secret、Harbor 密码、GitHub token 写入 Git。
+- 禁止把旧 `release/queue.yaml` 当作 GitOps v2 主入口；该文件仅为历史审计和旧工具兼容保留，视为冻结兼容文件。
+- 禁止默认要求本地 Harbor 参与所有 prod 发布；是否复制镜像由 service map / DeployResolution 决定。
+- 禁止绕过 ArgoCD 直接长期维护 k3s 业务资源。
+- 禁止在 prod 默认打开 `SKIP_REGISTRY_CHECK=1` 或 `SKIP_EVIDENCE_COLLECT=1`。`cluster-prod/deploy-promoter-prod-cronjob.yaml` 中这两个值应保持 `"0"`；只有短期排障可以临时打开，且必须恢复，否则会绕过 registry availability 和 evidence collection。

docs/superpowers/specs/2026-04-07-orbstack-k3s-upgrade-design.md

@@ -0,0 +1,145 @@
+# Mac Studio OrbStack K3S Deployment Upgrade
+
+## Goal
+
+Deploy ljwx-health, omni-stock, zhihu-engine, ljwx-shiti to Mac Studio OrbStack k3s
+with latest multi-arch GHCR images, then automate the dev → orbstack-k3s-cn promotion pipeline.
+
+## Context
+
+- Mac Studio runs OrbStack k3s (arm64), profile `orbstack-k3s-cn`
+- ArgoCD is running, services deployed with stale digests
+- All 4 services already have multi-arch images on GHCR (amd64+arm64)
+- Infrastructure (PostgreSQL/Redis) is in `infra` namespace inside k3s
+- No orbstack-specific overlays exist; services share `dev` or `k3s-eu` overlays
+
+## Services & Current State
+
+| Service | Overlay Path | Images | In Services Map? |
+|---------|-------------|--------|-----------------|
+| ljwx-health | `overlays/k3s-eu` | boot, admin, bigscreen | Yes |
+| omni-stock | `overlays/dev` | backend, frontend | **No** |
+| zhihu-engine | `overlays/dev` | backend, frontend | **No** |
+| ljwx-shiti | `overlays/dev` | shiti | Yes |
+
+## Phase 1: Update Digests (Manual, ~30 min)
+
+### 1.1 Get latest digests from GHCR
+
+Query the latest digest for each image:
+- `ghcr.io/lingjingwanxiang/ljwx-health/ljwx-boot`
+- `ghcr.io/lingjingwanxiang/ljwx-health/ljwx-admin`
+- `ghcr.io/lingjingwanxiang/ljwx-health/ljwx-bigscreen`
+- `ghcr.io/lingjingwanxiang/omni-stock/backend`
+- `ghcr.io/lingjingwanxiang/omni-stock/frontend`
+- `ghcr.io/lingjingwanxiang/zhihu-engine/backend`
+- `ghcr.io/lingjingwanxiang/zhihu-engine/frontend`
+- `ghcr.io/lingjingwanxiang/ljwx-shiti`
+
+### 1.2 Update overlay kustomization.yaml files
+
+Update digest values in:
+- `apps/ljwx-health/overlays/k3s-eu/kustomization.yaml`
+- `apps/omni-stock/overlays/dev/kustomization.yaml`
+- `apps/zhihu-engine/overlays/dev/kustomization.yaml`
+- `apps/ljwx-shiti/overlays/dev/kustomization.yaml`
+
+### 1.3 Push to main → ArgoCD auto-syncs
+
+Commit and push to `ljwx-deploy` main branch. ArgoCD on Mac Studio watches
+these overlay paths and will automatically sync the new digests.
+
+### 1.4 Verify deployment
+
+Check ArgoCD sync status and pod health on Mac Studio:
+- All pods running with new digests
+- Health endpoints responding
+- Ingress routing working
+
+## Phase 2: Automate CI → orbstack-k3s-cn Pipeline
+
+### 2.1 Add omni-stock and zhihu-engine to services mapping
+
+Update `release/services.orbstack-k3s-cn.yaml` to include:
+
+```yaml
+omni-stock-backend:
+  overlayPath: apps/omni-stock/overlays/dev/kustomization.yaml
+  kustomizeImageName: ghcr.io/lingjingwanxiang/omni-stock/backend
+  argocdApp: omni-stock-dev
+
+omni-stock-frontend:
+  overlayPath: apps/omni-stock/overlays/dev/kustomization.yaml
+  kustomizeImageName: ghcr.io/lingjingwanxiang/omni-stock/frontend
+  argocdApp: omni-stock-dev
+
+zhihu-engine-backend:
+  overlayPath: apps/zhihu-engine/overlays/dev/kustomization.yaml
+  kustomizeImageName: ghcr.io/lingjingwanxiang/zhihu-engine/backend
+  argocdApp: zhihu-engine-dev
+
+zhihu-engine-frontend:
+  overlayPath: apps/zhihu-engine/overlays/dev/kustomization.yaml
+  kustomizeImageName: ghcr.io/lingjingwanxiang/zhihu-engine/frontend
+  argocdApp: zhihu-engine-dev
+```
+
+### 2.2 Ensure service repos have CI → deploy pipeline
+
+Each service repo needs a `build-and-enqueue.yml` that:
+1. Builds multi-arch image → GHCR
+2. Updates the overlay digest in ljwx-deploy
+3. ArgoCD auto-syncs
+
+Check and fix CI for: omni-stock, zhihu-engine, ljwx-shiti.
+ljwx-health already has a working `deploy.yml` using `ci-deploy.yml` template.
+
+### 2.3 Verify end-to-end flow
+
+Push a trivial change to a service repo, confirm:
+- CI builds multi-arch image
+- Overlay digest updated in ljwx-deploy
+- ArgoCD syncs on Mac Studio
+- New pod running
+
+## Phase 3: Fix build-ghcr.yml QEMU Gap
+
+### 3.1 Problem
+
+`ljwx-workflow-templates/.github/workflows/build-ghcr.yml` uses `docker/setup-buildx-action@v3`
+but does NOT include `docker/setup-qemu-action@v3`. This means arm64 builds may fail
+on amd64 GitHub-hosted runners.
+
+`ci-deploy.yml` already includes QEMU setup correctly.
+
+### 3.2 Fix
+
+Add QEMU setup step to `build-ghcr.yml` before the Buildx setup step:
+
+```yaml
+- name: Set up QEMU
+  uses: docker/setup-qemu-action@v3
+```
+
+### 3.3 Verify
+
+Trigger a build for a service using `build-ghcr.yml` template and confirm
+both amd64 and arm64 manifests are present in GHCR.
+
+## Success Criteria
+
+- [ ] All 4 services running on Mac Studio with latest GHCR digests
+- [ ] ArgoCD shows Synced/Healthy for all 4 apps
+- [ ] Health endpoints responding on Mac Studio
+- [ ] omni-stock and zhihu-engine in services mapping
+- [ ] New builds automatically flow to Mac Studio via CI
+- [ ] build-ghcr.yml includes QEMU setup for reliable multi-arch builds
+
+## Risks
+
+| Risk | Mitigation |
+|------|-----------|
+| PostgreSQL schema mismatch (old DB, new app) | Run Flyway migrations as part of app startup |
+| Ingress/DNS differences on Mac Studio | Use `.local` domain or update ingress hosts |
+| GHCR pull rate limits | OrbStack has built-in image caching |
+| ArgoCD repo access (GitHub token) | Verify ArgoCD can pull from ljwx-deploy main |