文档

• 1: 概述
• 1.1: 1.7 发布说明
• 2: 快速开始
• 2.1: 部署 AIO
• 2.2: 离线创建集群
• 2.3: 准备离线组件包
• 3: 部署文档
• 3.1: 高可用部署
• 3.2: 升级检查
• 4: 使用手册
• 4.1: 创建集群
• 4.2: 集群托管
• 4.3: 集群管理
• 4.4: 节点管理
• 4.5: 访问控制
• 4.6: 操作与日志
• 4.7: 平台诊断
• 4.8: 镜像仓库
• 5: 常见问题
• 5.1: 集群创建排障
• 6: 贡献指南

1 - 概述

KubeClipper 为 Kubernetes 集群提供创建、扩缩容、升级、备份、恢复和删除等生命周期管理能力，提供 Web 控制台、API 和 kcctl 命令行。

1.7 架构

• kc-server 提供 API，保存集群和 Operation、Task 等资源，由控制器推进任务状态。
• kc-agent 安装在受管节点，通过 mTLS 访问 Server API，观察分配给本节点的任务，执行安装等操作并回报结果。
• kcctl / Console 提交管理请求，查看平台状态、操作进度和日志。
• etcd 保存平台资源和状态。平台 etcd 与所管理 Kubernetes 集群的 etcd 分别规划。

1.7 使用 API 驱动的 Operation v2，不再通过内置 NATS 分发任务。操作提交后异步执行，需结合 Operation、集群状态和节点实际状态确认结果。参见操作与日志。

网络与端口

端口可通过部署配置修改。Agent 任务日志监听配置也应与防火墙策略一起核对；不要直接套用旧版 NATS 端口表。

--ip-detect 选择平台管理地址；--node-ip-detect 选择 Kubernetes 节点地址。多网卡环境需要确认所选地址与管理网络可达。Pod 网络的地址发现规则由所选 CNI 配置决定。

版本与入门

• 1.7 发布说明与组件矩阵
• 快速开始
• 高可用部署
• 平台诊断

1.1 - 1.7 发布说明

本套文档对应 KubeClipper v1.7.0，发布于 2026 年 9 月 8 日。官方发布记录：v1.7.0。

主要变化

• Operation v2 通过 API 管理操作、任务和执行状态，Agent 与 Server 使用 mTLS 通信。
• kcctl operation 提供操作列表、详情、日志、重试和取消。
• kcctl status 与 kcctl doctor 提供平台状态检查和诊断。
• Registry 资源可用于选择 Kubernetes 镜像仓库和配置 containerd 镜像拉取。
• 部署预检查给出节点、角色和错误原因；Server 安装前等待平台 etcd 健康。

组件版本

默认 Kubernetes 版本为 v1.37.0。实际可选项以平台组件资源为准；离线环境还需准备对应 CPU 架构的包。版本来源：v1.7.0 支持矩阵。

版本边界

本文描述 v1.7.0 已发布能力。生产使用前查看 Release、安全公告和所用二进制版本。升级前参考升级检查。

版本菜单保留 1.6～1.1 历史文档。1.6 文档按 v1.6.0 发布标签整理。

2 - 快速开始

本文使用 KubeClipper v1.7.0。准备一台通过 SSH 可访问、使用 systemd 的 Linux 主机，部署 KubeClipper，再在该主机创建单节点实验集群。生产环境请参考高可用部署。

准备主机

• 安装 curl、tar、sudo，确保 SSH 服务可用，部署用户有 sudo 权限。
• 启用 chrony、ntp 或 systemd-timesyncd 中的一种时间同步服务。
• 准备可登录目标节点的 SSH 私钥，并确认节点之间的地址可达。
• 核对目标 Kubernetes 版本对内核、cgroup 和容器运行时的要求。历史文档中的操作系统列表不代表新版本 Kubernetes 的兼容性范围。
• 为部署包下载、解压和容器镜像预留磁盘空间。1.7.0 的完整部署包约 1.2 GiB，GitHub Release 中约 60 MB 的二进制包不能替代完整部署包。

安装 kcctl

下载与 1.7.0 发布标签一致的安装脚本，再执行安装。脚本通过项目的阿里云 OSS 原生域名下载二进制，不依赖旧的 oss.kubeclipper.io 域名。

