Installation

以下章節包含對安裝失敗進行故障排除或取得協助的提示。

登入 Harvester 安裝程式(即時作業系統)

使用者可以按下組合鍵 CTRL + ALT + F2 切換到另一個 TTY,並使用以下憑證登入:

使用者:rancher
密碼:rancher

滿足硬體需求

檢查您的硬體是否滿足最低需求以完成安裝。

卡在 `Loading images. This may take a few minutes...`

由於系統沒有預設路由,您的安裝程式可能會「卡在」這個狀態。您可以透過執行以下命令來檢查路由狀態:

$ ip route
default via 10.10.0.10 dev mgmt-br proto dhcp        <-- 是否存在預設路由?
10.10.0.0/24 dev mgmt-br proto kernel scope link src 10.10.0.15

檢查您的 DHCP 伺服器是否提供預設路由選項。附加 /run/cos/target/rke2.log 的內容也會有所幫助。

如需更多資訊,請參閱 DHCP Server Configuration。

修改代理節點上的叢集權杖

當代理節點無法加入叢集時,可能與叢集權杖與伺服器節點權杖不一致有關。為了確認問題,請連接到您的代理節點(例如使用 SSH)並使用以下命令檢查 rancherd 服務日誌:

$ sudo journalctl -b -u rancherd

如果代理節點中設定的叢集權杖與伺服器節點權杖不符,您將發現多條以下訊息:

msg="Bootstrapping Rancher (v2.7.5/v1.25.9+rke2r1)"
msg="failed to bootstrap system, will retry: generating plan: response 502: 502  Bad Gateway getting cacerts: <html>\r\n<head><title>502 Bad Gateway</title></head>\r\n<body>\r\n<center><h1>502 Bad Gateway</h1></center>\r\n<hr><center>nginx</center>\r\n</body>\r\n</html>\r\n"

請注意,Rancher 版本和 IP 位址取決於您的環境,可能與上述訊息不同。

要修復此問題,您需要更新 rancherd 配置檔案 /etc/rancher/rancherd/config.yaml 中的權杖值。

例如,如果伺服器節點中設定的叢集權杖是 ThisIsTheCorrectOne,您將按如下方式更新權杖值:

token: 'ThisIsTheCorrectOne'

為確保變更在重新啟動後持久化,請更新作業系統配置檔案 /oem/90_custom.yaml 的 token 值:

name: Harvester Configuration
stages:
  ...
  initramfs:
  - commands:
    - rm -f /etc/sysconfig/network/ifroute-mgmt-br
    files:
    - path: /etc/rancher/rancherd/config.yaml
      permissions: 384
      owner: 0
      group: 0
      content: |
        server: https://$cluster-vip:443
        role: agent
        token: "ThisIsTheCorrectOne"
        kubernetesVersion: v1.25.9+rke2r1
        rancherVersion: v2.7.5
        rancherInstallerImage: rancher/system-agent-installer-rancher:v2.7.5
        labels:
         - harvesterhci.io/managed=true
        extraConfig:
          disable:
          - rke2-snapshot-controller
          - rke2-snapshot-controller-crd
          - rke2-snapshot-validation-webhook
      encoding: ""
      ownerstring: ""

備註

要查看當前叢集權杖值,請登入您的伺服器節點(例如使用 SSH)並查看檔案 /etc/rancher/rancherd/config.yaml。例如,您可以執行以下命令僅顯示權杖的值:

$ sudo yq eval .token /etc/rancher/rancherd/config.yaml

檢查 Harvester 元件的狀態

在檢查 Harvester 元件的狀態之前,請按照指南取得 Harvester 叢集的 kubeconfig 檔案副本。

取得 kubeconfig 檔案副本後,針對叢集執行以下腳本以檢查每個元件的就緒狀態。

Harvester 元件腳本

#!/bin/bash

cluster_ready() {
  namespaces=("cattle-system" "kube-system" "harvester-system" "longhorn-system")
  for ns in "${namespaces[@]}"; do
    pod_statuses=($(kubectl -n "${ns}" get pods \
      --field-selector=status.phase!=Succeeded \
      -ojsonpath='{range .items[*]}{.metadata.namespace}/{.metadata.name},{.status.conditions[?(@.type=="Ready")].status}{"\n"}{end}'))
    for status in "${pod_statuses[@]}"; do
      name=$(echo "${status}" | cut -d ',' -f1)
      ready=$(echo "${status}" | cut -d ',' -f2)
      if [ "${ready}" != "True" ]; then
        echo "pod ${name} is not ready"
        false
        return
      fi
    done
  done
}

