CubeStudio 多机部署这件事，说实话我犹豫了很久才动手。之前一直用单机模式跑，三台GPU服务器各管各的，模型训练任务手动分发，数据靠U盘和网盘倒腾，项目组之间抢卡全靠吼。后来赶上团队扩张、多个项目并行，单机模式彻底撑不住了，才下定决心做多机、多集群、多资源组改造。这篇文章把整个过程的思路、步骤和踩过的坑都记下来，给同样在摸索的人一个参考。
1. 为什么单机模式必然走到头：算力孤岛和运维黑洞
先说说我当时遇到的实际问题。CubeStudio 单机部署确实快，一条命令装完就能拉起界面，几个工程师自己用完全够。但当规模涨到四五台机器、二三十号人同时使用时，单机模式的问题就暴露得特别明显：模型训练需要跨节点的大显存，单机搞不定；数据放在某一台机器上，换台机器跑任务就要重新拷；项目组之间没有隔离，A 组的任务把 GPU 占满，B 组连个测试任务都排不进去。
有人可能会想，那我把 CubeStudio 在每台机器上都装一遍，不就成了"多机"？这条路我试过，短期看确实能分散压力，但实际是制造了更多的算力孤岛和运维黑洞：每台机器一套独立的实例，用户要记住不同的访问地址，任务和数据完全割裂，监控也看不到全局视角。这就像每家每户自己挖一口井，而不是统一的自来水管道系统，水量再大也是分散的。
所以我当时给自己定了一个改造方向：以 Kubernetes 为底座，把多台物理机汇聚成一个统一的资源池，CubeStudio 作为上层的 AI 算力管理平台，负责接收用户的训练任务、自动调度到合适的节点、按项目组分配资源额度。这样一来，用户接触的还是同一个 CubeStudio 界面，但背后的算力已经在多台机器上自由流转。
这个思路的核心，是把"机器管理"和"算力管理"两个层面分开：机器层面由 K8s 统一纳管，算力层面由 CubeStudio 统一调度。后面所有实操步骤，都是围绕这两层展开的。
2. 扩容前的硬门槛：网络、存储、GPU 这三件事必须先想清楚
多机部署不是把机器拉到一起就能干的，前置条件不满足，后面全是坑。我踩得最狠的三块是：网络、存储和 GPU 环境。
2.1 网络规划：主机名、IP 段和端口一个都不能乱
多机模式下，节点之间要通过网络通信，所以必须提前规划好 IP 和主机名。我当时的规划方法是：
- 所有 GPU 服务器放到同一个二层网络里，保证相互之间低延迟高带宽，至少万兆网卡；
- 每台机器设置固定的主机名（如
gpu-node-01、gpu-node-02），并在/etc/hosts里写全所有节点的映射，避免 K8s 集群内部通过 DNS 解析出现混乱； - GPU 服务器之间可能需要大的模型文件传输，光靠管理网络跑会卡死业务，有条件的话单独拉一条数据网络，或者做网卡 bond。
另外要确认几个关键端口能互通：Kubernetes API Server 的 6443、节点上 kubelet 的 10250、etcd 的 2379-2380，以及 CubeStudio 自身的 Web 端口和各类组件之间的内部端口。我见过不少团队，前面步骤都装好了，最后卡在防火墙规则上，节点状态反反复复地NotReady，排查了一个晚上才发现是 10250 端口被安全策略挡了。
2.2 存储规划：模型权重和数据集必须共享
单机模式下，数据放在本机磁盘就行。多机部署后，同一个训练任务可能被调度到任意一台节点上运行，如果数据只在某一台机器上，那任务跑到别的机器上就找不到数据了。最直接的解法是上共享存储。
我没有一上来就搞复杂的分布式存储，而是先上了 NFS：一台存储服务器作为 NFS Server，各 GPU 节点作为 Client 挂载同一个目录，模型权重、数据集、输出目录全部放在共享存储上。CubeStudio 在提交任务时，容器里挂载的路径是统一的/data，底层映射到 NFS 共享目录，这样无论任务被调度到哪台节点，访问的数据都是一致的。
这里有个细节值得提醒：NFS 的挂载参数要注意权限和锁。多节点同时读写同一个目录，文件名冲突、缓存不一致的情况时有发生，建议挂载时加上nolock,noatime,actimeo=60这类参数，并统一使用同一个 UID/GID 启动容器，避免权限错乱。等规模再大一点，可以升级到 CephFS 或 JuiceFS 这类分布式文件系统，但起步阶段 NFS 完全够用。
2.3 GPU 环境：驱动、containerd 和运行时一条链
GPU 是多机部署里最容易出问题的地方。我们当时每台机器显卡型号还不完全一样，有 A 卡有 N 卡，折腾了很久才把环境对齐。确认了以下几点，才敢往下走：
- 每台节点安装与显卡匹配的驱动版本，并保证驱动版本在同一大版本内；
- 容器运行时（我们用的是 containerd）要配置好 nvidia-container-runtime，让容器能真正访问 GPU 设备；
- 提前把 GPU 型号对应的调度标签打上（比如
gpu-type=a100、gpu-type=3090），方便后面按项目组分算力时做精细调度。
这里最容易犯的错是：只在部分节点配好了 GPU 环境，结果任务被调度到没配好的节点上，容器起来了却拿不到nvidia-smi的输出，报一堆奇怪的驱动错误。排查半天，最后发现是nvidia-device-plugin这个 DaemonSet 在部分节点上没正常启动。所以强烈建议多机部署前，先把所有节点都打成一个统一基线：驱动版本、容器运行时版本、共享存储挂载、时间同步全部一致。
3. 多机部署实操：从主节点初始化到 worker 节点加入
这一部分是整个改造的核心动作。以下步骤基于常规的 Kubernetes 部署方式，实际环境可以根据版本和网络情况微调。
3.1 初始化主节点（Master）
我选择其中一台高性能机器作为 K8s 主节点，跑控制面组件和 CubeStudio 的调度服务。初始化前需要先做几件事：
- 关闭 swap 分区（K8s 的 kubelet 默认要求）；
- 加载内核模块
br_netfilter，并设置net.bridge.bridge-nf-call-iptables=1； - 配置时间同步，我这里用的是
chrony，所有节点指向同一台时间服务器，避免证书校验因时间偏差而失败。
初始化命令大致是：
kubeadm init \ --apiserver-advertise-address=192.168.1.10 \ --pod-network-cidr=10.244.0.0/16 \ --service-cidr=10.96.0.0/16初始化成功后，kubeadm 会输出两段关键信息：一段是kubeadm join命令和 token，另一段是用于生成管理员配置的kubeconfig。token 默认 24 小时过期，但后面还要加 worker 节点，建议把输出内容存好，或者提前在需要时再生成新 token。
3.2 安装容器网络插件（CNI）
多机部署和单机最大的区别之一，就是容器网络必须跨节点互通。我们用的是 Calico，安装后每个节点上的 Pod 会获得一个集群内的独立 IP，跨机器访问容器地址不再依赖宿主机端口映射。
这一步容易踩的坑是：CNI 的网段必须和初始化时的--pod-network-cidr保持一致，否则节点之间路由完全不通，Pod 只能在自己节点内部通信。当时我就在这个坑里困了好久，反复看日志才发现 Calico 的CALICO_IPV4POOL_CIDR配的和 kubeadm 的 pod-network-cidr 不一致。
3.3 加入 worker 节点
其余 GPU 服务器作为 worker 节点加入集群，命令就是初始化输出里的那段：
kubeadm join 192.168.1.10:6443 --token xxx --discovery-token-ca-cert-hash sha256:xxx每台节点执行完，回到主节点上用命令确认状态：
kubectl get nodes看到所有节点都处于Ready状态后，再给每个节点打上 GPU 类型标签，比如：
kubectl label node gpu-node-01 gpu-type=a100至此，底层 Kubernetes 集群已经完成多机化，所有节点的 CPU、内存、GPU 资源都被汇总到同一个资源池里。但这只是第一步，CubeStudio 还需要做对应的适配。
3.4 部署 CubeStudio 到集群
CubeStudio 自身要以容器方式运行在这个 K8s 集群里，相当于把平台服务托管到资源池上。为了便于升级和监控，我选择了 Helm 方式部署，把 Web 服务、调度服务、数据库等组件都装进集群。
这里有一个重要的取舍：CubeStudio 的服务组件包含数据库和文件存储，我特意把数据库挂到共享存储上，这样即使组件 Pod 在节点间漂移，数据也不会丢。如果数据库跑在本地磁盘上，一旦 Pod 被调度到别的节点，数据就完全找不回来了。
部署完成后，需要确认平台能看到集群的全部资源。正常情况下，节点列表会显示所有已加入的 GPU 机器，而不是单机模式下的那一台。如果只显示一台，多半是 kubeconfig 权限或者节点标签问题，优先检查这两个方向。
3.5 从单机切换到多机的最小心智
如果之前已经用了单机版 CubeStudio，里面还有历史任务和数据，建议先做好备份再切换。我们当时的做法是：把单机版的数据目录整体打包存到共享存储，再在新环境中指定该目录，重新启动后发现历史任务记录、数据集列表都还在。这一步虽然在文档里不怎么提，但实际升级时非常关键，直接决定你能不能无痛迁移。
4. 把外部 K8s 集群"收编"进来：纳管流程与证书权限
多机做完之后，多集群的需求很快就来了。我们的第二套 K8s 集群跑在另一朵云上，平时归另一个团队管，两边的资源各自独立，但都想统一在 CubeStudio 看板里使用。于是 CubeStudio 的多集群纳管功能就派上了用场。
4.1 在目标集群里创建一个专用的服务账号
纳管的核心，不是让 CubeStudio 直接拿到目标集群的admin权限，而是为目标集群创建一个受限的服务账号（ServiceAccount），授予它足够调度资源的权限，但又不至于影响集群本身的稳定性。我们按最小权限原则分配：
apiVersion: v1 kind: ServiceAccount metadata: name: cubestudio-sa namespace: kube-system --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: cubestudio-bind subjects: - kind: ServiceAccount name: cubestudio-sa namespace: kube-system roleRef: kind: ClusterRole name: cluster-admin这里要注意：虽然例子用了cluster-admin，但如果你对集群安全有更高要求，建议细化为只授予namespaces、pods、persistentvolumeclaims等资源的读写权限，不要轻易给全量管理员权限。
创建好之后，通过命令拿到该 ServiceAccount 的 Token：
kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep cubestudio-sa | awk '{print $1}')还需要拿到目标集群的 API Server 地址，一般是在~/.kube/config里可以看到server字段。有了 API Server 地址和 Token，就能在 CubeStudio 平台的"集群管理"页面里填入这两项，完成纳管。
4.2 证书有效期和网络可达性是两个大坑
纳管成功后，最常踩的坑来自两个方向。
第一个是证书过期。K8s 集群里的 ServiceAccount Token 有的有明确有效期，过期后 CubeStudio 就无法正常往该集群下发任务。解决办法有两个方向，一个是定期刷新 Token，另一个是部署支持自动轮转的 Token 机制。
第二个是网络可达性。CubeStudio 所在集群的节点必须能够访问目标集群的 API Server 地址。如果两个集群在不同的内网段，或者一个在线下机房一个在云上，就要提前打通专线或公网安全组策略。否则平台上会一直显示该集群"连接失败"。
4.3 多集群视图下的资源归属
收编多个集群后，同一个资源池可能包含不同地域、不同计费方式的机器。我们通过给集群打标签来区分归属，比如region=beijing、region=shanghai、cloud=private。这样调度任务时，既可以指定某几个项目组用某个集群，也可以设置跨集群的全局调度策略，让任务自动选择最空闲的机器。
多集群最怕的是"看着资源很多，但任务全堆在同一个集群里"，所以要定期查看各集群的实时占用率。CubeStudio 的集群看板可以直观看到每个集群的 GPU 使用率、节点状态、任务排队数，这是多集群管理里最值得盯的一个面板。
5. 按项目组分算力：资源组、配额与所有权
多机和多集群解决了"算力在哪里"的问题，但如果人人都能不看配额地提交任务，很快资源池又会变成新的混乱。所以下一步，就是按项目组分算力。
5.1 资源组的逻辑：先划物理池，再划逻辑配额
我们的资源分组有两层逻辑：
- 物理资源池：把节点按用途划分。比如
gpu-a100这个池子只包含 A100 节点，gpu-3090池子包含 3090 节点； - 逻辑配额：在 CubeStudio 里创建项目组，给每个项目组绑定一个或多个物理资源池，并设置 CPU、内存、GPU 卡数的上限。
举个例子，算法一队做大型模型预训练，独占gpu-a100池子里的 8 张卡；算法二队做模型微调和推理测试，绑定gpu-3090池子里的 6 张卡。这样两队之间互不干扰，谁也不会因为对方的任务而排队。
5.2 配额设置与超卖控制
给项目组设置配额时，要考虑的不只是 GPU 卡数，还有显存和 CPU。我当时做过一个不太科学的设置，只限制了 GPU 卡数，结果一个项目组把整个池子的系统内存和节点磁盘跑爆了，其他项目组跟着遭殃。
合理的配额应该是一个组合：GPU 卡数、显存总量、CPU 核数、内存上限、存储配额，最好都设置上。团队规模不大的情况下，可以用简单的静态配额，先不给超卖，等资源利用率确实上来了再动态调整。
具体操作上，在 CubeStudio 的"资源组管理"页面新建项目组后，需要配置：
- 选择绑定的集群（单集群或多集群）；
- 选择允许使用的资源池标签（比如
gpu-type=3090）； - 设置 GPU、CPU、内存的限额；
- 关联项目组用户或用户组。
这些配置保存后，用户在提交任务时，就只能看到自己项目组绑定的那些资源，其他池子的资源对个人用户完全不可见。这个隔离效果非常重要，它让用户从感受上觉得"这个池子就是我的"，而不是所有人共享一个巨大的公共池，从而减少抢资源引发的矛盾。
5.3 命名空间隔离与权限粒度
在 Kubernetes 层面，每个项目组对应的就是一个独立命名空间（Namespace）。CubeStudio 创建项目组时，会自动在该命名空间下创建对应的配额对象（ResourceQuota）和限制范围（LimitRange），这样即使绕开 CubeStudio 直接操作 K8s，也能保证同样的配额限制。
我建议把"命名空间名称"和"项目组名称"强绑定，并形成命名规范，比如proj-nlp、proj-cv。这样后续排查问题、看日志、做成本核算都方便得多。否则项目组起了一堆随意命名的名字，运维排查时根本分不清哪个是哪个。
5.4 按项目组分算力的一个隐藏收益
除了控制资源，按项目组分算力还有一个隐藏收益：数据权限隔离。每个项目组在共享存储上有独立目录，挂载到各自容器的不同路径下。项目组 A 的容器访问不到项目组 B 的数据目录，这在多人协作和合规审计的场景下非常重要。我们当时因为一个项目涉及不能互相对外公开的数据，特意加强了这块配置，效果很直接。
6. 部署过程中的坑和我的处理方式
前面那些章节基本是"地主家"的流程，下面这些坑才是我真正花时间的地方，一个个说清楚。
6.1 节点状态反复 NotReady 的元凶
多机集群刚开始运行时，经常出现某个节点NotReady，过几分钟又恢复。查了半天发现根因是内存空间不足——kubelet 定期报告节点状态，但系统压力大时，kubelet 会被 cgroup 限制甚至被 OOM Kill。解决办法是给 kubelet 所在的系统进程留足够的系统资源，并检查节点 docker/containerd 目录是否有堆积的日志和镜像缓存，定期清理。
另一个容易忽略的因素是节点时钟漂移。K8s 的证书校验非常依赖时间，一台节点的时钟和主节点差了几分钟，连接就会断断续续。所以我们后来在每台节点上强制配置了chrony，并加了定时任务检查时间同步状态。
6.2 GPU 显存与调度器的"盲区"
平台调度任务时，对 GPU 的感知依赖于nvidia-device-plugin上报的显存和型号。有一次我看到某个节点上报了 8 张 A100，就放心地把 8 个任务调度过去，结果第三个任务直接失败。查了下是因为显存已经被之前残留的僵尸进程占满，但设备插件上报的数据还是"空闲"。
这个问题的本质是：K8s 和调度器默认只认 GPU 卡数，不认显存余量。如果多个小任务共享一张卡，就会发生资源冲突。我们的处理方案是：
- 在调度策略上默认每个任务独占整张 GPU 卡，不做显存切分；
- 如果需要显存切分，开启 MIG 或者 GPU 共享插件，但这要求任务本身能适配；
- 定期检查节点上的残留 GPU 进程，发现异常及时清理。
6.3 共享存储的权限混乱
多集群接入后，不同集群的节点通过不同的 UID 运行容器，结果访问同一个 NFS 目录时权限乱了套：一个集群创建的文件，另一个集群没权限读。
这个问题我处理得比较暴力：在所有集群上统一了nfs-utils的挂载 UID/GID，并规定所有容器使用同一个runAsUser用户名。虽然不够精细，但对于一个内部平台来说，稳定性和"谁都能读"比严格的权限划分更重要。真正要做到精细化的多租户存储，建议引入带配额和权限体系的分布式文件存储，而不是继续用 NFS 死磕。
6.4 日志和监控跨集群不统一
多集群环境下，最怕的就是排错时在每个集群里东翻西找：用户报任务失败，但根本不知道任务被调度到了哪台机器上。我们后来把所有集群的日志统一汇聚到一套日志平台里，并且强制在日志里记录Node Name、Pod UID、Project Group三个维度。这样排错时可以根据项目组 + 时间范围直接过滤出完整链路，不用再挨个节点翻日志。
监控方面同理。各个集群独立部署 Prometheus 的话，管理成本很高，最好在 CubeStudio 侧统一接入监控数据源，按集群维度做聚合面板。这样一张大屏可以看清整个平台的状态，而不是十几个 Grafana 页面来回切。
6.5 高可用与升级策略
多机、多集群架构下，平台的调度服务是核心中的核心。如果 CubeStudio 调度服务挂掉，所有项目组都没法提交新任务。所以生产环境千万不能让平台服务单点运行。我的建议是：
- CubeStudio 自身的核心组件至少 2 个副本，分布在不同节点；
- 数据库和文件存储走共享存储或托管数据库；
- 平台升级前先在测试集群验证一次，再滚动升级生产集群；
- 每次纳管新集群时，做一个"最小任务验证"，确认该集群可以正常拉起 Pod、访问共享存储、上报资源，再正式开放给项目组。
这套策略帮我们躲过了两次升级翻车的局面，虽然每次升级都花费不少时间，但总比线上任务大面积失败再回滚好得多。
尾声：实操中的三个体会
这套架构跑了几个月之后，我最大的感受是：多机、多集群并不是越复杂越好，而是要让用户和运维都能舒服地使用才算成功。
第一个体会是"先跑通再优化"。不要一开始就追求所有集群全部接入、所有资源组都严格配额，先让一个小团队的一两个项目在上面跑起来，把流程验证通了，再逐步扩容。第二个体会是"标签的一致性就是生命线"。无论是集群标签、GPU 标签还是项目组命名规范，都要统一维护，否则随着节点和集群越加越多，混乱度会指数级上升。第三个体会是"排错时先看时间，再看权限，最后看资源"。通常这三个维度能覆盖八成的部署问题。
如果你也在做类似的改造，不妨从一台机器扩展到两台的场景开始，把平台在 K8s 上的部署流程完全跑通，再考虑多集群和资源组。直接一步到位虽然看起来快，但遇到问题时跨度太大，很难定位是哪一层出的错。希望这篇实操记录能帮你少走几步弯路。