curl -fL -o get-kubeclipper.sh \
  https://raw.githubusercontent.com/kubeclipper/kubeclipper/v1.7.0/scripts/get-kubeclipper.sh
KC_VERSION=v1.7.0 bash get-kubeclipper.sh
kcctl version

脚本支持 Linux、macOS 的 amd64 和 arm64 客户端。平台服务部署在 Linux 上；以下命令在 Linux 部署机运行。也可以从 v1.7.0 Release 下载对应客户端。

下载完整部署包

按目标平台架构设置 ARCH。下例为 amd64；arm64 主机将其改为 arm64。

ARCH=amd64
curl -fL -o "kc-${ARCH}.tar.gz" \
  "https://kubeclipper.oss-ap-southeast-1.aliyuncs.com/release/v1.7.0/kc-${ARCH}.tar.gz"
tar -tzf "kc-${ARCH}.tar.gz" | head

完整部署包包含平台服务、控制台及离线资源。离线环境需要提前在联网机器下载，再传入部署机。创建 Kubernetes 集群时还应核对平台中已有的组件包和架构，见离线创建集群。

部署 All-in-One 平台

以下示例使用 SSH 私钥。替换为自己的私钥路径；部署机必须能够通过 SSH 登录目标节点，即使目标节点就是本机。

read -r -s -p '设置 admin 密码: ' KC_ADMIN_PASSWORD
printf '\n'
kcctl deploy --user root --pk-file "$HOME/.ssh/id_rsa" \
  --pkg "$PWD/kc-${ARCH}.tar.gz" \
  --initial-password "$KC_ADMIN_PASSWORD"
unset KC_ADMIN_PASSWORD

初始密码需满足平台校验要求：8–16 位，包含大写字母、小写字母和数字。部署前检查失败时，先处理输出中对应的节点和检查项，不要反复重装。

1.7 的 Agent 通过 mTLS 访问 Server API，部署时保持 TLS 开启。默认控制台为 http://SERVER_IP:80，Server API 为 https://SERVER_IP:8080，这两个入口用途不同。

登录并检查平台

将 SERVER_IP 替换为实际 Server 地址。命令会提示输入刚才设置的 admin 密码。

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

通过浏览器访问 http://SERVER_IP 可打开控制台。生产环境应在控制台入口配置 HTTPS。status 检查平台状态，doctor 给出诊断证据；它们不会自动修复环境。

创建第一个集群

从 kcctl get node 的结果选择就绪节点，将节点 ID 或 IP 填入 NODE。离线方式是默认值；先确认已有对应架构和版本的资源包。

NODE=192.168.10.10
kcctl create cluster --name demo --master "$NODE" --untaint-master \
  --k8s-version v1.37.0 --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

--untaint-master 允许实验集群在控制节点调度普通工作负载。安装耗时取决于机器、网络和镜像准备情况。命令提交成功后，继续查看 Operation 和集群状态，不能把提交成功当作安装完成。

从集群详情页获取 kubeconfig，设置 KUBECONFIG 后检查 Kubernetes：

kubectl get nodes -o wide
kubectl get pods -A
kubectl get --raw='/readyz?verbose'

确认集群处于 Running、节点 Ready，并检查系统 Pod 和 API 健康状况。任务失败时参考操作与日志和平台诊断。

清理实验集群

以下操作会删除 demo 集群，先确认其中没有需要保留的工作负载和数据：

kcctl delete cluster demo
kcctl operation list -c demo
kcctl get cluster

等待删除操作结束并确认集群已移除。不要使用重置状态或强制删除来代替失败原因排查。

2.1 - 部署 AIO

All-in-One 将 Server 和 Agent 部署在同一台 Linux 主机上，适合体验和实验。

完整步骤见快速开始：准备主机、安装 v1.7.0 kcctl、下载完整部署包、部署平台并创建实验集群。

生产环境请先规划独立的 Server 和工作节点，参考高可用部署。

2.2 - 离线创建集群

离线安装需要先准备平台部署包，以及 Kubernetes、CRI、CNI 等组件资源。Registry 资源只描述镜像仓库，不能替代离线包。

检查资源

完成平台部署后登录并检查：

kcctl resource list
kcctl get node

确认目标节点架构与资源包一致。1.7 推荐矩阵为 Kubernetes v1.37.0 / v1.36.4 / v1.35.8、containerd 2.2.4、Calico v3.31.5。需要补充组件包时参考准备离线组件包。

