mirrors/pikasTech-HWLAB
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: serialize DEV CD apply

Browse Source
This commit is contained in:
Code Queue Review
2026-05-23 09:08:31 +00:00
parent dc031e0640
commit 24ccabbb89
15 changed files with 2140 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reference/README.md
+1 -1
View File
@@ -20,7 +20,7 @@
| 文档治理与 docs-spec 本地权威 | [documentation-governance.md](documentation-governance.md) |
| 架构和 M3 上位约束 | [architecture.md](architecture.md) |
| DEV 运行态、端口、k3s、DB readiness 和环境边界 | [dev-runtime-boundary.md](dev-runtime-boundary.md) |
| 部署正规化、artifact 发布、回滚和 Cloud Web rollout | [deployment-publish.md](deployment-publish.md) |
| 部署正规化、DEV CD 单事务入口、artifact 发布、回滚和 Cloud Web rollout | [deployment-publish.md](deployment-publish.md) |
| Cloud Workbench 默认界面和 UX 边界 | [cloud-workbench.md](cloud-workbench.md) |
| Code Agent chat 同源通道 readiness 与真实回复判定 | [code-agent-chat-readiness.md](code-agent-chat-readiness.md) |
| MVP E2E 验收测试与带编号测试报告 issue 规则 | [MVP-e2e-acceptance.md](MVP-e2e-acceptance.md) |
docs/reference/deployment-publish.md
+63 -13
View File
@@ -25,9 +25,44 @@ truth.
| Stage | Current HWLAB state | Required next behavior |
| --- | --- | --- |
| 1. Long-term reference | This file records DEV deployment, Cloud Web publish, API/edge/health, frp, D601 registry, k3s rollout, rollback, and verification rules. `AGENTS.md` indexes it. | Keep process issues as sources only; update this reference when a deployment rule changes. |
| 2. CLI or controlled scripts | Existing controlled entrypoints cover contract planning, desired-state planning, artifact publish, DEV apply/report, k3s read-only visibility, and Cloud Web checks. Rollback is documented as commands/report hints but is not yet one unified CLI command. | Converge check, plan, publish, apply, rollback, status, and verify into HWLAB CLI or a small controlled script surface backed by `deploy/deploy.json`. |
| 2. CLI or controlled scripts | `scripts/dev-cd-apply.mjs` is the only formal DEV CD side-effect entrypoint for publish, desired-state refresh, apply, and live verify. Other controlled scripts still cover contract planning, dry-run planning, preflight, single-step internals, k3s read-only visibility, and Cloud Web checks. Rollback is documented as commands/report hints but is not yet one unified CLI command. | Converge check, plan, rollback, status, and verify into HWLAB CLI while preserving the single transaction lock for side effects backed by `deploy/deploy.json`. |
| 3. UniDesk CI/CD plus images | DEV services are imageized and published to the D601 registry. D601 rollout still includes manual bridge steps for Cloud Web and frp/k3s execution. | Move build, publish, desired-state refresh, rollout, post-deploy validation, and report upload into standard UniDesk CI/CD jobs without replacing HWLAB runtime. |
## DEV CD Transaction
The stable DEV CD side-effect command is:
```sh
node scripts/dev-cd-apply.mjs --apply --confirm-dev --confirmed-non-production --write-report
```
This command is the only formal path that may publish DEV artifacts, refresh
desired-state from the publish report, apply to `hwlab-dev`, and verify public
`16666/16667` in one run. It reads `deploy/deploy.json` at transaction start,
records the manifest hash and target commit, acquires
`Lease/hwlab-dev/hwlab-dev-cd-lock`, runs the internal steps serially, writes
`reports/dev-gate/dev-cd-apply.json`, and releases the Lease.
The Lease is a deployment-plane mutex, not a desired-state source. Its
annotations record at least `promotionCommit`, `deployJsonHash`,
`ownerTaskId`, `transactionId`, `phase`, `startedAt`, `updatedAt`,
`ttlSeconds`, `liveBefore`, and `targetNamespace`. `deploy/deploy.json`,
`deploy/artifact-catalog.dev.json`, and `deploy/k8s/base/workloads.yaml`
remain the only authoritative deploy inputs.
If another transaction holds the Lease, the command must stop before publish or
apply with structured `deploy-lock-held` output that includes holder,
promotion commit, phase, target namespace, and retry seconds. Expired locks are
not silently overwritten; taking over a stale lock requires both
`--break-stale-lock` and `--confirm-dev`, and the previous holder is retained
in audit annotations/report fields.
The old side-effect commands are now internal transaction steps. Direct manual
use of `scripts/dev-artifact-publish.mjs --publish` or
`scripts/dev-deploy-apply.mjs --apply` without `HWLAB_CD_TRANSACTION_ID` is
rejected with `cd-transaction-required`; preflight, build, dry-run, check, and
read-only modes remain available.
## Artifact Publish
DEV artifacts publish to the D601 local/internal registry:
@@ -36,18 +71,22 @@ DEV artifacts publish to the D601 local/internal registry:
127.0.0.1:5000/hwlab/*
```
The stable publish command is:
The single-step publish command is a transaction-internal side-effect step:
```sh
node scripts/dev-artifact-publish.mjs --publish
```
For a single Cloud Web image:
It only runs in side-effect mode when `HWLAB_CD_TRANSACTION_ID` is set by
`scripts/dev-cd-apply.mjs`. Use `node scripts/dev-cd-apply.mjs --apply
--confirm-dev --confirmed-non-production --write-report` for normal DEV CD.
For Cloud Web source freshness before the transaction:
```sh
node web/hwlab-cloud-web/scripts/check.mjs
node web/hwlab-cloud-web/scripts/build.mjs
node scripts/dev-artifact-publish.mjs --publish --services hwlab-cloud-web
node scripts/dev-cd-apply.mjs --apply --confirm-dev --confirmed-non-production --write-report
```
Cloud Web must build `web/hwlab-cloud-web/dist` before publish because the
@@ -130,7 +169,12 @@ services may still use internal `6667`.
## Cloud Web Manual DEV Rollout
The verified manual path for `hwlab-cloud-web` is:
This section is retained as historical operational baseline for what the
transaction reproduces. New DEV side effects should use
`scripts/dev-cd-apply.mjs`; do not bypass the Lease with ad hoc publish,
`kubectl set image`, or restart commands.
The previous verified manual path for `hwlab-cloud-web` was:
```sh
cd /home/ubuntu/workspace/hwlab
@@ -141,6 +185,9 @@ KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n hwlab-dev set image deployment/h
KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n hwlab-dev rollout status deployment/hwlab-cloud-web --timeout=180s
```
That historical sequence is no longer the normal side-effect path; direct
`--publish` is rejected unless it is called by the transaction.
The rollout must use D601 native k3s:
```sh
@@ -171,16 +218,18 @@ scroll, and an internal Markdown help surface. The frontend contract is
## Apply Boundary
`scripts/dev-deploy-apply.mjs` is the DEV-only apply/report path. A real apply
requires explicit non-production flags:
`scripts/dev-deploy-apply.mjs` is the DEV-only apply/report backend. A real
apply requires the transaction environment created by `scripts/dev-cd-apply.mjs`
plus explicit non-production flags:
```sh
node scripts/dev-deploy-apply.mjs --apply --confirm-dev --confirmed-non-production --write-report
```
The apply path must stop before mutation when artifact evidence, registry
digests, kube access, DEV health, or required runtime readiness are missing.
It must not read secret values or target PROD.
Direct manual `--apply` calls without `HWLAB_CD_TRANSACTION_ID` return
`cd-transaction-required`. The apply path must stop before mutation when
artifact evidence, registry digests, kube access, DEV health, or required
runtime readiness are missing. It must not read secret values or target PROD.
Suspended template Jobs are immutable in `spec.template`. Only the explicit
DEV allowlist may be replaced by the apply script:
@@ -220,9 +269,10 @@ use the repo-owned scripts below instead of ad hoc shell fragments.
| Check deployment contract and FRP/endpoint drift | `node scripts/deploy-contract-plan.mjs --check` | Fold into `hwlab deploy check --env dev`. |
| Plan desired image/workload state | `node scripts/deploy-desired-state-plan.mjs --plan --pretty` and `node scripts/deploy-desired-state-plan.mjs --promotion-commit <sha> --check` | Fold into `hwlab deploy plan --env dev --file deploy/deploy.json` with a promotion commit gate. |
| Preflight artifact publish | `node scripts/dev-artifact-publish.mjs --preflight` | Keep as backend for `hwlab artifact publish --preflight`. |
| Publish DEV images | `node scripts/dev-artifact-publish.mjs --publish` | CI job should run this and upload digest reports. |
| Refresh catalog/desired state | `node scripts/refresh-artifact-catalog.mjs --target-ref origin/main --publish-report reports/dev-gate/dev-artifacts.json` | Make refresh an explicit CLI/CD step after publish. |
| Apply DEV rollout | `node scripts/dev-deploy-apply.mjs --apply --confirm-dev --confirmed-non-production --write-report` | Keep apply behind confirmation flags and route through CLI/CD approval. |
| Publish/apply/verify DEV | `node scripts/dev-cd-apply.mjs --apply --confirm-dev --confirmed-non-production --write-report` | Keep as the single side-effect transaction and run from repo-owned DEV CI/CD. |
| Publish DEV images | `node scripts/dev-artifact-publish.mjs --publish` inside `HWLAB_CD_TRANSACTION_ID` | Internal step only; direct side-effect calls are rejected. |
| Refresh catalog/desired state | `node scripts/refresh-artifact-catalog.mjs --target-ref origin/main --publish-report reports/dev-gate/dev-artifacts.json` | Internal transaction step after publish; read/write desired-state only from repo files. |
| Apply DEV rollout | `node scripts/dev-deploy-apply.mjs --apply --confirm-dev --confirmed-non-production --write-report` inside `HWLAB_CD_TRANSACTION_ID` | Internal transaction step; direct side-effect calls are rejected. |
| Roll back DEV Deployment | `kubectl -n hwlab-dev rollout undo deployment/<name>` with explicit D601 kubeconfig | Add `hwlab deploy rollback --env dev --service <id> --to-revision <n>`. |
| Verify status | `curl` checks plus `node scripts/d601-k3s-readonly-observability.mjs` | Add `hwlab deploy verify --env dev --write-report`. |