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/ClawManager
ClawManager 是一个 Kubernetes 原生的 AI 智能体实例管理控制平面，提供受治理的 AI 访问、运行时编排和跨运行时可复用资源。本文将带你完成 ClawManager 多节点 Kubernetes 集群部署：用一份内置 Longhorn 的官方清单，从零搭出带持久存储的 AI 智能体管理平台，全程附命令与排错要点，新手也能照做。
为什么多节点部署必须用 RWX 共享存储？
单节点部署靠本地磁盘（HostPath）就能跑，但一旦集群扩到 3 台以上机器，有一个绕不开的问题：
- 控制面组件（MySQL、Redis、MinIO）只需要
ReadWriteOnce（RWO），任意一个节点的磁盘即可； - 智能体工作区（
clawmanager-workspaces）却被clawmanager-app、openclaw-runtime、hermes-runtime、opencode-runtime等多个 Deployment 同时挂载，Pod 可能被调度到任何节点——这必须用ReadWriteMany（RWX）跨节点共享卷。
⚠️ 官方明确不支持的"伪多节点"方案：多节点 HostPath、用
local-path等节点本地存储冒充 RWX、把集群内部 Service DNS 当 NFS 服务端、把持久数据放进emptyDir。
官方验证路径选择了Longhorn作为示例 CSI：longhorn提供 RWO 卷，longhorn-rwx提供基于 NFSv4 的 RWX 卷。这两个名字只是示例，换成 Ceph、EFS 等同等能力的 StorageClass 完全没问题（见 docs/deployment.md）。
集群架构一图看懂
整份集群清单（deployments/k8s/cluster/clawmanager.yaml）一次部署出这些组件：
| 组件 | 角色 | 持久化 |
|---|---|---|
clawmanager-app | 前端 + 后端 API 控制平面 | RWX 工作区卷 |
mysql | 应用状态数据库 | RWO，5 GiB |
redis | 会话 / Team 协作消息总线 | RWO，1 GiB |
minio | 对象存储（技能包等资源） | RWO，10 GiB |
skill-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-columns=IP:.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 节点测试集群请先改为 2：
sed -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 --timeout=10m kubectl -n longhorn-system rollout status deployment/longhorn-driver-deployer --timeout=10m kubectl -n longhorn-system rollout status daemonset/longhorn-csi-plugin --timeout=10m 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 --timeout=15m kubectl -n clawmanager-system get deploy,pod,pvc -o wide期望：所有 PVC 为Bound，clawmanager-app、openclaw-runtime、hermes-runtime、opencode-runtime及 MySQL、Redis、MinIO、skill-scannerPod 全部 Running。
③ Longhorn 卷健康
kubectl -n longhorn-system get volumes.longhorn.io \ -o custom-columns=NAME:.metadata.name,STATE:.status.state,ROBUSTNESS:.status.robustness,REPLICAS:.spec.numberOfReplicas,SHARESTATE:.status.shareState期望：所有卷healthy；工作区 RWX 卷额外应显示SHARESTATE: running和 NFS 端点（share-manager正常启动的标志）。
访问 Web 控制台并验收部署
集群清单把前端暴露为 HTTPS NodePort（clawmanager.yaml）：
kubectl 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 一直Pending | StorageClass / CSI 未就绪 | kubectl get sc、kubectl -n clawmanager-system describe pvc <名>看事件 |
Pod 卡ContainerCreating，提示 mount helper 缺失 | 节点没装 NFS 客户端 | 补装nfs-common/nfs-utils后重启 Pod |
RWX 卷卡在shareState: starting | NFS 客户端缺失、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_PROFILE | cluster | 声明多节点 CSI 模式 |
K8S_HOSTPATH_FALLBACK_ENABLED | false | 禁止悄悄退回 HostPath |
K8S_PVC_BIND_TIMEOUT | 2m | PVC 绑定等待上限 |
K8S_CONTROL_PLANE_STORAGE_CLASS | longhorn | 控制面 RWO 卷的 StorageClass |
K8S_INSTANCE_STORAGE_CLASS | longhorn | 实例 RWO 卷的 StorageClass |
K8S_WORKSPACE_STORAGE_CLASS | longhorn-rwx | 工作区 RWX 卷的 StorageClass |
同时把清单中 4 个 PVC 的storageClassName改为你的类名，并确认K8S_WORKSPACE_ACCESS_MODE=ReadWriteMany与新存储的访问模式一致。更多运维细节（归档大小限制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 \ --type=merge -p '{"value":"true"}' # 3. 运行官方卸载 Job kubectl create -f deployments/k8s/cluster/uninstall.yaml kubectl wait --for=condition=complete job/longhorn-uninstall -n longhorn-system --timeout=10m # 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 就绪 → PVC
Bound→ 卷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），仅供参考