创建集群

kcctl create cluster 默认离线安装。示例使用一个实验节点：

kcctl create cluster --name offline-demo --master 192.168.10.21 --untaint-master \
  --k8s-version v1.37.0 --cri containerd --cri-version 2.2.4 \
  --cni calico --cni-version v3.31.5
kcctl operation list -c offline-demo
kcctl get cluster offline-demo -o yaml

在 Console 创建时同样选择已准备好的组件版本、目标节点和离线方式。需要镜像仓库时先准备镜像并配置Registry 资源。存储插件按实际需求单独选择，不把某一种 NFS 插件当作创建集群的必选步骤。

确认安装结果

结合 Operation 和节点日志定位失败原因。取得 kubeconfig 后检查节点 Ready、系统 Pod 和 API readiness。离线资源缺失、架构不一致或镜像地址不可达时，先修正资源再重试，参见操作与日志。

2.3 - 准备离线组件包

1.7.0 的完整部署包和额外的 Kubernetes / CRI / CNI 组件包用途不同。先使用快速开始中的完整部署包部署平台，再按实际需求补充组件资源。

选择版本和架构

以 1.7 版本说明中的矩阵为准。以下示例下载 Kubernetes v1.37.0 的 amd64 组件；arm64 节点需准备 arm64 包，不要混用架构。

在联网机器下载并打包

以下命令在 Bash 中执行，使用项目 OSS 原生域名。curl -fL 会在下载失败时退出；不要忽略证书或 HTTP 错误后继续打包。

set -e
ARCH=amd64
VERSION=v1.37.0
PKG_DIR="$(mktemp -d)"
COMPONENT_DIR="k8s/${VERSION}/${ARCH}"
mkdir -p "${PKG_DIR}/${COMPONENT_DIR}"
for FILE in manifest.json configs.tar.gz images.tar.gz; do
  curl -fL -o "${PKG_DIR}/${COMPONENT_DIR}/${FILE}" \
    "https://kubeclipper.oss-ap-southeast-1.aliyuncs.com/packages/${COMPONENT_DIR}/${FILE}"
done
tar -czf "k8s-${VERSION}-${ARCH}.tar.gz" -C "$PKG_DIR" k8s
tar -tzf "k8s-${VERSION}-${ARCH}.tar.gz"

归档中需保留 k8s/版本/架构/ 层级，不能只压缩文件本身。下载目录保留在 $PKG_DIR，核对后可自行清理。

其他组件使用相同层级，按下表准备文件，再压缩对应组件目录：

例如 Calico 路径为 packages/calico/v3.31.5/amd64/manifest.json。这些是已有组件资源的打包方式，不代表任意自定义版本都已被平台支持。

传入离线环境并上传

把归档传到能访问平台的部署机。该机器需保留部署配置和可登录 Server 的 SSH 凭据。

kcctl resource push --pkg k8s-v1.37.0-amd64.tar.gz --type k8s
kcctl resource list

上传 containerd 和 Calico 时分别使用 --type cri、--type cni。确认平台能列出匹配的版本和架构，再按离线创建集群验证。镜像仓库的配置参见 Registry。

3 - 部署文档

3.1 - 高可用部署

本文部署 KubeClipper 平台的高可用控制面。平台 Server 的高可用与受管 Kubernetes 集群的高可用是两件事，需分别规划。

准备节点与网络

准备三个 Linux Server 节点，以及需要纳管的 Agent 节点。部署用户通过同一 SSH 私钥访问所有节点，并具备 sudo 权限。时间同步和端口要求见架构与网络。

Server 节点部署平台 etcd，节点数量和故障容忍按 etcd 仲裁要求规划。生产环境建议将平台 Server 与运行 Kubernetes 工作负载的节点分开。

安装和下载

按照快速开始安装 v1.7.0 kcctl，下载与目标架构匹配的完整 kc-amd64.tar.gz 或 kc-arm64.tar.gz 部署包。不要将 GitHub Release 的客户端二进制包传给 --pkg。

部署三个 Server 和 Agent

将示例 IP、私钥和部署包路径替换为实际值。--server 使用逗号分隔地址，--agent 可按区域填写。

