需确认TKE集群Kubernetes版本≥v1.24.0、节点OS为Ubuntu 20.04+/CentOS 8+且内核≥5.4，启用VPC-CNI网络策略，配置CoreDNS支持跨命名空间解析，使用CFS NFS存储类挂载/shared路径，并部署适配LoadBalancer的Control Plane。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您计划在腾讯云容器服务（TKE）环境中部署WorkBuddy集群，但发现Pod启动失败、gRPC连接超时或Skills镜像拉取异常，则可能是由于TKE节点配置未满足WorkBuddy对Kubernetes版本、网络策略或存储插件的特定要求。以下是验证并适配TKE环境的具体步骤：
一、确认TKE集群基础兼容性
TKE需满足WorkBuddy对Kubernetes运行时的最小约束，包括API Server能力、CNI插件行为及节点操作系统内核特性。不满足将导致Control Plane无法注册Worker或etcd状态同步中断。
1、登录TKE控制台，进入目标集群详情页，检查“集群信息”中Kubernetes版本是否为v1.24.0 或更高版本；低于该版本将无法调度StatefulSet类型的Control Plane组件。
2、在“节点池”页面查看节点操作系统，确认所有节点运行Ubuntu 20.04+或CentOS 8+，且内核版本≥5.4；TKE默认的TencentOS Kernel若低于此阈值，需手动升级或切换节点镜像。
3、执行kubectl get nodes -o wide，验证各节点STATUS为Ready且INTERNAL-IP可路由；若显示NotReady或IP为空，说明CNI插件（如VPC-CNI）未正确注入或节点安全组未放行VPC内网通信端口。
二、启用TKE专用网络与服务发现增强
WorkBuddy依赖gRPC长连接与DNS-based服务发现进行Agent协调，TKE默认CoreDNS配置可能无法解析跨命名空间的Service FQDN，导致Claw指令分发失败。
1、在TKE集群“服务管理”中创建ClusterIP类型Service，名称为wb-etcd，选择已有etcd StatefulSet作为后端，并显式设置spec.clusterIP为固定IP（如10.96.100.100）。
2、编辑TKE集群的CoreDNS ConfigMap，于data.Corefile中在kubernetes插件块内追加forward . /etc/resolv.conf，并重启coredns Pod以强制继承宿主机DNS解析路径。
3、为WorkBuddy命名空间启用NetworkPolicy：创建策略允许50051–50053端口从wb-control到所有wb-worker标签Pod的入向流量，禁止外部Namespace访问该端口段。
三、配置TKE CSI存储类对接共享文件系统
WorkBuddy Worker节点需挂载统一的/shared路径用于Skills包分发与沙箱快照持久化，TKE原生CBS存储不支持多写，必须通过NFS或云上CPFS实现跨节点读写一致。
1、在腾讯云文件存储CFS控制台创建通用型NFS v4.1文件系统，绑定至TKE集群所在VPC及可用区，并记录挂载点域名（如10.0.1.100:/）。
使用 draw.io（.drawio 格式）和 SVG 生成兼容 Microsoft Visio 的架构图。当用户需要以下任一场景时触发： - 用于 Visio 或技术文档的架构/系统/网络图 - 带连接标注的分层控制系统图 - 将 draw.io XML 转换为稳定、可嵌入的 SVG - 修复 Visio 或 draw.io 无法打开的故障排查类图表 - 任何需专业级布局且文本可编辑的图表
2、在TKE集群中执行kubectl apply -f cfs-storageclass.yaml，其中storageClassName设为cfs-nfs，provisioner字段填写tke.cloud.tencent.com/cfs，parameters.mountOptions设为nfsvers=4.1,hard,intr,noac。
3、修改WorkBuddy Helm values.yaml，将workerGroup.storage.className设为cfs-nfs，并确保workerGroup.storage.size为20Gi以上，避免Skills解压时触发PVC扩容失败。
四、部署TKE适配版Control Plane
TKE环境禁用部分Kubernetes原生API（如NodePort Service自动分配），Control Plane需绕过默认Service暴露方式，改用Ingress或LoadBalancer直连，否则Claw指令无法抵达调度中枢。
1、下载workbuddy-cluster Helm Chart后，在charts/control-plane/templates/下删除service-nodeport.yaml模板文件，防止Helm渲染出无效资源。
2、在values.yaml中将controlPlane.service.type设为LoadBalancer，并指定controlPlane.service.annotations为{"service.kubernetes.io/qcloud-loadbalancer-internal": "true"}，确保CLB仅限VPC内访问。
3、执行helm install wb-control -n workbuddy-system ./workbuddy-cluster --set controlPlane.tls.enabled=false --set controlPlane.service.loadBalancerIP="10.0.1.200"（该IP需预先在TKE CLB控制台申请并绑定）。
五、验证TKE Worker节点技能加载与执行链路
Worker节点需能独立拉取Skills镜像、挂载NFS卷、加载本地模型权重并响应Control Plane下发的gRPC任务帧；任一环节阻塞将导致任务卡在“Pending”状态。
1、在TKE节点上执行curl -s https://hub.codebuddy.cn/skills/v2/ | jq '.status'，确认返回"success"；若报403，需在TKE集群“密钥管理”中创建docker-registry Secret并绑定至workbuddy-system Namespace。
2、部署测试Worker Pod：kubectl run skill-test --image=codebuddy/skill-base:1.8.0 --rm -it --overrides='{"spec":{"volumes":[{"name":"shared","nfs":{"server":"10.0.1.100","path":"/"}}],"containers":[{"name":"test","volumeMounts":[{"name":"shared","mountPath":"/data/workbuddy/shared"}]}]}}' -- sh -c "ls -l /data/workbuddy/shared && exit 0"
3、观察Pod日志是否输出Skills目录列表且无Permission denied错误；若出现stale file handle，说明NFS挂载参数未启用noac或TKE节点内核缺少nfs4_disable_idmapping=1内核参数。
