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

docs: mark g14 as hwlab runtime truth

Browse Source
This commit is contained in:
Codex
2026-05-25 20:18:05 +00:00
parent b71bac57c2
commit cd75bf5b00
3 changed files with 70 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reference/g14.md
+15 -19
View File
@@ -1,40 +1,36 @@
# G14 Provider Node
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 is the current HWLAB DEV/PROD source and k3s/GitOps runtime truth, and it remains a UniDesk provider node for staging other 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 be built and tested without taking over user services that still run on D601.
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.
For Code Queue and non-HWLAB 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. Non-HWLAB production Code Queue, CI/CD and user-service execution must remain on D601 while D601 is carrying those services.
## HWLAB DEV Staging
## HWLAB DEV/PROD Runtime
G14 can host a parallel HWLAB DEV staging cluster in the native k3s namespace `hwlab-dev`. The canonical G14 HWLAB source workspace is `/root/hwlab` on branch `G14`, with `origin` set to `git@github.com:pikasTech/HWLAB.git`; G14 source edits, CI/CD script changes, render work and manual polling must be done from that workspace through UniDesk SSH passthrough. Do not use `/root/HWLAB`, `/home/ubuntu/hwlab`, `/workspace/hwlab` or a master-server checkout as persistent G14 source truth. G14-local details are mirrored on the node in `/root/docs/hwlab-g14-workspace.md`.
G14 hosts the current HWLAB DEV runtime in native k3s namespace `hwlab-dev`, and the same node/GitOps line is the HWLAB PROD target unless a newer HWLAB repo rule says otherwise. The canonical G14 HWLAB source workspace is `/root/hwlab` on branch `G14`, with `origin` set to `git@github.com:pikasTech/HWLAB.git`; HWLAB source edits, CI/CD/GitOps script changes, render work, manual polling and runtime validation must be done from that workspace through UniDesk SSH passthrough. Do not use `/root/HWLAB`, `/home/ubuntu/hwlab`, `/workspace/hwlab`, D601 workspace or a master-server checkout as persistent HWLAB source truth. G14-local details are mirrored on the node in `/root/docs/hwlab-g14-workspace.md`.
The standard entry forms are:
```bash
bun scripts/cli.ts ssh G14 script <<'SCRIPT'
set -eu
cd /root/hwlab
git status --short --branch
SCRIPT
bun scripts/cli.ts ssh G14 apply-patch < patch.diff
bun scripts/cli.ts ssh G14:k3s kubectl get pods -n hwlab-ci
tran G14:/root/hwlab script -- git status --short --branch
tran G14 apply-patch < patch.diff
tran G14:k3s kubectl get pods -n hwlab-dev
```
`G14:k3s` is the only supported k3s route form. Do not use `ssh G14 k3s ...`; the first token must locate the distributed target, and the following tokens must be the operation.
The G14 HWLAB DEV boundary is:
The G14 HWLAB runtime 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.
- Current DEV public endpoints are `http://74.48.78.17:17666/` and `http://74.48.78.17:17667/health/live`. D601 `16666/16667` is legacy/migration evidence only.
- Keep HWLAB Services as `ClusterIP` unless a repo-owned G14 GitOps rule explicitly exposes them. Public exposure should stay in the approved G14 edge/proxy path, not ad hoc NodePort or local port-forward.
- 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.
- Use only G14-local Codex auth material and k8s Secrets authorized for HWLAB on G14; do not copy D601 or production auth material by hand.
- 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.
- `HWLAB_PUBLIC_ENDPOINT` and health/live evidence must describe the G14 endpoint, not the old D601 production endpoint.
- Do not run HWLAB repository `check`, Playwright/browser smoke, image builds or other heavy validation on the master server. Run those through G14 `/root/hwlab`, G14 k3s/Tekton, or another explicitly approved external execution plane.
- Manual device-agent experiments for real hardware must be standalone resources in `hwlab-dev` such as `device-agent-71-freq` and must not patch existing HWLAB Deployments, Services, ArgoCD Applications, FRP, CD desired-state or public frontend routing unless a separate HWLAB change authorizes it.
- A D601 Windows `hwlab-gateway` may connect outbound to G14 DEV cloud-api as an external host bridge for Keil/serial/workspace access. That bridge does not make D601 the HWLAB runtime truth; it is only a hardware access provider behind the G14 device-agent/cloud-api path.
After the G14-local database is provisioned, run the HWLAB migration CLI only against the G14 DEV database with explicit non-production confirmations:
@@ -44,7 +40,7 @@ kubectl -n hwlab-dev exec deploy/hwlab-cloud-api -- \
--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.
Healthy G14 HWLAB runtime means the main Deployments and StatefulSets are Ready, `cloud-api` and `edge-proxy` return `/health/live` with `status=ok`, durable runtime checks pass, and the public G14 DEV endpoints report the expected revision. For a device-agent smoke, health also requires the standalone device-agent Service to answer in-cluster and the D601 Windows gateway session/resource/capability to be visible through G14 cloud-api.
## Node-Local VPN Proxy
docs/reference/hwlab.md
+42 -22
View File
@@ -5,16 +5,13 @@
## 固定入口
- UniDesk 指挥侧 workspace：`/root/unidesk`，固定使用 `master`，开始前执行 `git status` 和 `git pull --ff-only origin master`。
- HWLAB 指挥侧 workspace：`/workspace/hwlab`，固定使用 `main`，开始前执行 `git status` 和 `git pull --ff-only origin main`。
- HWLAB 项目内长期规则入口：`/workspace/hwlab/AGENTS.md`。
- `D601:HWLAB` 固定开发 workspace：通过 `bun scripts/cli.ts ssh D601 script` 进入 `/home/ubuntu/workspace/hwlab-dev`，固定使用 `main` 分支和 `origin git@github.com:pikasTech/HWLAB.git`。所有 D601 侧 HWLAB 代码修改、`node --test`、`web:check`、Playwright/browser smoke、分布式敏捷实验补丁收敛和 PR 前验证都优先在这个目录执行。开始前必须执行 `cd /home/ubuntu/workspace/hwlab-dev && git status --short --branch && git remote -v`，确认分支是 `main...origin/main` 且 remote 正确。
- 开始 `D601:HWLAB` 分布式开发、切换任务、恢复中断或上下文压缩后，必须重新读取 `/home/ubuntu/workspace/hwlab-dev/AGENTS.md`；该文件和 HWLAB repo 内 `docs/reference/` 是代码修改、测试和 PR 的当前约束来源。
- D601 HWLAB 部署/构建/CD 副本：`/home/ubuntu/workspace/hwlab` 只作为部署、构建、CI/CD 或发布读数副本使用，开始前也要 `git -C /home/ubuntu/workspace/hwlab pull --ff-only origin main`；不要把它和 `/home/ubuntu/workspace/hwlab-dev` 的开发职责混用。
- D601 临时目录边界：禁止把 `/tmp/hwlab-*`、`/home/ubuntu/workspace/hwlab-*` 一次性目录、master-server checkout 或其他 runner clone 当作 `D601:HWLAB` source truth。确需一次性 repo 的 CD wrapper 会自行创建并清理；人工开发和测试必须回到 `/home/ubuntu/workspace/hwlab-dev`。
- D601 上 `/home/ubuntu/hwlab` 可能是 runner 或并行任务工作区。指挥官不能把它当作部署真相，也不能清理、reset 或复用其中的 runner worktree。
- `G14:HWLAB` 固定 workspace：只能通过 UniDesk SSH 桥进入 G14 的 `/root/hwlab`，固定使用 `G14` 分支和 `origin git@github.com:pikasTech/HWLAB.git`。每次开始 G14 工作前必须执行 `cd /root/hwlab && git status --short --branch && git remote -v`，期望分支是 `G14...origin/G14`；若不满足，先修正 workspace，不能继续开发、render、polling 或部署。
- 开始 `G14:HWLAB` 分布式开发、切换任务、恢复中断或上下文压缩后，必须重新读取 `/root/hwlab/AGENTS.md`；不能只凭主 server 的压缩上下文继续操作 G14 source workspace。
- G14 k3s 操作必须使用 route 语法 `G14:k3s`，例如 `bun scripts/cli.ts ssh G14:k3s kubectl get pods -n hwlab-ci`；禁止写成 `ssh G14 k3s ...`。`/root/HWLAB`、`/home/ubuntu/hwlab`、`/workspace/hwlab`、D601 workspace、master-server checkout 或临时 clone 都不能作为 `G14:HWLAB` source truth。
- HWLAB 当前主阵地：`G14:HWLAB`，唯一长期 source workspace 是 G14 节点上的 `/root/hwlab`，固定使用 `G14` 分支和 `origin git@github.com:pikasTech/HWLAB.git`。新开发、文档、render、polling、CI/CD、GitOps、DEV/PROD runtime 和验收默认都以这个 workspace 和 G14 k3s 为准。
- HWLAB 项目内长期规则入口：`/root/hwlab/AGENTS.md`。开始 `G14:HWLAB` 分布式开发、切换任务、恢复中断或上下文压缩后，必须重新读取该文件；不能只凭主 server 的压缩上下文继续操作。
- 每次开始 G14 工作前必须通过 UniDesk SSH 桥执行 `cd /root/hwlab && git status --short --branch && git remote -v`，期望分支是 `G14...origin/G14`；若不满足，先修正 workspace，不能继续开发、render、polling 或部署。
- G14 k3s 操作必须使用 route 语法 `G14:k3s`，例如 `tran G14:k3s kubectl get pods -n hwlab-dev`；禁止写成 `ssh G14 k3s ...`。第一个 route token 必须定位分布式目标，后续 token 才是 operation。
- `D601:HWLAB` 已降级为 legacy/migration 对照和 D601 Windows 硬件 bridge 入口，不再是默认开发主阵地或运行面真相。只有用户明确指定 D601 legacy、D601 回滚对照或 D601 Windows/Keil/串口硬件桥接时，才使用 `/home/ubuntu/workspace/hwlab-dev`；进入前仍要执行 `cd /home/ubuntu/workspace/hwlab-dev && git status --short --branch && git remote -v` 并读取该目录的 `AGENTS.md`。
- D601 上 `/home/ubuntu/workspace/hwlab`、`/home/ubuntu/hwlab`、`/tmp/hwlab-*`、`/home/ubuntu/workspace/hwlab-*`、master-server checkout 或其他 runner clone 都不能作为当前 HWLAB source truth。发现 D601 口径与 G14 `/root/hwlab/AGENTS.md` 冲突时，以 G14 当前规则为准。
- `/root/HWLAB`、`/workspace/hwlab`、D601 workspace、master-server checkout 或临时 clone 都不能作为 `G14:HWLAB` source truth。
## 关键 GitHub 入口
@@ -29,31 +26,54 @@
## DEV 入口
- DEV 前端入口固定为 `http://74.48.78.17:16666/`。
- DEV API/live 入口固定为 `http://74.48.78.17:16667/health/live`。
- 当前 G14 DEV 前端入口固定为 `http://74.48.78.17:17666/`。
- 当前 G14 DEV API/live 入口固定为 `http://74.48.78.17:17667/health/live`。
- D601 legacy DEV 前端/API 入口曾使用 `http://74.48.78.17:16666/` 和 `http://74.48.78.17:16667/health/live`；只在显式 D601 legacy 排障或迁移对照时使用，不能作为当前 HWLAB DEV 运行面证据。
- 旧公网 `:6666` 和 `:6667` 不是浏览器验收入口；内部 k3s service 仍可使用 `6667` 作为服务端口。
- `16666` 由 master 侧 `hwlab-frps-dev` 接收 D601 `hwlab-frpc` 的反向代理流量；不要把 master 上的其他 UniDesk frontend/backend-core 路径误判为 HWLAB 前端。
- 当前 G14 入口由 G14 侧公开代理承担；不要把 master 上的其他 UniDesk frontend/backend-core 路径误判为 HWLAB 前端。D601 legacy `16666/16667` 的 FRP 说明只用于历史对照。
## 最小 Device Agent/Gateway 桥接模型
最小打通目标是只新增桥接面，不改动既有 HWLAB 应用、GitOps、FRP、CD 或前端路径：
- 在 `G14:k3s` 的 `hwlab-dev` namespace 手动建立一个 standalone `device-agent-71-freq` Pod/Deployment 和 ClusterIP Service。它暴露设备语义入口，例如 `/health`、`/skills`、`/workspace/*`、`/run`，并把真实硬件调用转成 HWLAB cloud-api 的 gateway operation，而不是在 Pod 内直接访问 Windows 硬件。
- 在 `D601:win` 上启动 `hwlab-gateway`，作为 71-FREQ/ConStart/Keil/串口资源的外部 host bridge。gateway 通过公网或受控网络出站连接当前 G14 DEV cloud-api：`http://74.48.78.17:17667`，注册稳定的 `gatewaySessionId`、`resourceId` 和 `capabilityId`。
- D601 Windows gateway 的最小配置必须来自 profile 或环境变量，核心字段是 `HWLAB_GATEWAY_CLOUD_URL=http://74.48.78.17:17667`、`HWLAB_GATEWAY_ID`、`HWLAB_GATEWAY_SESSION_ID`、`HWLAB_GATEWAY_RESOURCE_ID`、`HWLAB_GATEWAY_CMD_CAPABILITY_ID`、`HWLAB_GATEWAY_CMD_EXEC_ENABLED=1`、`HWLAB_GATEWAY_DEMO_OPEN=1`、`HWLAB_GATEWAY_MAX_INFLIGHT` 和 `HWLAB_GATEWAY_CMD_TIMEOUT_MS`。这些值用于声明能力和执行边界，不得散落在 device-agent 代码里。
- device-agent 访问 G14 集群内 cloud-api 时优先使用 `http://hwlab-cloud-api.hwlab-dev.svc.cluster.local:6667`。Node/undici `fetch` 会按 Fetch bad-port 规则拒绝 `6667`，因此 Node 实现必须使用 `node:http`/`node:https`、已有 repo-owned HTTP helper，或改用不触发 bad-port 的受控代理端口。
- 71-FREQ 的 device profile 必须配置化保存，至少包含工程根目录、Keil project/target、默认串口波特率、gateway/resource/capability 选择器和 workspace 根。不得把 `F:\Work\ConStart`、工程名、串口号或 probe UID 硬编码进 device-agent 镜像。
- 最小验收顺序是：G14 `hwlab-dev` cloud-api `/health/live` ready；D601 Windows 能访问 `http://74.48.78.17:17667/health/live`；D601 `hwlab-gateway` 注册后 cloud-api 能看到 gateway session/resource/capability；G14 `device-agent-71-freq` `/health` 和 `/skills` 返回 ready；通过 device-agent 发起一条只读或 `echo` 级 gateway shell operation，并返回 operation/evidence/trace 摘要。
- 这个模型只证明 `device-agent Pod -> G14 cloud-api -> D601 hwlab-gateway -> Windows host` 的控制链路。Keil 编译下载、串口日志抓取和 workspace CRUD 可以作为后续 device-agent skill 子命令逐步接入；未接入前不能把 device-agent 标成完整 71-FREQ 硬件代理。
## Master Server 校验边界
- master server 是 UniDesk/HWLAB 的生产入口且资源紧张；它只能承担轻量源码编辑、Git 操作、日志/健康观察、JSON CLI 指挥和受控 CD 审阅，不能承担正式校验执行面。
- 禁止在 master server 上运行 HWLAB 或 UniDesk 的仓库级 `check`/`test`/smoke 命令，包括但不限于 `bun scripts/cli.ts check`、`node --test`、`node web/hwlab-cloud-web/scripts/check.mjs`、`node scripts/dev-cloud-workbench-smoke.mjs`、Playwright/browser layout smoke，以及其他会长时间占用 CPU/内存、启动浏览器或遍历大仓库的校验流程。
- 需要正式验证时，固定切到 D601 原生 k3s 侧 worktree、HWLAB repo-owned CI 或其他获批外部执行面；master server 只负责发起、观察和记录，不负责实际跑 check。
- 如果为了排障必须从 master server 生成命令或查看源码，后续验证命令也必须显式改到 D601 路径执行，例如 `/home/ubuntu/workspace/hwlab` 或临时 hotfix worktree，而不是直接在 `/root/unidesk` 或 master server 上本地运行。
- 需要正式验证时，固定切到 G14 `/root/hwlab`、G14 k3s/Tekton、HWLAB repo-owned CI 或其他获批外部执行面；master server 只负责发起、观察和记录，不负责实际跑 check。
- 如果为了排障必须从 master server 生成命令或查看源码，后续验证命令也必须显式改到 G14 路径执行，例如 `tran G14:/root/hwlab script -- ...` 或 `tran G14:k3s ...`，而不是直接在 `/root/unidesk` 或 master server 上本地运行。
## D601 k3s 口径
## G14 运行面与 D601 Legacy 口径
HWLAB 的真实 DEV runtime 在 D601 原生 k3s 中，必须显式使用：
HWLAB 当前真实 DEV/PROD runtime 在 G14 原生 k3s 中。只读观察使用：
```sh
tran G14:k3s kubectl -n hwlab-dev get deploy,svc,pod -o wide
```
`hwlab-cloud-api` 和 `hwlab-edge-proxy` 在集群内使用 `6667` Service 端口，对外 DEV API 使用 `17667`。G14 local details 见 `docs/reference/g14.md` 和 G14 节点 `/root/docs/hwlab-g14-workspace.md`。
D601 原生 k3s 口径只用于 legacy 对照、迁移排障或明确指定的 D601 回滚任务。此时必须显式使用：
```sh
KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n hwlab-dev get deploy,svc,pod -o wide
```
不要直接相信默认 `kubectl` context。D601 上默认 context 可能是 `docker-desktop`，它会展示另一套与公网 `16666/16667` 无关的状态，并可能给出误导性的 `ImagePullBackOff`。
D601 上不要直接相信默认 `kubectl` context。默认 context 可能是 `docker-desktop`，它会展示另一套与公网 legacy `16666/16667` 无关的状态，并可能给出误导性的 `ImagePullBackOff`。
`frpc` 配置不是 D601 host `/etc/frp/frpc.toml`，而是 `hwlab-dev` namespace 里的 `hwlab-frpc-config` ConfigMap 和 `hwlab-frpc` Deployment。master 侧 `frps` 配置由 `hwlab-frps-dev` 容器挂载 `/opt/hwlab-frp/frps.dev.toml`。
历史 D601 `frpc` 配置不是 D601 host `/etc/frp/frpc.toml`，而是 D601 legacy `hwlab-dev` namespace 里的 `hwlab-frpc-config` ConfigMap 和 `hwlab-frpc` Deployment。master 侧 legacy `frps` 配置由 `hwlab-frps-dev` 容器挂载 `/opt/hwlab-frp/frps.dev.toml`。
## UniDesk HWLAB DEV CD Wrapper
## D601 Legacy HWLAB DEV CD Wrapper
以下 UniDesk wrapper 是旧 D601 DEV CD 指挥入口，只用于显式 legacy 诊断和迁移对照。当前 G14 DEV/PROD 发布、GitOps 和运行面收敛必须优先按 G14 `/root/hwlab` 与 HWLAB repo-owned 规则执行；不要把下面的 D601 wrapper 当作当前 HWLAB release truth。
UniDesk 指挥侧固定入口：
@@ -97,9 +117,9 @@ node scripts/dev-cd-apply.mjs --apply --confirm-dev --confirmed-non-production -
- HWLAB runtime truth 必须回写到 HWLAB 仓库自己的 issue、`AGENTS.md`、`docs/reference/`、部署配置或 secret 管理入口；UniDesk 只保留指挥侧边界和交叉引用。
- 热修后必须说明 durable source fix 如何进入 HWLAB 的 CLI、manifest、`deploy/deploy.json` 或等价发布路径；如果尚未完成，要保留 HWLAB issue 追踪。
## 已验证的 Cloud Web 手动 DEV 发布路径
## D601 Legacy Cloud Web 手动 DEV 发布路径
当只需要发布 `hwlab-cloud-web` 到 DEV 时，使用以下路径；它是当前手动 CD 的基准，后续自动化应收敛到 HWLAB `deploy/deploy.json` 和 CLI，而不是重新发明路径。
以下路径是 D601 legacy DEV 的历史手动发布基准，只用于迁移对照或显式 D601 回滚排障。当前 G14 DEV/PROD 发布必须优先按 G14 `/root/hwlab`、G14 GitOps 和 HWLAB repo-owned 规则执行；不要把这里的 D601 命令当作当前发布入口。
1. 更新 D601 部署副本：