read -r -s -p '设置 admin 密码: ' KC_ADMIN_PASSWORD
printf '\n'
kcctl deploy \
  --server 192.168.10.11,192.168.10.12,192.168.10.13 \
  --agent default:192.168.10.21,192.168.10.22 \
  --user root --pk-file "$HOME/.ssh/id_rsa" \
  --pkg "$PWD/kc-amd64.tar.gz" \
  --initial-password "$KC_ADMIN_PASSWORD"
unset KC_ADMIN_PASSWORD

保持 TLS 开启。多网卡环境通过 --ip-detect 与 --node-ip-detect 显式选择可达地址；可使用 kcctl deploy -h 核对参数。默认平台 etcd 端口为 12379、12380、12381。

验证结果

kcctl login --host https://192.168.10.11:8080 --username admin
kcctl status
kcctl doctor
kcctl get node

检查三个 Server 的服务状态、平台 etcd 成员和 Agent 是否正常。在其他 Server 地址重复检查 API 可达性。需要统一域名或 VIP 时，另行配置入口负载均衡和证书；部署三个 Server 不会自动创建入口 VIP。

浏览器默认访问各 Server 的 HTTP 80 控制台入口；CLI 使用 HTTPS 8080 API。生产入口应配置 HTTPS，并按实际网络限制管理端口访问。

添加和移除 Agent

kcctl join --agent default:192.168.10.23
kcctl get node

确认节点没有需要保留的集群和工作负载后，再执行移除：

kcctl drain --agent 192.168.10.23

先查看正常 drain 的错误原因，再决定后续处理；不要默认使用强制参数。升级前参见升级检查。

3.2 - 升级检查

平台升级与受管 Kubernetes 集群升级分别处理。本文介绍 KubeClipper 平台升级前后的检查，不承诺任意旧版本都可直接升级到 1.7。

升级前

1. 记录 Server、Agent、kcctl 和 Console 的版本及节点拓扑，确认目标包的 CPU 架构。
2. 查看目标版本的 Release、安全公告和配置变化。1.7 改用 Operation v2，旧操作记录和任务状态需要在测试环境核对。
3. 在没有运行中安装、升级、备份等操作的窗口执行。先处理未完成或失败的操作。
4. 备份平台 etcd、Server/Agent 配置、证书与持久化认证密钥，并验证恢复方法。受管集群的数据备份需要单独安排。
5. 在可恢复的测试环境演练目标升级路径，记录服务中断和恢复步骤。

kcctl version
kcctl status
kcctl doctor
kcctl operation list
kcctl upgrade -h

执行升级

kcctl upgrade 支持整个平台或组件升级。目标包应满足命令帮助中的目录结构，并已经在测试环境验证；不要把客户端包当成平台升级包。

UPGRADE_PACKAGE=/path/to/validated-upgrade-package.tar.gz
kcctl upgrade all --pkg "$UPGRADE_PACKAGE"

只有 Release 或已验证部署流程明确支持时，才使用在线升级或组件独立替换。不要把替换一个二进制文件视为整个升级完成。

升级后

再次检查 kcctl status、kcctl doctor，核对各节点实际运行版本。验证登录、节点信息、操作详情与日志、受管集群访问及 Console 基本流程。测试一个受控的生命周期操作，确认 Operation 和实际集群状态一致。

升级失败时保留错误和日志，按事先验证的恢复步骤处理。恢复旧二进制前先判断数据和配置是否仍兼容，不要在未知状态下反复覆盖服务。

4 - 使用手册

4.1 - 创建集群

创建集群前，确认 KubeClipper 平台可用、节点已注册并就绪、组件资源的版本和架构匹配。建议先完成快速开始，验证一条完整的部署路径。

控制台创建

登录控制台，在集群页面创建集群。填写名称，选择控制节点、工作节点及组件版本，再按实际网络规划设置 Pod / Service CIDR。生产集群需提前规划控制平面高可用、API 访问地址和存储；单节点实验配置不能直接用于生产。

1.7 的推荐组件组合参见版本说明。资源不在平台中时先上传组件包。私有仓库相关字段参见 Registry；镜像仓库和组件包是两种独立资源。

CLI 创建与验证

离线创建集群提供带明确版本的 CLI 示例。创建请求提交后，在Operation中查看执行结果，并检查集群状态、节点 Ready、系统 Pod 和 Kubernetes API 健康状态。失败时先保留日志并排查，不要通过重置状态跳过失败步骤。

