From bc77ba4c03e1191987792c888e107b7735992b8e Mon Sep 17 00:00:00 2001 From: Codex Date: Sun, 24 May 2026 15:52:50 +0000 Subject: [PATCH] docs: document G14 staging boundary --- AGENTS.md | 2 +- docs/reference/g14.md | 31 ++++++++++++++++++++++++++++--- 2 files changed, 29 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0bad1dfb..b55e7052 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -100,7 +100,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文 - `docs/reference/secretary-reference.md`：秘书日程管理、时间盒、短期待办捕获和 Todo Note / Decision Center 分流规则。 - `docs/reference/code-queue-supervision.md`：Code Queue 居中调度、并发队列拆分、运行中监控、基础设施缺陷分流和验收收口规则。 - `docs/reference/hwlab.md`：HWLAB 指挥侧固定 workspace、D601 原生 k3s 口径、16666/16667 DEV 入口、DEV CD wrapper 和受控发布边界。 -- `docs/reference/g14.md`：G14 provider 节点、k3s 控制桥、迁移后 Code Queue/CI 基础设施目标和节点本地 VPN proxy bootstrap 边界。 +- `docs/reference/g14.md`：G14 provider 节点、k3s 控制桥、HWLAB DEV 旁路 staging、Code Queue/CI 候选目标和节点本地 VPN proxy bootstrap 边界。 - `docs/reference/observability.md`：服务日志、任务活性、通用性能指标 API 和性能面板的可观测性规则。 - `docs/reference/microservices.md`：用户服务（兼容命名 `microservice`）的配置、代理、安全边界、unidesk-direct/k3sctl-managed 部署模式、Todo Note/Baidu Netdisk on main-server、k3s Control/Code Queue/MDTODO/Decision Center/FindJob/Pipeline/MET Nonlinear on D601 和验证规则。 - `docs/reference/windows-passthrough.md`：WSL provider 通过 SSH 透传调用 Windows cmd/PowerShell、Keil、COM 串口和 Windows 侧 skill 的长期规则。 diff --git a/docs/reference/g14.md b/docs/reference/g14.md index 7ba98179..841468ba 100644 --- a/docs/reference/g14.md +++ b/docs/reference/g14.md @@ -1,10 +1,34 @@ # G14 Provider Node -G14 is a UniDesk provider node for migrated infrastructure workloads. Its UniDesk provider id is `G14`; the local UniDesk worktree is `/root/unidesk`, and the native k3s kubeconfig is `/etc/rancher/k3s/k3s.yaml`. +G14 is a UniDesk provider node for staging infrastructure workloads. Its UniDesk provider id is `G14`; the local UniDesk worktree is `/root/unidesk`, and the native k3s kubeconfig is `/etc/rancher/k3s/k3s.yaml`. -G14's long-lived k3s control bridge is `k3sctl-adapter-g14`, a UniDesk direct service outside the k3s fault domain. It listens on the G14 host loopback port `127.0.0.1:4266` and is registered separately from the D601 `k3sctl-adapter`, so G14 infrastructure services can move without taking over user services that still run on D601. +G14's long-lived k3s control bridge is `k3sctl-adapter-g14`, a UniDesk direct service outside the k3s fault domain. It listens on the G14 host loopback port `127.0.0.1:4266` and is registered separately from the D601 `k3sctl-adapter`, so G14 infrastructure services can be built and tested without taking over user services that still run on D601. -For Code Queue and CI/CD migration, G14 uses native k3s labels `unidesk.ai/node-id=G14` and `unidesk.ai/provider-id=G14`. The migrated Code Queue execution plane uses `src/components/microservices/k3sctl-adapter/k3s/code-queue.g14.k8s.yaml` and the managed-service catalog `src/components/microservices/k3sctl-adapter/k3s/code-queue.g14.k3s.json`. +For Code Queue and CI/CD migration preparation, G14 uses native k3s labels `unidesk.ai/node-id=G14` and `unidesk.ai/provider-id=G14`. The G14 Code Queue manifests `src/components/microservices/k3sctl-adapter/k3s/code-queue.g14.k8s.yaml` and `src/components/microservices/k3sctl-adapter/k3s/code-queue.g14.k3s.json` are candidate staging artifacts only until an explicit production cutover is approved. Production Code Queue, CI/CD and user-service execution must remain on D601 while D601 is carrying production. + +## HWLAB DEV Staging + +G14 can host a build-only HWLAB DEV staging cluster in the native k3s namespace `hwlab-dev`. The source checkout is `/root/hwlab`, and images should be built on G14 with the HWLAB repo-owned artifact script in build-only mode, then loaded or pushed to the G14-local registry before applying Kubernetes manifests. + +The G14 HWLAB DEV boundary is: + +- Do not switch public traffic, DNS, FRP, UniDesk microservice routing or Code Queue/CI/CD control from D601 to G14 during staging. +- Keep `hwlab-tunnel-client` scaled to `0` replicas unless a separate cutover approval explicitly enables a public tunnel. +- Keep G14 HWLAB Services as `ClusterIP`; use `kubectl port-forward --address 127.0.0.1` or in-cluster probes for smoke tests. +- Use a G14-local PostgreSQL instance such as `hwlab-g14-postgres` and a G14-local `hwlab-cloud-api-dev-db` Secret for cloud-api durable runtime tests. Do not copy D601 database credentials. +- Use only G14-local placeholder Codex auth for mount/readiness tests unless real Code Agent execution on G14 has been separately authorized; do not copy D601 or production auth material. +- Set `HWLAB_CLOUD_API_PORT=6667` explicitly in the G14 cloud-api Deployment. Kubernetes otherwise injects a `HWLAB_CLOUD_API_PORT=tcp://...` Service environment variable that breaks the Node port parser. +- Override `HWLAB_PUBLIC_ENDPOINT` to a cluster-local G14 endpoint while no public tunnel is active, so staging services do not advertise the D601 production endpoint. + +After the G14-local database is provisioned, run the HWLAB migration CLI only against the G14 DEV database with explicit non-production confirmations: + +```bash +kubectl -n hwlab-dev exec deploy/hwlab-cloud-api -- \ + node /app/cmd/hwlab-cloud-api/migrate.mjs \ + --apply --confirm-dev --confirmed-non-production +``` + +Healthy G14 HWLAB staging means the main Deployments and StatefulSets are Ready, `cloud-api` and `edge-proxy` return `/health/live` with `status=ok`, and `hwlab-tunnel-client` still has `replicas=0` and no Pods. `hwlab-agent-mgr` can report `degraded` while no skills manifest commit/version is wired; treat that as an agent-runtime metadata gap, not as a traffic switch signal. ## Node-Local VPN Proxy @@ -20,6 +44,7 @@ The G14 host persists this proxy configuration in these local files: - `/etc/profile.d/unidesk-g14-proxy.sh` exports `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, lowercase aliases and `NO_PROXY` for new login shells. Set `UNIDESK_G14_DISABLE_PROXY=1` before shell startup to opt out. - `/root/.npmrc` pins npm `proxy`, `https-proxy`, `noproxy` and retry settings for root-side bootstrap commands. - `/root/.gitconfig` pins root Git HTTP/HTTPS proxy settings. +- `/root/.docker/config.json` pins Docker client proxy settings for commands and build contexts that honor Docker client proxy configuration. - `/etc/systemd/system/docker.service.d/proxy.conf` pins Docker daemon pull proxy settings. Updating this drop-in requires `systemctl daemon-reload` and a Docker restart before the active daemon sees the new `NO_PROXY`; do not restart Docker while G14 provider-gateway, k3s bootstrap or image builds are in flight unless that interruption is intentional. The `NO_PROXY` list must include localhost, the main server, private LAN ranges, k3s pod/service CIDRs, Kubernetes service domains and the loopback registry so that k3s, `127.0.0.1:5000`, Kubernetes API access and UniDesk control paths do not route through the VPN proxy.