if cluster_ready; then
  echo "cluster is ready"
else
  echo "cluster is not ready"
fi

API
```
$ curl -fk https://<VIP>/version
```
備註
您必須將 <VIP> 替換為實際的 VIP,這是連結中 kube-vip.io/requestedIP 的值。

收集故障排除資訊

在報告安裝失敗時,請在錯誤報告中包含以下資訊:

安裝失敗的螢幕截圖。
系統資訊和日誌。
- 從 v1.0.2 開始提供
請按照登入 Harvester 安裝程式(即時作業系統)中的指南登入。並執行命令以產生包含故障排除資訊的壓縮檔:
```
supportconfig -k -c
```
命令輸出訊息包含產生的壓縮檔路徑。例如,在以下範例中,路徑為 /var/loq/scc_aaa_220520_1021 804d65d-c9ba-4c54-b12d-859631f892c5.txz:

備註
如果在 Harvester 配置檔案中將 install.debug 欄位設定為 true,失敗的 PXE Boot 安裝會自動產生壓縮檔。

Harvester 控制台在第 0 天安裝後顯示「Setting up Harvester」

問題描述

成功安裝後,Harvester 控制台持續顯示 Setting up Harvester。雖然大多數 UI 和 CLI 操作不受影響,但嘗試開始升級會被阻止。

執行命令 kubectl get managedchart -n fleet-local harvester -oyaml 後會顯示以下資訊:

...
status:
  conditions:
  - lastUpdateTime: "2025-10-22T08:01:18Z"
    message: 'NotReady(1) [Cluster fleet-local/local]; daemonset.apps harvester-system/harvester-network-controller
      modified {"spec":{"template":{"spec":{"containers":[{"args":["agent"],"command":["harvester-network-controller"],
      "env":[{"name":"NODENAME","valueFrom":{"fieldRef":{"apiVersion":"v1","fieldPath":"spec.nodeName"}}},
      {"name":"NAMESPACE","valueFrom":{"fieldRef":{"apiVersion":"v1","fieldPath":"metadata.namespace"}}}],
      "image":"rancher/harvester-network-controller:master-head","imagePullPolicy":"IfNotPresent","name":"harvester-network",
      "resources":{"limits":{"cpu":"100m","memory":"128Mi"},"requests":{"cpu":"10m","memory":"64Mi"}},
      "securityContext":{"privileged":true},"terminationMessagePath":"/dev/termination-log","terminationMessagePolicy":"File",
      "volumeMounts":[{"mountPath":"/dev","name":"dev"},{"mountPath":"/lib/modules","name":"modules"}]}]}}}};'
    status: "False"
    type: Ready

根本原因

Harvester 控制台執行以下命令以確定 harvester ManagedChart(在 fleet-local 命名空間中)的狀態是否為 Ready。

cmd := exec.Command("/bin/sh", "-c", kubectl -n fleet-local get ManagedChart harvester -o jsonpath='{.status.conditions}' |
jq 'map(select(.type == "Ready" and .status == "True")) | length')

Fleet 使用 ManagedChart CRD 透過 GitOps 管理資源。如果直接修改任何這些資源,ManagedChart 會記錄並標記偏差。在上述範例中,由於自訂映像標籤直接套用到 harvester-system/harvester-network-controller DaemonSet,因此發生錯誤。

要檢索 ManagedChart 資源的完整清單,請執行命令 kubectl get bundle -n fleet-local mcc-harvester -oyaml。

apiVersion: fleet.cattle.io/v1alpha1
kind: Bundle
metadata:
  name: mcc-harvester
  namespace: fleet-local
spec:
  resources:
  - content: H4s...===
    encoding: base64+gz
    charts/harvester-network-controller/templates/daemonset.yaml
  - content: ...

解決方法

您可以執行以下任一操作:

還原對受影響資源所做的直接變更。
使用 kubectl edit managedchart -n fleet-local harvester 以所需的自訂配置更新 ManagedChart CRD。

登入 Harvester 安裝程式(即時作業系統)​

滿足硬體需求​

卡在 Loading images. This may take a few minutes...​

修改代理節點上的叢集權杖​

檢查 Harvester 元件的狀態​

收集故障排除資訊​

Harvester 控制台在第 0 天安裝後顯示「Setting up Harvester」​

問題描述​

根本原因​

解決方法​

相關問題​