4.2 - 集群托管

Kubeadm 集群托管

托管由 kubeadm 创建和管理的 kubernetes 集群，kubeclipper 会通过 kubeconfig 文件，获取集群和节点信息，并导入到 kubeclipper 平台中。

点击“集群管理”>“集群托管”按钮进入集群托管页面，点击左上角“添加”按钮，在添加提供商弹窗中，填写提供商名称（如 kubeadm-demo）和描述后，填写以下信息：

• 区域：提供商下的集群和节点在 kubeclipper 平台中的所属区域。
• 提供商类型：选择 kubeadm。
• 节点连接方式：集群节点的连接方式，可以选择“私钥”或者“密码”，您需要确保可以通过所选方式 ssh 到集群节点。
  • 选择“私钥”，需要输入节点用户名和私钥信息。
  • 选择“密码”，需要输入节点用户名和密码信息。
• 集群名称：作为在本平台的展示名称，不能与其他集群重复。
• KubeConfig：托管集群的 KubeConfig 文件。

填写完成后点击“确定”按钮，将集群和节点导入到平台中。点击提供商名称（kubeadm-demo），进入提供商详情页，您可以查看提供商下的集群，并对提供商执行以下操作：

• 同步：系统将每隔4小时定期同步集群信息，您也可以点击“同步”按钮手动执行。
• 编辑：编辑提供商的名称、描述、访问信息、节点连接方式。
• 移除：解除平台对该集群的管理，保留 Kubernetes 集群本体。清理还会移除导入时安装的 kc-agent，以及平台创建的 ServiceAccount、ClusterRoleBinding 和 kubectl 终端服务；原本已纳管的节点有不同的保留逻辑。移除前核对节点归属并保存 kubeconfig。

托管集群管理

您可以点击“集群管理”>“集群”进入集群列表页面，查看包括托管集群和本地集群在内的所有集群列表，对于不同集群，支持的管理操作如下表所示：

插件和外接存储的镜像来源以所选组件包及其配置为准。离线环境须提前准备镜像，并确认各节点能够从配置的仓库拉取；需要认证或自签名证书时，先配置 CRI 镜像仓库。

4.3 - 集群管理

KubeClipper 1.7 的集群生命周期操作由 Operation v2 执行。先查看集群对象，再用操作详情和节点实际状态确认结果。

kcctl get cluster
kcctl get cluster demo -o yaml
kcctl operation list -c demo

日志、重试和取消

完整命令见操作与日志。失败后先处理根因再重试；重置集群状态不会修复失败的节点或撤销已执行操作。

访问集群

在 Console 的集群详情页获取 kubeconfig，设置 KUBECONFIG 后执行：

kubectl get nodes -o wide
kubectl get pods -A
kubectl get --raw='/readyz?verbose'

平台状态正常不代表所有受管集群都正常。升级、扩缩容、备份和恢复后，都要检查对应集群中的节点、系统 Pod 和业务数据。

扩缩容与镜像仓库

先用 kcctl join 将新增机器纳入平台，确认节点就绪、区域与目标集群一致，再在集群详情中添加节点。移除节点前迁移工作负载并检查容量；平台的 kcctl drain 用于移除平台 Agent，不等同于集群缩容。节点接入步骤见节点管理。

Kubernetes 镜像仓库与 containerd 拉取仓库分别配置，具体步骤见镜像仓库。变更后检查实际镜像拉取结果。

备份与恢复

1. 配置备份空间，并在编辑集群时关联该备份空间。使用目录备份空间时，先在相关节点创建并挂载约定路径，确认可写。
2. 在集群中发起备份，或通过定时备份设置执行时间和保留数量；确认备份记录成功且文件可读取。
3. 恢复时选择该集群的备份记录，跟踪恢复 Operation，完成后检查 API、节点、系统 Pod 和业务状态。

这里的集群备份以 Kubernetes etcd 快照为核心，不包含业务持久卷中的文件；应用数据需要另行备份。恢复会改变集群状态，先在隔离环境演练，不能仅凭备份记录存在判断可恢复。

Kubernetes 版本升级

这与 KubeClipper 平台升级是两项操作。先备份并验证恢复方案，检查目标版本的组件资源、镜像和工作负载兼容性，再从集群的升级入口选择目标版本。托管的 kubeadm 集群不提供此升级入口。

