文档

• 1: 1.6 发布说明
• 2: 快速开始
• 3: 使用手册
• 3.1: 操作与日志
• 3.2: 镜像仓库
• 3.3: 诊断与升级检查

1 - 1.6 发布说明

KubeClipper v1.6.0 于 2026 年 6 月 2 日正式发布。Release · 完整变更。

发布内容

• containerd 2 和 Calico v3.31.5 支持，更新 Kubernetes 组件矩阵。
• Operation 命令和日志查看改进，包括按集群打开 TUI。
• kcctl set cluster 可配置集群外部访问。
• 镜像仓库配置持久化，以及更新 registry 认证时保留现有 containerd 配置等修复。

组件矩阵

来源：v1.6.0 README。可用资源还取决于平台中已上传的版本和架构。

架构与默认端口

1.6 由 kc-server、kc-agent、kcctl、Console 及平台 etcd 组成，使用内置或外部 NATS 分发任务。它与 1.7 的 API 驱动 Operation v2 架构不同。

限制管理端口访问，并按部署配置核对实际端口。默认值来源：v1.6.0 部署选项。

与 1.7 的命令差异

• 1.6 终止操作使用 kcctl operation terminate；1.7 使用 cancel。
• 1.6 不提供 1.7 的 kcctl status、kcctl doctor，使用节点服务和日志排查。
• 1.6 文档中的组件矩阵、NATS 配置和任务模型应与 1.6 二进制配套使用。

2 - 快速开始

以下命令在 Linux amd64 部署机的 Bash 中执行，使用 v1.6.0 客户端和完整部署包。准备使用 systemd、SSH 可达且部署用户有 sudo 权限的 Linux 节点；配置时间同步，核对 Kubernetes 的内核、cgroup 和磁盘要求。

安装客户端

1.6 发布标签中的旧安装脚本使用 oss.kubeclipper.io，该域名当前证书已过期。下面直接从 GitHub Release 下载客户端，不关闭证书校验。

curl -fL -o kc-linux-amd64-v1.6.0.tar.gz \
  https://github.com/kubeclipper/kubeclipper/releases/download/v1.6.0/kc-linux-amd64.tar.gz
mkdir -p kc-client-v1.6.0
tar -xzf kc-linux-amd64-v1.6.0.tar.gz -C kc-client-v1.6.0
sudo install -m 0755 kc-client-v1.6.0/kcctl /usr/local/bin/kcctl
kcctl version

其他客户端架构从 1.6 Release选择对应包。arm64 归档中的二进制位于架构子目录，先用 tar -tzf 查看路径。

下载完整部署包并安装平台

客户端归档不能替代完整部署包。下面使用项目的 OSS 原生域名，amd64 和 arm64 均有对应完整部署包。

curl -fL -o kc-amd64-v1.6.0.tar.gz \
  https://kubeclipper.oss-ap-southeast-1.aliyuncs.com/release/v1.6.0/kc-amd64.tar.gz
read -r -s -p '设置 admin 密码: ' KC_ADMIN_PASSWORD
printf '\n'
kcctl deploy --user root --pk-file "$HOME/.ssh/id_rsa" \
  --pkg "$PWD/kc-amd64-v1.6.0.tar.gz" \
  --initial-password "$KC_ADMIN_PASSWORD"
unset KC_ADMIN_PASSWORD

使用可登录目标节点的 SSH 私钥，密码设为 8–16 位并包含大写、小写字母和数字。多节点部署参数通过 kcctl deploy -h 核对。保持 API 与 NATS 的 TLS 配置开启。

登录与创建集群

将 Server 地址和节点 IP 替换为自己的值，命令会提示输入 admin 密码。控制台入口为 http://SERVER_IP，CLI 使用 HTTPS API。

SERVER_IP=192.168.10.10
kcctl login --host "https://${SERVER_IP}:8080" --username admin
kcctl get node
kcctl resource list

先确认平台资源列表包含所需版本及节点架构，再创建单节点实验集群：

NODE=192.168.10.10
kcctl create cluster --name demo --master "$NODE" --untaint-master \
  --k8s-version v1.36.1 --cri containerd --cri-version 2.2.4 \
  --cni calico --cni-version v3.31.5
kcctl operation list -c demo
kcctl get cluster demo -o yaml

安装完成后，从集群详情获取 kubeconfig，检查 kubectl get nodes -o wide、kubectl get pods -A 和 kubectl get --raw='/readyz?verbose'。操作排查见操作与日志。

3 - 使用手册

1.6 平台的操作、镜像仓库和维护。

3.1 - 操作与日志

1.6 的 Operation 通过旧版任务模型和 NATS 执行。查询当前操作，复制实际 ID 查看详情和日志：

kcctl operation list
kcctl operation list -c demo
OPERATION_ID='<实际操作 ID>'
kcctl operation describe "$OPERATION_ID"
kcctl operation logs "$OPERATION_ID"
kcctl operation logs "$OPERATION_ID" --follow
kcctl operation logs "$OPERATION_ID" --summary

在交互式终端中，按集群进入 TUI：

kcctl operation logs --cluster demo

保留失败节点和步骤的日志，处理原因后再重试。1.6 的 retry 只接受 failed 状态：

kcctl operation retry "$OPERATION_ID"

终止 running 状态的操作使用 terminate，不是 1.7 的 cancel：

kcctl operation terminate "$OPERATION_ID"
kcctl operation describe "$OPERATION_ID"

终止请求不代表节点变更已回滚。检查任务、集群和实际节点状态后再清理。命令来源：v1.6.0 Operation CLI。

3.2 - 镜像仓库

Registry 资源描述 Kubernetes 镜像源或 containerd 拉取配置。注册仓库不会自动复制镜像，离线组件包也需独立准备。

kcctl create registry --name internal --host registry.example.com:5000 --scheme http
kcctl get registry
kcctl create registry -h
kcctl registry -h

上例是管理网络中的 HTTP 仓库；生产环境按实际仓库配置 HTTPS、CA 和认证。1.6 还支持持久化 kcctl registry 的节点和 SSH 配置，后续操作前核对已有配置。

创建集群时，--image-registry internal 选择 Kubernetes 镜像源，--cri-registry internal 配置 containerd 镜像拉取。先准备镜像，再检查节点到仓库的连通性、证书和认证。参数来源：v1.6.0 Registry CLI。

3.3 - 诊断与升级检查

1.6 不包含 1.7 的 kcctl status 和 kcctl doctor。从版本、API、节点服务和任务日志开始排查。

kcctl version
kcctl get node
kcctl get cluster
kcctl operation list
kcctl resource list

在 Linux 节点按实际角色检查 systemd 服务，保留错误日志。NATS、平台 etcd 和 Server 的故障需要分别定位。

sudo systemctl status kc-server kc-agent kc-etcd kc-nats --no-pager
sudo journalctl -u kc-server -n 100 --no-pager
sudo journalctl -u kc-agent -n 100 --no-pager
sudo journalctl -u kc-nats -n 100 --no-pager

Agent 节点不一定部署 Server、etcd 或 NATS，使用外部 NATS 时也不会有本地 kc-nats 服务。核对实际角色及部署配置。

升级到 1.7 前

备份平台 etcd、配置、证书、认证密钥及受管集群数据。在可恢复的测试环境验证升级路径，重点核对 NATS 到 Operation v2 的差异、运行中任务及旧操作记录。查看1.7 升级检查，并确认实际运行的全部组件版本。

本页不承诺所有 1.6 部署都可直接原地升级。失败时先保留日志并按演练过的恢复步骤处理。