fix: stabilize code agent trace and gateway flow

2026-05-24 17:06:22 +00:00
parent b71a3cc89e
commit 9b08caa1a2
22 changed files with 795 additions and 226 deletions
@@ -24,6 +24,41 @@ 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) 保持一致。

+## kubectl 热修命令形状
+
+运行面热修应优先使用小补丁、短连接和远端临时文件，避免把大对象穿过 shell argv、CLI 输出截断或 `kubectl apply` 的 last-applied annotation。
+
+推荐的 ConfigMap data 局部覆盖方式是：在本地生成只包含本次 key 的 merge patch，通过 D601 短连接写入远端临时文件，再让 `kubectl` 从真实文件读取：
+
+```sh
+node - <<'NODE' | bun scripts/cli.ts ssh D601 argv bash -lc '
+set -e
+export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
+kubectl get nodes -o jsonpath="{.items[*].metadata.name}" | grep -w d601 >/dev/null
+patch_file=/tmp/hwlab-hotfix.patch.json
+cat > "$patch_file"
+kubectl -n hwlab-dev patch configmap <hotfix-configmap> --type merge --patch-file "$patch_file"
+rm -f "$patch_file"
+kubectl -n hwlab-dev rollout restart deployment/<deployment>
+kubectl -n hwlab-dev rollout status deployment/<deployment> --timeout=180s
+'
+const fs = require("node:fs");
+process.stdout.write(JSON.stringify({
+  metadata: { annotations: { "hwlab.pikastech.com/hotfix-reason": "<reason>" } },
+  data: { "<key>": fs.readFileSync("<local-file>", "utf8") }
+}));
+NODE
+```
+
+固定避坑规则：
+
+- 不要用 `kubectl patch --patch-file -` 假设 stdin 可用；目标 `kubectl` 版本可能把 `-` 当普通文件名。用 `/tmp/*.patch.json` 再 `--patch-file`。
+- 不要把大 JSON patch 放进 `kubectl patch -p "$patch"` 或 shell argv；ConfigMap 覆盖源码文件时很容易触发 `Argument list too long`。用 stdin 写远端临时文件。
+- 不要对已经很大的 hotfix ConfigMap 使用 `kubectl apply -f -`；`apply` 会尝试写入 `kubectl.kubernetes.io/last-applied-configuration`，可能超过 Kubernetes annotation 256 KiB 限制。局部更新用 `patch --type merge --patch-file`。
+- 不要通过会截断 stdout 的控制 CLI 把 `kubectl get configmap -o json` 回读到本地再 `replace`；大 data 可能被日志/截断污染成非法 JSON。只有在确认完整无截断的原生通道中，才允许对完整对象做 `kubectl replace -f -`。
+- 每次 `rollout restart` 后立即执行 `rollout status`，再用 running pod 做最小只读验证，例如 `node --check`、`grep` marker、`curl` health 或公开入口 trace/result 轮询。
+- 临时补丁文件必须放在远端 `/tmp`，命名包含 hotfix 目标，命令结束后删除；issue 里只记录 ConfigMap 名、key、mountPath、operationId/traceId 和验证方法，不粘贴完整 data。
+
 ## 必须记录

 每次 DEV hotfix 至少记录以下字段，写入 PR/issue/comment，不写入仓库 `reports/**`：