使用手册

• 1: 创建集群
• 2: 集群托管
• 3: 集群管理
• 4: 节点管理
• 5: 访问控制
• 6: 操作与日志
• 7: 平台诊断
• 8: 镜像仓库

1 - 创建集群

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

控制台创建

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

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

CLI 创建与验证

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

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 镜像仓库。

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 - 节点管理

区域管理

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

节点管理

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

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 控制台并执行命令。

启用/禁用节点

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

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，就可以正常访问平台并执行角色权限内操作。

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 状态确认结果。集群删除后还要检查平台列表和节点残留。平台问题参考诊断指南。

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 凭据。

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 等组件都从同一个默认仓库拉取。

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