从本地演示到镜像、Helm 和部署恢复

Mac 单进程演示检验控制算法、HTTP/SSE 和审批重放；Kind 在 Linux 虚拟机容器内提供真正的 apiserver、scheduler、kubelet，可检验控制器权限、Pod 生命周期和服务发现；真实 NVIDIA 节点才可检验 CUDA、设备分配、KV 内存和 token 性能。三个实验回答不同问题，不能互相代用。

npm ci
npm run docs:dev
./scripts/start.sh
# 另一个终端
(cd modeldock && go test -race ./...)
.venv/bin/python -m unittest discover -s opspilot/tests -v
.venv/bin/python scripts/smoke.py

Python 锁文件用于可重复安装。CLI 与 API 都要从项目根目录启动，避免 SQLite 相对路径指向两份库。Go 进阶 Operator 与数据库实验有独立 go.mod，不能只跑顶层 go test 就认为全部编译过。

安装 Go 1.26、kubectl、Docker Desktop、kind、helm、uv；先确认 docker info 可用。本工作区已部署的集群名为 handbook-lab。如果它已存在，跳过 create。只对专用实验集群执行：

mkdir -p tmp
export KUBECONFIG="$PWD/tmp/handbook.kubeconfig"
kind create cluster --name handbook-lab --kubeconfig "$KUBECONFIG"
./scripts/kind-mock.sh
./scripts/kind-control.sh
kubectl create namespace modeldock-lab --dry-run=client -o yaml | kubectl apply -f -
kubectl apply -f k8s/crd.yaml
kubectl wait --for=condition=Established crd/modelservices.lab.modeldock.dev
helm upgrade --install handbook deploy/chart -n modeldock-lab --wait
kubectl -n modeldock-lab wait msvc/chart-demo --for=jsonpath='{.status.phase}'=Running --timeout=90s

脚本在 Mac 交叉编译 Linux 二进制，将 scratch 镜像直接载入 Kind 节点；无需每次从公共仓库拉基础镜像。CI 也可用 modeldock/Dockerfile 多阶段构建 CPU runtime。Chart 默认不启用网关：要先在专属 namespace 创建 Secret，键 TENANT_KEYS_JSON 的值为包含租户 Token 和允许模型列表的 JSON，然后显式启用。

# tenant.env 由你本机生成并保密；示例格式：TENANT_KEYS_JSON={"team-a":{"Token":"随机长密钥","Models":["chart-demo"]}}
kubectl -n modeldock-lab create secret generic handbook-gateway --from-env-file=tmp/tenant.env
helm upgrade handbook deploy/chart -n modeldock-lab --set gatewaySecret=handbook-gateway --wait
kubectl -n modeldock-lab port-forward svc/modeldock-gateway 18188:8080

部署后查 EndpointSlice、网关 /ready、正确 Token 的 SSE、错误 Token 的 401、租户外模型的 403。容器运行于 ClusterIP；不要直接暴露 cluster-admin、etcd 或 MCP stdio 工具。生产入口应通过 Ingress/Gateway 终结 TLS，授权后访问推理路径；若用 Cloudflare Tunnel，只路由经过认证的应用入口，不代理 kubectl 管理端口。验证长连接时用 curl -N 观察帧间隔，同时检查反代缓冲、idle timeout 与客户端取消是否释放上游。

进阶 Vue 控制台：运行 npm run console:dev 打开本地 5180。开发代理将 /inference 转发到 18188、/diagnostics 转到 18190。npm run console:build 输出 console/dist。若独立部署该静态目录，用 VITE_GATEWAY_BASE 与 VITE_OPS_BASE 指定经过认证的 HTTPS API；最好同源转发，跨源时仅允许控制台的确切 Origin、Authorization 和必要方法，不能把凭证写入 VITE_ 环境变量。

构建产物与运行凭证分开

Go 的三个模块单独编译测试；CPU 模型镜像面向 Kind 节点的 Linux 架构，不能复制一个 darwin 可执行文件进容器。Chart 将镜像与 Secret 引用分开；RBAC 只授权目标 namespace 和所需动词。CI 的工程工作流为 MySQL、Redis 临时创建服务，envtest 单独启动 API Server。但仓库里有工作流不等于你自己的 GitHub Actions 已经跑过。

helm lint deploy/chart
helm template handbook deploy/chart -n modeldock-lab > /tmp/cloudlab-render.yaml
kubectl apply --dry-run=server -n modeldock-lab -f /tmp/cloudlab-render.yaml
rm /tmp/cloudlab-render.yaml

发布窗口中的失败。 先区分未就绪和未授权的 401/403，再查端点快照。回滚镜像不回滚数据库 schema；先做兼容性变更，再发布新二进制，否则 helm rollback 仍然不能恢复服务。详细的跨系统验证和收尾见端到端验收。