CLI 参数可用下列命令查看：

kcctl cluster upgrade --help

升级命令使用 --cluster-name 和 --version 指定集群与目标版本，默认采用离线方式；--online 改为在线方式，--image-registry 选择已配置的 Registry 资源。目标版本必须在平台可用资源中，不能将支持矩阵当作任意版本间升级成功的保证。提交后跟踪 Operation，并执行上面的集群健康检查。

删除集群

先确认工作负载和数据已备份，再发起删除并跟踪 Operation：

kcctl delete cluster demo
kcctl operation list -c demo
kcctl get cluster

确认删除结束后再复用节点。失败时保留日志和节点状态，参考平台诊断，不要用强制删除掩盖未完成的清理。

4.4 - 节点管理

区域管理

平台支持多区域管理，即为平台管理的所有节点和集群进行物理或逻辑的区域划分。您可以在“区域管理”页面查看平台内管理的所有区域，点击区域名称，进入区域详情页面，可以查看区域下的所有集群列表和节点列表。

节点管理

您可以在“节点信息”页面查看平台中管理的全部节点列表，和节点规格、状态等信息。点击节点名称进入节点详情页面，可以查看详细的节点基本信息和系统信息。

KubeClipper 中的节点状态表示 kc-agent 对节点的管理状态。正常情况下，节点状态显示为“就绪”，默认节点健康监控宽限期为 4 分钟，每 10 秒检查一次；超过宽限期后，状态会更新为“未知”，实际显示时间还会受到调度和通信延迟影响。此时先排查 Agent、网络和 Server 连通性，恢复就绪后再安排新的集群部署或扩容。

添加节点

在部署 KubeClipper 时，您就可以添加初始的 server 节点和 agent 节点，其中，server 节点用于部署 KubeClipper 自身服务，agent 节点可用于部署 kubernetes 集群。在用于实验或开发的 KubeClipper 环境，您可以将 server 节点同时添加为 agent 节点。但如果用于生产环境，建议不要将 server 节点复用为 agent 节点。

您也可以使用 kcctl join 命令为 KubeClipper 添加 agent 节点。同时，您可以为每个 agent 节点标记一个区域，区域可以是物理的或逻辑的位置，您可以使用同一区域的节点创建 kubernetes 集群，但不可以使用跨区域的节点创建集群。未标记区域的节点默认属于 default 区域。

命令行示例：

kcctl join --agent beijing:1.2.3.4 --agent shanghai:2.3.4.5

移除节点

当您不再需要某些节点，可以使用 kcctl drain 命令将节点从平台中移除。

命令行示例：

kcctl drain --agent 192.168.10.19

连接终端

在节点列表页面，您可以点击目标节点右侧的“连接终端”按钮，在连接终端的弹窗中输入节点端口和用户名密码信息后，访问节点 SSH 控制台并执行命令。

启用/禁用节点

您可以点击节点右侧“禁用”按钮暂时禁用节点，禁用状态下的节点不允许创建或添加到集群。

4.5 - 访问控制

用户管理

安装 KubeClipper 之后，您需要创建所需角色的用户。一开始，系统默认只有一个用户 admin，具有平台管理员角色。

点击“访问控制”>“用户”，进入用户管理页面，点击左上角“创建用户”按钮，在弹窗中填写用户名、密码、手机号码、邮箱等信息，并指定用户角色，点击“确认”按钮。系统内置四个角色如下：

• 平台管理员：拥有集群管理、用户管理、审计管理等全部平台查看和操作权限。

• 集群管理员：拥有所有集群管理权限。

• 用户管理员：拥有所有用户管理权限。

• 平台只读用户：拥有全部平台查看权限。

用户创建完成后，您可以在用户详情页面查看用户详情信息，并执行以下操作：

• 编辑：编辑用户别名、角色、手机号、邮箱信息。

• 编辑密码：编辑用户登录密码。

• 删除：删除用户。

在用户详情页面，您还可以查看当前用户的登录日志列表。

您可以编辑平台 /etc/kubeclipper-server/kubeclipper-server.yaml 文件，根据需要设置用户登录日志的最大保留条数和保留期限，清理逻辑仅在该用户的日志总数超过最大条数时触发：先删除超额的旧记录，再清理剩余的过期记录；未超过最大条数时，不会仅因过期而删除。

自定义角色

