k3s 单机部署 CubeStudio

本篇说明如何用 k3s（Rancher 的轻量级 Kubernetes 发行版）在单台机器上快速搭一套 K8s 底座，作为 CubeStudio 的运行环境。k3s 适合资源有限、想快速体验单机部署的场景；命令里都用了国内镜像源加速。

关于其它 K8s 底座方式（RKE2 + Rancher、KubeSphere 多机）见同目录下对应文档。部署前的机器规格、操作系统等要求见 部署总览与前置要求。

一、master 节点

单机部署时只需要这一个节点（既是 master 也跑工作负载）。

# 关闭防火墙，清空 iptables 规则（避免与 k8s/容器规则冲突）
systemctl stop firewalld && systemctl disable firewalld && iptables -F && iptables -t nat -F && iptables -t mangle -F && iptables -X

# 下载部署脚本（指定 k3s 版本分支）
git clone -b v1.24.7+k3s1 https://github.com/k3s-io/k3s.git
cd k3s

# 设置 k3s 版本
export INSTALL_K3S_VERSION=v1.24.7+k3s1

# 设置 k3s 启动参数：
# --system-default-registry 让系统组件走阿里云镜像源
# --write-kubeconfig 把 kubeconfig 写到 ~/.kube/config
# --disable=traefik 不安装自带的 traefik（CubeStudio 用 istio 做网关）
# （注释行额外指定了 cluster-cidr / service-cidr，按需开启）
#export INSTALL_K3S_EXEC="--system-default-registry registry.cn-hangzhou.aliyuncs.com --write-kubeconfig ~/.kube/config --disable=traefik --cluster-cidr 10.72.0.0/16 --service-cidr 10.73.0.0/16"
export INSTALL_K3S_EXEC="--system-default-registry registry.cn-hangzhou.aliyuncs.com --write-kubeconfig ~/.kube/config --disable=traefik"

# 使用国内源
export INSTALL_K3S_MIRROR=cn
# 强制重新下载并替换软链接
export INSTALL_K3S_SYMLINK=force
#export INSTALL_K3S_FORCE_RESTART=true
# 国内镜像加速 URL
export INSTALL_K3S_MIRROR_URL=${INSTALL_K3S_MIRROR_URL:-'rancher-mirror.rancher.cn'}

# 替换 github 和 storage 为国内可访问的地址
export GITHUB_URL=https://githubfast.com/k3s-io/k3s/releases
export STORAGE_URL=https://k3s-ci-builds.s3.amazonaws.com
sed -i 's|^GITHUB_URL=.*|GITHUB_URL=https://githubfast.com/k3s-io/k3s/releases|' install.sh
sed -i 's|^STORAGE_URL=.*|STORAGE_URL=https://k3s-ci-builds.s3.amazonaws.com|' install.sh

# 执行部署
sh install.sh

# 打印 master 的 token（worker 节点加入集群时需要）
cat /var/lib/rancher/k3s/server/node-token

部署完后给 containerd 配置镜像 mirror，加速从 docker.io 拉镜像：

cat > /etc/rancher/k3s/registries.yaml <<EOF
mirrors:
  docker.io:
    endpoint:
      - "docker.1panel.live"
      - "docker.m.daocloud.io"
      - "hub.rat.dev"
EOF

二、worker 节点（多机时才需要）

单机部署不需要 worker 节点，本节可跳过。

如需扩展为多机集群，在每台 worker 上执行（myserver 换成 master 内网地址，K3S_TOKEN 用上一步打印的 node-token）：

systemctl stop firewalld && systemctl disable firewalld && iptables -F && iptables -t nat -F && iptables -t mangle -F && iptables -X
git clone -b v1.24.7+k3s1 https://github.com/k3s-io/k3s.git
cd k3s
export INSTALL_K3S_VERSION=v1.24.7
export K3S_URL=https://myserver:6443
export K3S_TOKEN=XXX
sh install.sh

三、配置 Containerd（非必须）

非必须，也可以使用 docker。

k3s 会在 /var/lib/rancher/k3s/agent/etc/containerd/config.toml 中自动生成 containerd 的配置文件。

如果要对这个文件做高级定制，可以在同一目录中创建一个名为 config.toml.tmpl 的文件，它会代替默认配置。config.toml.tmpl 是一个 Go 模板文件，渲染时 k3s 会把 config.Node 结构体传入模板，从而按结构字段自定义配置。具体用法（含 Linux / Windows 示例）参见 k3s 官方文档中 containerd 配置相关章节。

四、部署 cube-studio

部署完 k3s 后，就可以按"单机部署 cube-studio"的标准流程来部署平台了，参见 单机 k8s 部署。

将 k8s 集群的 kubeconfig 文件复制到 install/kubernetes/config 文件中，然后执行如下命令，其中 xx.xx.xx.xx 为机器内网的 IP（不是外网 IP）：

# 在 k8s worker 机器上执行（start.sh 第一个参数为内网 IP）
sh start.sh xx.xx.xx.xx

start.sh xx.xx.xx.xx 会用该内网 IP 给本节点打标签（train/cpu/notebook/service/istio/...=true）、部署 dashboard / mysql / redis / prometheus / istio / argo / 训练算子 / labelstudio 以及管理平台本体，并把 SERVICE_EXTERNAL_IP 等配置替换成该 IP。脚本细节见 install/kubernetes/start.sh。

五、清理

卸载 k3s（k3s 安装时自动生成的脚本）：

/usr/local/bin/k3s-killall.sh
/usr/local/bin/k3s-uninstall.sh

六、重启

sudo systemctl stop k3s
sudo systemctl start k3s
# worker 节点上是 k3s-agent
sudo systemctl stop k3s-agent
sudo systemctl start k3s-agent

k3s 版本、镜像加速地址等为示例值，可按需调整；CubeStudio 的部署命令与参数以源码（install/kubernetes/）为准，本篇仅供导航与上手。