ClawManager 多节点 Kubernetes 集群部署指南结合 Longhorn 持久存储从零到一的完整实战【免费下载链接】ClawManagerA Kubernetes-native control plane for AI agent instance management, with governed AI access, runtime orchestration, and reusable resources across multiple agent runtimes.项目地址: https://gitcode.com/gh_mirrors/cl/ClawManagerClawManager 是一个 Kubernetes 原生的 AI 智能体实例管理控制平面提供受治理的 AI 访问、运行时编排和跨运行时可复用资源。本文将带你完成 ClawManager 多节点 Kubernetes 集群部署用一份内置 Longhorn 的官方清单从零搭出带持久存储的 AI 智能体管理平台全程附命令与排错要点新手也能照做。为什么多节点部署必须用 RWX 共享存储单节点部署靠本地磁盘HostPath就能跑但一旦集群扩到 3 台以上机器有一个绕不开的问题控制面组件MySQL、Redis、MinIO只需要ReadWriteOnceRWO任意一个节点的磁盘即可智能体工作区clawmanager-workspaces却被clawmanager-app、openclaw-runtime、hermes-runtime、opencode-runtime等多个 Deployment 同时挂载Pod 可能被调度到任何节点——这必须用ReadWriteManyRWX跨节点共享卷。⚠️ 官方明确不支持的伪多节点方案多节点 HostPath、用local-path等节点本地存储冒充 RWX、把集群内部 Service DNS 当 NFS 服务端、把持久数据放进emptyDir。官方验证路径选择了Longhorn作为示例 CSIlonghorn提供 RWO 卷longhorn-rwx提供基于 NFSv4 的 RWX 卷。这两个名字只是示例换成 Ceph、EFS 等同等能力的 StorageClass 完全没问题见 docs/deployment.md。集群架构一图看懂整份集群清单deployments/k8s/cluster/clawmanager.yaml一次部署出这些组件组件角色持久化clawmanager-app前端 后端 API 控制平面RWX 工作区卷mysql应用状态数据库RWO5 GiBredis会话 / Team 协作消息总线RWO1 GiBminio对象存储技能包等资源RWO10 GiBskill-scanner技能安全扫描—*-runtime各类 AI 智能体运行时池RWX 工作区卷Longhorn v1.12.0分布式块存储 RWX自身副本数据四个 PVC 的定义在清单的 clawmanager.yaml 中部署后在clawmanager-system命名空间生效。准备工作节点检查与依赖安装1. 确认节点健康kubectl config current-context kubectl get nodes -o wide所有可能跑工作负载的节点都必须是Ready。Longhorn 不会在不健康的集群上稳定工作先修好节点再安装。2. 每个节点安装存储客户端Longhorn 用 iSCSI 做块卷、NFS 做 RWX 卷因此每台工作节点都要装对应客户端# Ubuntu / Debian apt-get update apt-get install -y open-iscsi nfs-common cryptsetup dmsetup systemctl enable --now iscsid || systemctl enable --now open-iscsi # RHEL / Rocky / Alma yum install -y iscsi-initiator-utils nfs-utils cryptsetup device-mapper systemctl enable --now iscsid逐台自检command -v iscsiadm command -v mount.nfs command -v mount.nfs4 systemctl is-active iscsid || systemctl is-active open-iscsi如果mount.nfs4缺失clawmanager-workspaces的 Pod 会一直卡在ContainerCreating事件里会出现bad option; you might need a /sbin/mount.type helper program——这是新手最容易踩的坑。3. 处理 multipathd 干扰systemctl is-active multipathd || true multipath -t 2/dev/null | grep -F devnode ^sd[a-z0-9] || true期望multipathd未运行或黑名单里包含devnode ^sd[a-z0-9]。都不满足时禁用它或按 README 添加黑名单后重启。漏掉这一步的典型症状是Waiting for volume share to be available。4. 检查跨节点 Pod 网络先查是否存在重复 Pod IP有输出就说明 CNI 有问题必须先修kubectl get pods -A \ -o custom-columnsIP:.status.podIP,NS:.metadata.namespace,NAME:.metadata.name,NODE:.spec.nodeName \ --no-headers \ | awk $1 ! none { count[$1] } END { for (ip in count) if (count[ip] 1) print ip }无输出才继续下一步。5. 副本数与存储节点数对齐清单默认numberOfReplicas: 3定义见 clawmanager.yaml。只有 3 台及以上节点可用时才保持默认2 节点测试集群请先改为 2sed -i.bak s/numberOfReplicas: 3/numberOfReplicas: 2/g clawmanager.yaml否则卷会长期处于degraded降级状态。一键部署应用清单并等待组件就绪确认清单中的镜像所有节点都能拉取后离线环境请预先导入私有仓库执行kubectl apply -f deployments/k8s/cluster/clawmanager.yaml然后分三段验证。① Longhorn 存储层kubectl -n longhorn-system rollout status daemonset/longhorn-manager --timeout10m kubectl -n longhorn-system rollout status deployment/longhorn-driver-deployer --timeout10m kubectl -n longhorn-system rollout status daemonset/longhorn-csi-plugin --timeout10m kubectl get sc longhorn longhorn-rwx期望longhorn-manager与longhorn-csi-plugin在所有节点就绪两个 StorageClass 都存在。② ClawManager 工作负载kubectl -n clawmanager-system get pvc kubectl -n clawmanager-system rollout status deployment/clawmanager-app --timeout15m kubectl -n clawmanager-system get deploy,pod,pvc -o wide期望所有 PVC 为Boundclawmanager-app、openclaw-runtime、hermes-runtime、opencode-runtime及 MySQL、Redis、MinIO、skill-scannerPod 全部 Running。③ Longhorn 卷健康kubectl -n longhorn-system get volumes.longhorn.io \ -o custom-columnsNAME:.metadata.name,STATE:.status.state,ROBUSTNESS:.status.robustness,REPLICAS:.spec.numberOfReplicas,SHARESTATE:.status.shareState期望所有卷healthy工作区 RWX 卷额外应显示SHARESTATE: running和 NFS 端点share-manager正常启动的标志。访问 Web 控制台并验收部署集群清单把前端暴露为 HTTPS NodePortclawmanager.yamlkubectl get svc -n clawmanager-system # 看到 clawmanager-frontend 443:30443/TCP浏览器访问https://任意节点IP:30443。首次是自签名证书点高级 → 继续访问即可然后用默认管理员账号登录建议登录后立即改密码 用户名admin 密码admin123登录后Console 仪表盘会直接显示多节点容量视图——节点数、CPU/内存/磁盘分配一目了然这是验收多节点生效最直观的界面用户侧的 Desktop Portal 则直接呈现创建在共享工作区上的智能体实例OpenClaw / Hermes 运行时最后可以走一遍创建 AI 网关模型 → 创建实例的完整链路流程见 docs/use_guide_cn.md确认 RWX 工作区卷在运行时 Pod 中确实可用。常见问题速查表症状原因处理ImagePullBackOff节点拉不到镜像kubectl describe pod找到失败镜像检查节点仓库访问离线环境预导入PVC 一直PendingStorageClass / CSI 未就绪kubectl get sc、kubectl -n clawmanager-system describe pvc 名看事件Pod 卡ContainerCreating提示 mount helper 缺失节点没装 NFS 客户端补装nfs-common/nfs-utils后重启 PodRWX 卷卡在shareState: startingNFS 客户端缺失、multipathd干扰或跨节点网络不通查share-manager日志kubectl -n longhorn-system logs share-manager-pod卷degraded副本数 可用存储节点数下调numberOfReplicas或扩容节点longhorn-driver-deployerCrashLoop重复 Pod IP / 跨节点网络故障回到准备工作第 4 步排查 CNI遇到拿不准的排障细节按编号对照 deployments/k8s/cluster/README.md 的 Install 章节即可每一步都给了检查命令和期望输出。换成自己的存储只改 6 个环境变量longhorn/longhorn-rwx不是硬绑定。换成 Ceph、EFS 等存储时改clawmanager-appDeployment 的这几个环境变量默认值见 clawmanager.yaml变量默认值说明CLAWMANAGER_STORAGE_PROFILEcluster声明多节点 CSI 模式K8S_HOSTPATH_FALLBACK_ENABLEDfalse禁止悄悄退回 HostPathK8S_PVC_BIND_TIMEOUT2mPVC 绑定等待上限K8S_CONTROL_PLANE_STORAGE_CLASSlonghorn控制面 RWO 卷的 StorageClassK8S_INSTANCE_STORAGE_CLASSlonghorn实例 RWO 卷的 StorageClassK8S_WORKSPACE_STORAGE_CLASSlonghorn-rwx工作区 RWX 卷的 StorageClass同时把清单中 4 个 PVC 的storageClassName改为你的类名并确认K8S_WORKSPACE_ACCESS_MODEReadWriteMany与新存储的访问模式一致。更多运维细节归档大小限制CLAWMANAGER_WORKSPACE_ARCHIVE_MAX_MIB、上报问题前要收集的命令清单等都在 docs/deployment.md。干净卸载顺序不能反测试环境要拆除时必须让 Longhorn 卸载 Job 先于整体清单执行# 1. 先删 ClawManager 工作负载 kubectl delete namespace clawmanager-user-1 clawmanager-system --ignore-not-found # 2. 解锁 Longhorn 删除确认 kubectl -n longhorn-system patch settings.longhorn.io deleting-confirmation-flag \ --typemerge -p {value:true} # 3. 运行官方卸载 Job kubectl create -f deployments/k8s/cluster/uninstall.yaml kubectl wait --forconditioncomplete job/longhorn-uninstall -n longhorn-system --timeout10m # 4. 最后才删除一键清单 kubectl delete -f deployments/k8s/cluster/clawmanager.yaml --ignore-not-found如果之前误删了整体清单导致卸载卡住README 的 Recovery 章节给出了清理残留 webhook 与 CRD 的完整方法。总结回顾这条从零到一的路径节点先行——Ready 节点 iSCSI/NFS 客户端 干净的 Pod 网络占掉了 90% 的坑一键清单——Longhorn 与 ClawManager 同文件部署RWO 与 RWX 分工明确三段验证——Longhorn 就绪 → PVCBound→ 卷healthy且 RWX 卷shareState: running控制台验收——:30443登录后核对多节点容量视图跑通第一个智能体实例。按这套流程走完你就拥有了一个存储可迁移、实例可恢复、AI 访问受治理的多节点 ClawManager 集群。想进一步探索 k3s 路径、单节点 HostPath 方案或端到端验收用例可以继续看 docs/deployment.md、deployments/k3s/cluster/clawmanager.yaml 与 e2e/README.md。【免费下载链接】ClawManagerA Kubernetes-native control plane for AI agent instance management, with governed AI access, runtime orchestration, and reusable resources across multiple agent runtimes.项目地址: https://gitcode.com/gh_mirrors/cl/ClawManager创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考