除了系统内置角色，您也可以创建自定义角色，以满足业务需要。

点击“访问控制”>“角色”，进入角色管理页面，您可以点击左上角“创建角色”按钮，创建自定义角色。

在创建角色页面，您需要填写角色名称和描述，并勾选自定义角色所需权限，一些权限依赖于其他权限，在选择这些权限时，将自动选中依赖的权限。

创建自定义角色完成后，您可以在角色详情页面查看角色基本信息、角色权限列表、授权用户列表，并对自定义角色执行以下操作：

• 编辑：编辑自定义角色描述。

• 编辑权限：编辑自定义角色下的权限。

• 删除：删除自定义角色，需确保没有用户使用待删除角色。

接入外部用户

KubeClipper 可以通过 OIDC 协议使用外部用户登录。

首先，平台管理员需要登录平台 server 节点，在 kubeclipper-server.yaml 文件中的 authentication 下插入以下信息：

oauthOptions:
    identityProviders:
    - name: keycloak
      type: OIDC
      mappingMethod: auto
      provider:
        clientID: kc
        clientSecret: REPLACE_WITH_CLIENT_SECRET
        issuer: https://idp.example.com/realms/kubeclipper
        scopes:
        - openid
        - email
        redirectURL: https://console.example.com/oauth2/redirect/keycloak

这是 authentication 下的配置片段，需合并到现有配置。将示例域名和 REPLACE_WITH_CLIENT_SECRET 替换为实际值；IdP 注册的回调地址必须与 redirectURL 完全一致，路径末尾的 keycloak 与提供商 name 一致。各 Server 更新配置后，按节点滚动重启 kc-server。

其中，“provider” 下需要您填写自己的 OAuth2 服务的clientID、clientSecret、issuer信息，以 keycloak 为例，如下图所示。

redirectURL示例：https://console.example.com/oauth2/redirect/keycloak

OAuth2 用户可以通过以下步骤访问和使用 KubeClipper 平台：

1. 点击登录页的 “OAuth2 登录”按钮，进入 OAuth2 登录页面，输入用户名密码登录，进入 KubeClipper 平台，首次登录，您会因未被授予权限而无法访问平台。
2. 平台管理员或其他拥有用户管理权限的用户登录 KubeClipper，在用户管理页面，找到目标 OAuth2 用户，通过编辑用户指定用户角色。
3. OAuth2 用户重复第一步，登录 KubeClipper，就可以正常访问平台并执行角色权限内操作。

4.6 - 操作与日志

KubeClipper 1.7 将安装、升级、备份、删除等工作建模为 Operation，并按步骤和节点执行 Task。提交命令成功只表示请求已被接受，最终结果需要继续查询。

查找操作

kcctl operation list
kcctl operation list -c demo

从列表复制实际操作 ID 后查看详情和日志：

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

通过日志定位失败步骤和节点。在交互式终端中，可按集群打开 TUI 日志视图：

kcctl operation logs --cluster demo

脚本和非交互终端使用带操作 ID 的纯文本日志命令。

处理失败

先保留操作详情、失败节点日志和集群状态，处理包缺失、镜像下载、节点网络或服务异常等原因，再重试：

kcctl operation retry "$OPERATION_ID"
kcctl operation describe "$OPERATION_ID"
kcctl operation logs "$OPERATION_ID" --follow

重试后再次检查实际集群和节点，不能只看 retry 命令返回值。若参数本身错误，先核对任务配置，不要用反复重试代替修正。

取消操作

kcctl operation cancel "$OPERATION_ID"
kcctl operation describe "$OPERATION_ID"

取消不等于回滚已经执行的安装或数据操作。继续确认任务是否停止，以及节点上已经产生的变更；清理前先确定资源归属。

确认成功

结合 Operation 结果、kcctl get cluster demo -o yaml、Kubernetes 节点与 Pod 状态确认结果。集群删除后还要检查平台列表和节点残留。平台问题参考诊断指南。

4.7 - 平台诊断

先确定故障发生在平台、Agent、资源下载还是 Kubernetes 集群，再针对对应层排查。

平台状态

kcctl version
kcctl status
kcctl status -o json
kcctl doctor

status 汇总 kc-server、kc-etcd 和 kc-agent 的健康状态。doctor 检查本地访问、服务、平台 etcd 和 Agent，并输出失败证据。非健康结果会返回非零退出码，适合用于检查脚本；两个命令都不会自动修复环境。

