Lyon
107 lines
7.0 KiB
Markdown
107 lines
7.0 KiB
Markdown
# HWLAB DEV Runtime Hotfix Runbook
|
||
|
||
本文定义 `hwlab-dev` 运行态热修的最低边界、审计字段、只读确认和回滚口径。它只适用于 DEV 能力边界或阻塞排障，不是发布验收手册，也不把运行态覆盖当作源码真相。
|
||
|
||
本规则承接 [pikasTech/HWLAB#462](https://github.com/pikasTech/HWLAB/issues/462) 和 [pikasTech/HWLAB#465](https://github.com/pikasTech/HWLAB/issues/465)，服务 [pikasTech/HWLAB#7](https://github.com/pikasTech/HWLAB/issues/7) / [pikasTech/HWLAB#239](https://github.com/pikasTech/HWLAB/issues/239) 的“用户工作台 + Code Agent 真实可用”主线。它不改变 `DC-DCSN-P0-2026-003` / [pikasTech/HWLAB#78](https://github.com/pikasTech/HWLAB/issues/78) 的 M3 上位约束：hotfix runbook、审计输出、SOURCE、LOCAL、DRY-RUN 或只读观察都不能被包装成 M3 DEV-LIVE 通过。
|
||
|
||
## 允许条件
|
||
|
||
DEV runtime hotfix 只能在以下条件同时满足时使用：
|
||
|
||
- 目标是 `hwlab-dev`，不是 PROD、真实用户生产面或真实硬件生产控制面。
|
||
- 目的是打通能力边界、定位阻塞层或恢复用户工作台关键路径；不能为了绕过源码、测试、artifact 或 CD 流程而热修。
|
||
- 操作前已经明确该任务不会抢占 M3 虚拟硬件可信闭环主线，也不会把热修证据升级成 M3 验收。
|
||
- 操作后必须创建或关联源码化 follow-up。#465 的持久化拆分是固定分工：#460 负责 Code Agent -> PC gateway `shell.exec` 能力路由，#461 负责 hotfix runner 源码化，#462 负责本 runbook 与只读审计，#463 负责 JSON-RPC `serviceId` 结构化诊断，#464 负责 DEV-LIVE smoke/harness。
|
||
|
||
## D601 k3s 前置
|
||
|
||
D601 裸 `kubectl` 不可信。所有只读观测、热修、回滚和复核都必须显式指定原生 k3s kubeconfig，并先确认节点：
|
||
|
||
```sh
|
||
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
|
||
kubectl get nodes -o jsonpath='{.items[*].metadata.name}'
|
||
```
|
||
|
||
结果必须包含 `d601`。出现 `docker-desktop`、`desktop-control-plane`、`127.0.0.1:11700` 或第二套 `hwlab-dev` 控制面时，停止 hotfix、回滚和验收判断。此边界与 [dev-runtime-boundary.md](dev-runtime-boundary.md) 和 [deployment-publish.md](deployment-publish.md) 保持一致。
|
||
|
||
## 必须记录
|
||
|
||
每次 DEV hotfix 至少记录以下字段，写入 PR/issue/comment，不写入仓库 `reports/**`：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| Deployment | namespace、name、generation、template annotation、容器 image。 |
|
||
| Pod | 新旧 pod 名、phase、node、用于验证的 running pod。 |
|
||
| ConfigMap | 名称、key 名、用途；不得把 data 全量贴入 issue。 |
|
||
| annotation | 记录热修来源和目的的 Deployment template annotation。 |
|
||
| mount/subPath | volume 名、ConfigMap 名、mountPath、subPath、readOnly。 |
|
||
| traceId / operationId | 能力验证请求的 trace 与 operation 标识。 |
|
||
| 验证命令 | `grep` marker、`node --check`、API 返回字段等只读或最小验证命令。 |
|
||
| 回滚方式 | 移除 volume/mount/annotation 的方法，或用源码 artifact/CD 覆盖的方法。 |
|
||
| 源码化 follow-up | 关联 issue/PR，说明热修不会作为长期 runtime truth。 |
|
||
|
||
#465 的典型对象是：
|
||
|
||
| 项 | 值 |
|
||
| --- | --- |
|
||
| Deployment | `hwlab-dev/hwlab-cloud-api` |
|
||
| ConfigMap | `hwlab-cloud-api-code-agent-hotfix` |
|
||
| 覆盖文件 | `/app/internal/cloud/code-agent-chat.mjs` |
|
||
| subPath | `code-agent-chat.mjs` |
|
||
| marker | `runtime-hotfix-pc-gateway-shell` |
|
||
| annotation | `hwlab.pikastech.local/pc-gateway-shell-hotfix` |
|
||
| 能力路径 | `/v1/agent/chat -> /v1/rpc/hardware.invoke.shell -> PC gateway -> Windows cmd` |
|
||
|
||
## 只读审计入口
|
||
|
||
仓库内只读入口是：
|
||
|
||
```sh
|
||
node scripts/dev-runtime-hotfix-audit.mjs --pretty
|
||
node scripts/dev-runtime-hotfix-audit.mjs --collect-readonly --pretty
|
||
```
|
||
|
||
默认 `--plan` 模式只输出 compact JSON 计划，不执行 `kubectl`。`--collect-readonly` 只允许 `kubectl get` 和 `kubectl exec` 形态的读检查，用于判断当前 DEV 是否仍被 hotfix 覆盖；它不会执行 `apply`、`patch`、`rollout`、`restart`、`delete`、`create`、`set image`，也不会读取 Secret resources 或 secret values。
|
||
|
||
输出分类固定包含以下语义：
|
||
|
||
| 分类 | 含义 |
|
||
| --- | --- |
|
||
| `hotfix-configmap-present` | 目标 ConfigMap 仍存在。 |
|
||
| `deployment-mounts-hotfix` | Deployment template 仍通过 volumeMount/subPath 覆盖目标文件。 |
|
||
| `pod-loads-hotfix-marker` | running pod 内目标文件仍包含 hotfix marker。 |
|
||
| `source-artifact-expected` | 正式收口应回到 source/PR/artifact/CD。 |
|
||
| `rollback-required` | 当前仍检测到热修残留或覆盖，不能把运行态当源码真相。 |
|
||
| `no-hotfix-detected` | 只读审计未发现该 hotfix ConfigMap 或 mount 覆盖。 |
|
||
| `unknown-needs-manual-readonly-check` | 无法确认节点、对象或 pod 状态，需要人工继续只读核对。 |
|
||
|
||
## 回滚口径
|
||
|
||
优先回滚方式是用源码化 artifact/CD 覆盖 runtime hotfix：#460/#461 合并并发布后，Deployment 应消费正式镜像，不再通过 ConfigMap 覆盖 `/app/internal/cloud/code-agent-chat.mjs`。只读确认口径是：
|
||
|
||
```sh
|
||
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
|
||
kubectl get nodes -o jsonpath='{.items[*].metadata.name}'
|
||
kubectl -n hwlab-dev get deployment hwlab-cloud-api -o json
|
||
kubectl -n hwlab-dev get configmap hwlab-cloud-api-code-agent-hotfix -o json
|
||
node scripts/dev-runtime-hotfix-audit.mjs --collect-readonly --pretty
|
||
```
|
||
|
||
如果必须直接移除运行态覆盖，授权操作者应先从 `kubectl -n hwlab-dev get deployment hwlab-cloud-api -o json` 中定位精确 indexes，再移除：
|
||
|
||
- 指向 hotfix ConfigMap 的 `spec.template.spec.volumes[]`；
|
||
- 指向 `/app/internal/cloud/code-agent-chat.mjs` 的 `containers[].volumeMounts[]`；
|
||
- `hwlab.pikastech.local/pc-gateway-shell-hotfix` 等 hotfix annotation；
|
||
- 不再需要的 `hwlab-cloud-api-code-agent-hotfix` ConfigMap。
|
||
|
||
直接 `kubectl patch`、`kubectl delete configmap`、`kubectl rollout status` 或等价写操作必须由明确授权的 DEV 操作者执行，并且仍要使用 `KUBECONFIG=/etc/rancher/k3s/k3s.yaml` 与节点 `d601` 确认。本 runbook 的审计脚本不执行这些写操作。回滚后再次运行 `scripts/dev-runtime-hotfix-audit.mjs --collect-readonly`，期望分类包含 `no-hotfix-detected`，且不包含 `deployment-mounts-hotfix`、`pod-loads-hotfix-marker` 或 `rollback-required`。
|
||
|
||
## 禁止误用
|
||
|
||
- 不得把 ConfigMap/pod 覆盖当作 source truth；正式修复必须回到 source、PR、artifact 和 repo-owned CD。
|
||
- 不得把 #462 runbook 或只读审计包装成 #460/#461 源码化完成。
|
||
- 不得把 #462 runbook 或只读审计包装成 #464 DEV-LIVE smoke/harness 完成。
|
||
- 不得把热修期间的 stdout、trace 或 operation 扩大为 M3 trusted evidence；M3 判定仍按 [m3-loop-rollout-runbook.md](m3-loop-rollout-runbook.md)。
|
||
- 不得读取或打印 Secret value、kubeconfig token、DB URL 密码、provider token。
|
||
- 不得新增或修改仓库 `reports/**`；过程证据写入 PR/issue/comment，临时 JSON 只能放 `/tmp`、`.state` 或 CI artifact。
|