fix: guard D601 k3s control plane

2026-05-23 12:57:23 +00:00
parent a20d041c23
commit 6c44f66289
9 changed files with 47 additions and 8 deletions
@@ -4,6 +4,18 @@ UniDesk deployment is driven by a desired-state manifest. The manifest answers o

 Persistent D601 dev environment rules, including the public dev frontend port, `deploy apply --env dev` service scope and Rust backend-core build boundary, are owned by `docs/reference/dev-environment.md`. Release-line governance, CI/CD runtime pinning and the `release/v1` transition policy are owned by `docs/reference/release-governance.md` and [GitHub issue #6](https://github.com/pikasTech/unidesk/issues/6). This document owns the generic desired-state reconciler and target-side build contract.

+## D601 Native k3s Emergency Guard
+
+D601 曾同时存在 Docker Desktop Kubernetes 与自部署 k3s，并已造成 `hwlab-dev`、Code Queue 和 CI/CD 观测路径混淆；证据与治理跟踪见 [GitHub issue #138](https://github.com/pikasTech/unidesk/issues/138)，2026-05-23 热修复背景见 [GitHub issue #118](https://github.com/pikasTech/unidesk/issues/118)。Docker Desktop Kubernetes 已由用户停用并清理数据，后续不得重新启用或作为部署目标。
+
+任何 D601 Kubernetes 部署、dry-run、Tekton、Code Queue、HWLAB/UniDesk DEV 排障和人工 `kubectl` 验证都必须先显式绑定原生 k3s：
+
+```sh
+KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl get nodes -o jsonpath='{.items[*].metadata.name}'
+```
+
+结果必须包含 `d601`。裸 `kubectl`、`docker-desktop` context、`desktop-control-plane` 节点或 `127.0.0.1:11700` server 都不是 UniDesk k3s 证据；出现这些信号时必须停止写操作并修复 kubeconfig/脚本入口。Docker daemon 仍可用于镜像构建、registry 或直管服务，但 Docker Desktop Kubernetes 不得与原生 k3s 共同承载 `unidesk*`、`hwlab-dev` 或 Code Queue 资源。
+
 ## Manifest

 The root `deploy.json` is the single desired-state source for both prod and dev. Environment branches such as `deploy/dev` and `deploy/prod` are deprecated because they create a second control plane for version intent.
@@ -73,7 +85,7 @@ It may create resources only in `unidesk-dev`:
 - `StatefulSet/Service postgres-dev` with a 5Gi persistent volume claim and bounded CPU/memory requests/limits.
 - `Job unidesk-dev-db-migrate`, which waits for `postgres-dev`, runs the guard, then prepares backend-core and Code Queue tables in the independent `unidesk_dev` database.

-The manifest must not create, update, or delete production namespace resources, production DB objects, production PVCs, production Deployments/Services/Secrets, or main server Docker Compose services. Static validation is available through `bun scripts/cli.ts dev-env validate`; Kubernetes client dry-run is `bun scripts/cli.ts dev-env validate --kubectl-dry-run`. If applying manually during Phase 2, the only allowed apply target is this manifest and the post-check must prove production resources are unchanged, for example by comparing `kubectl -n unidesk get deploy,sts,svc,secret,pvc -o name` before and after.
+The manifest must not create, update, or delete production namespace resources, production DB objects, production PVCs, production Deployments/Services/Secrets, or main server Docker Compose services. Static validation is available through `bun scripts/cli.ts dev-env validate`; Kubernetes client dry-run is `bun scripts/cli.ts dev-env validate --kubectl-dry-run`. If applying manually during Phase 2, the only allowed apply target is this manifest and the post-check must prove production resources are unchanged, for example by comparing `KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n unidesk get deploy,sts,svc,secret,pvc -o name` before and after.

 Before applying the foundation on a fresh D601 native k3s runtime, run `bun scripts/cli.ts dev-env prewarm-images` and wait for the returned job to succeed. This imports the foundation images `postgres:16-alpine` and `rancher/mirrored-library-busybox:1.36.1` from Docker into `/run/k3s/containerd/containerd.sock`; k3s/containerd must not depend on live Docker Hub pulls during rollout. If this step is skipped, `postgres-dev` or the local-path helper pod can remain `ImagePullBackOff`, leaving the PVC pending even though the manifest is valid.