若平台 API 无法访问，检查 kcctl login 使用的地址是否为 HTTPS API 入口，默认端口 8080。检查本地登录和部署配置，以及部署机到各节点的 SSH 连通性。

节点服务

在对应的 Linux 节点执行：

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

只部署 Agent 的节点不应要求存在 Server 或平台 etcd 服务。结合实际节点角色解读结果，并检查磁盘、时间同步、管理地址和防火墙。

部署失败

预检查错误会指出检查项和节点。若服务已存在，先确认该节点是否属于正在使用的平台；不要删除服务来绕过检查。下载错误应核对地址、证书、文件大小和包内容，不能用关闭证书校验掩盖错误。

集群任务失败

kcctl operation list -c demo
kcctl get cluster demo -o yaml
kcctl get node
kcctl resource list

通过操作与日志定位具体步骤和节点。离线安装核对版本、架构和资源包；镜像拉取失败核对镜像仓库地址、认证和网络。提交 Issue 时提供版本、拓扑、脱敏后的错误和操作 ID，移除密码、token、私钥与 kubeconfig 凭据。

4.8 - 镜像仓库

Registry 资源用于描述 Kubernetes 镜像仓库或给 containerd 添加镜像拉取配置。它与平台离线资源包不是同一种对象，创建 Registry 也不会自动把镜像同步到仓库。

创建 Registry 资源

以下是管理网络中 HTTP 镜像仓库的例子。生产仓库应按实际情况配置 HTTPS、CA 和认证；完整参数见命令帮助。

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

需要认证时可通过 --auth-username 和 --auth-password 配置，注意命令历史和终端日志中的凭据暴露。使用 HTTPS 时核对 --ca 与 --skip-tls-verify，不要直接沿用 HTTP 示例配置。

为集群选择仓库

kcctl create cluster --name demo --master 192.168.10.21 \
  --k8s-version v1.37.0 --cri containerd --cri-version 2.2.4 \
  --cni calico --cni-version v3.31.5 \
  --image-registry internal --cri-registry internal

• --image-registry 选择用于 Kubernetes 镜像的 Registry 资源。
• --cri-registry 将 Registry 资源的配置加入 containerd；可按需要指定多个资源。
• 未指定镜像仓库时，各组件采用各自的默认值和适用的 Agent 镜像源配置。不要假定 Kubernetes、Calico 等组件都从同一个默认仓库拉取。

创建前把所需镜像放入仓库，并检查集群节点实际可访问的镜像路径、认证和证书。离线安装还要满足资源包要求。

5 - 常见问题

5.1 - 集群创建排障

本页适用于 1.7。旧版 v1.2.1 的 Calico 下载问题及临时处理方法保留在1.2 历史文档，不应直接应用于 1.7。

提交后集群没有就绪

kcctl operation list -c demo
kcctl get cluster demo -o yaml
kcctl get node

继续查看 Operation 详情和日志。请求已接受、Operation 已结束和 Kubernetes 节点就绪需要分别确认。

离线包或镜像错误

用 kcctl resource list 核对版本和架构；通过失败步骤日志确认镜像路径、认证和网络。参考离线创建集群。

平台或 Agent 异常

运行 kcctl status、kcctl doctor，检查 API 入口、服务和 SSH 访问。平台使用的 SSH 凭据应为私钥；不要把公钥路径填入私钥字段。

排查顺序和日志命令见平台诊断；重试和取消见操作与日志。

6 - 贡献指南

文档存放在 kubeclipper.github.io，中文和英文分别位于 content/zh-cn 与 content/en。提交修改时请尽量同步两种语言；暂时无法翻译时，在 PR 中说明。

1. Fork 文档仓库，修改对应页面。功能和版本信息请以已发布的软件版本为准，不把规划中的能力写成现状。
2. 按仓库 README 安装依赖，在本地预览，并运行 make check 检查多版本构建和站内链接。
3. 提交 Pull Request，说明改了哪些页面、依据是什么，以及本地检查结果。若是一组面向用户的重要变化，可同时在项目动态新增一篇简短更新。
4. 合并并发布后，核对线上页面与入口。构建成功不等于线上内容已经更新。

发现错误但暂时无法修改时，可提交文档问题。软件问题请提交到项目仓库。