版本：v26.09

常见问题解答（FAQ） ​

本文档旨在提供常见的安装部署问题，并给出可用的解决手段。

1. calico组件的install-cni容器一直重启，出现calico-node在init阶段（1/3）且处于CrashLoopbackOff状态 ​

  • 问题原因

    可用在节点上执行ip route查看路由信息，该问题通常由以下两种情况引起。

    1. 节点上缺少默认路由。
    2. 节点上存在多条默认路由，且分配给集群部署的不是最高优先级路由（metric数值越小优先级越高）。

  • 解决方法

    针对问题原因1，添加默认路由，执行下面命令。

    bash
    ip route add default via 192.168.100.1 dev eth0 proto static metric 100

    针对问题原因2，删除多余的默认路由，执行下面命令。

    bash
    ip route del default via 192.168.90.1 dev eth1

  • 问题拓展

    Calico要求节点必须有一个优先级最高的默认路由，本质上是为了确保集群内外所有流量都能在节点这个三层路由器上被正确转发。

    默认路由的配置一般在/etc/sysconfig/network-scripts目录下，定义和配置系统网络接口（网卡）的持久化配置文件。当系统重启或网络服务重启时，系统会读取这些文件来设置IP地址、网关、DNS等信息。

2. calico-node频繁重启，容器陷入“启动-探测失败-重启”的死循环 ​

  • 问题原因

    该问题通常由设置的initialDelaySeconds过短导致的，Pod还未完成初始化、建立连接、加载配置等羁绊操作，kubelet就开始探测calico-node的健康状态。

  • 解决方法

    设置合适的延迟时间，告诉kubelet，在容器启动后，先等待一段时间，然后再执行第一次探测操作，执行如下命令进行设置。

    bash
    # 编辑K8s资源yaml，找到readinessProbe就绪探针相关，新增initialDelaySeconds字段
kubectl edit ds -n kube-system calico-node

    initialDelaySeconds推荐设置如下，实际场景中根据实际情况设置。

    • 小集群（10节点以下），设置为30，足够calico完成基本初始化。
    • 大集群（10节点以上），设置为60，节点多、资源竞争激烈，需要更长的启动时间。

3. calico-node处于0/1的Running状态 ​

  • 详细现象

    查看详细信息，如下。

    • 节点状态为NotReady：这是最直观的表现。通过kubectl get nodes命令，你会发现这个节点的状态不是Ready，而是NotReady。
    • calico-nodePod探针失败：查看calico-nodePod的详情（kubectl describe pod ...）或日志，会反复出现类似以下的错误信息。
      • Readiness probe failed: calico/node is not ready: BIRD is not ready
      • BGP not established with X.X.X.X （X.X.X.X通常是其他节点的IP）
      • Error querying BIRD: unable to connect to BIRDv4 socket
    • Pod跨节点通信中断：因为BGP会话未能建立，路由信息无法同步。最直接的后果是，当前节点上的Pod无法与集群内其他节点上的Pod正常通信。

  • 问题原因

    calico-node的IP_AUTODETECTION_METHOD这个字段设置错误，导致节点网络不通。

  • 解决方法

    执行如下命令修改环境变量的取值。

    bash
    # 编辑K8s资源yaml，设置IP_AUTODETECTION_METHOD环境变量
kubectl edit ds -n kube-system calico-node

    常见设置取值如下。

    • skip-interface=nerdctl*：openFuyao设置的默认策略，跳过nerdctl前缀的网卡，选择第一个有效网卡的IP。
    • can-reach=192.168.100.5：直接指定目标地址的网卡IP。
    • interface=eth4：使用eth4网卡上的IP。

  • 问题拓展

    IP_AUTODETECTION_METHOD这个字段决定了Calico如何在多网卡的节点上，自动选择用于建立BGP邻居和封装流量的正确IP地址。

4. 引导集群安装业务集群时，业务集群节点的bkeagent无法连接引导集群的APIServer，导致集群安装失败 ​

  • 问题原因

    bkeagent启动的时候会指定参数--kube-config配置其监控的APIServer，bkeagent启动后会判断其调谐处理的CRD是否在监控的APIServer中下发，这就会触发bkeagent尝试连接引导集群的APIServer，出现了下面的报错日志信息。

    # v25.12及之前版本日志是/var/log/bkeagenbt.log，之后的版本是/var/log/openFuyao/bkeagent.log
The CRD cannot be installed in the target cluster, xxx

    查看配置文件（v25.12及之前版本日志是/etc/bkeagent/config，之后的版本是/etc/openFuyao/bkeagent/config），发现server对应的IP地址并非给定的引导节点的地址。

  • 解决方法

    执行下面的命令重置引导节点，然后指定IP地址进行初始化。

    bash
    # 重置引导节点
bke reset --all --mount
# 指定IP地址进行初始化
bke init --hostIP=1.2.3.4

5. 引导集群部署openFuyao管理面时，coredns处于CrashLoopbackOff状态 ​

  • 详细信息

    查看coredns的详细日志（kubectl logs -n kube-system coredns-xxx），出现下面的日志（实际日志IP地址和Port端口不同）。

    [ERROR] plugin/errors: 2 . NS: read udp 100.20.0.15:59690->100.10.0.10:53: i/o timeout
[FATAL] plugin/loop: Loop(127.0.0.1:34812 -> :53) detected for zone ".", see https://coredns.io/plugins/loop#troubleshooting. Query: "HINFO ***"

  • 问题原因

    出现上面的日志，说明coredns进行域名解析时陷入了loop死循环。

  • 解决方法

    kubectl get cm -n kube-system coredns -o yaml可以看到forward设置为/etc/resolv.conf，这导致了无其他可用的DNS服务器时就会使用coredns的server ip作为服务器进行域名解析，最后导致死循环。

    执行下面命令，设置服务器。

    bash
    # 设置forward为forward . 8.8.8.8，如果有可用的DNS服务器，可以设置为对应的IP地址
kubectl edit cm -n kube-system coredns

  • 问题拓展

    forward插件是将集群内无法解析的DNS请求，转发给指定的上游DNS服务器。

6. 使用虚拟IP部署高可用集群失败，使用bke reset进行节点重置后，再次使用已占用的虚拟IP部署高可用集群，部署失败 ​

  • 问题原因

    高可用集群的keepalived组件会将虚拟IP绑定在高可用集群的某个节点上，使用bke reset在每个节点上重置环境后，并不会将虚拟IP从已绑定的节点上解绑，导致二次使用时，出现报错，最终导致集群无法拉起。

  • 解决方法

    登录到首次安装的高可用集群的 Master 节点上，执行下面的命令解绑虚拟IP。

    bash
    # 查看节点的网卡绑定的IP地址
ip addr
# 如果查询到绑定了虚拟IP，执行下面的命令进行解绑，vip替换为实际使用的寻IP，eth0替换为实际绑定的网卡
ip addr del <vip> dev <eth0>

7. openFuyao安装的集群，除了管理面删除集群外，后端如何删除集群 ​

正式步骤、删除顺序、清理范围与成功判据见集群卸载及通过后台（命令行）删除业务集群。

引导集群或者管理集群的installer-service会从APIServer中读取BKECluster数据。除管理面删除外，也可在引导节点或管理集群终端执行：

bash
# 查询集群信息
kubectl get bc -A
# 将占位符替换为实际命名空间与名称后编辑
kubectl edit bc -n <命名空间> <名称>

在打开的 YAML 编辑器中设置以下两项（彻底清理目标节点时）：

yaml
metadata:
  annotations:
    bke.bocloud.com/ignore-target-cluster-delete: "false"
spec:
  reset: true

8. 后端如何实现openFuyao集群的扩缩容操作 ​

openFuyao管理面提供集群的生命周期管理能力，包括集群的扩容、缩容、升级、安装和卸载等能力。这里提供后端进行集群的扩缩容处理，需要在集群处于健康的情况下进行操作，集群处于非健康状态时，扩缩容操作可能会出现错误。

  • 缩容操作，将节点从已有集群中删除。

    查看已有BKENode资源。

    bash
    # bke-cluster替换为实际集群的信息
kubectl get bn -n bke-cluster

    删除对应的BKENode资源。

    bash
    # bke-cluster-n1替换为实际的节点名称
kubectl delete bn -n bke-cluster bke-cluster-n1

    再次执行查看已有BKENode资源命令发现无对应节点即删除成功。

  • 扩容操作，将新节点加入到已有集群中。

    编写新的节点的配置文件(newNode.yaml)。

    yaml
    apiVersion: bke.bocloud.com/v1beta1
kind: BKENode
metadata:
  name: bke-cluster-n1
  namespace: bke-cluster
  labels:
    cluster.x-k8s.io/cluster-name: bke-cluster
spec:
  hostname: n1
  ip: <node-ip>
  password: '<encrypted>'
  port: "22"     
  role:
  - node
  username: root

    执行下面命令实现扩容操作。

    bash
    kubectl apply -f newNode.yaml

    执行查看已有BKENode资源命令发现对应节点Ready即扩容成功。

注：v25.12及之前版本参考以下指南操作。

  • 缩容操作，将节点从已有集群中删除。

    编辑BKECluster资源。

    bash
    # bke-cluster替换为实际集群的信息
kubectl edit bc -n bke-cluster bke-cluster

    设置预约删除的节点。

    yaml
    metadata:
  annotations:
    # 节点预约删除，节点删除是个危险的动作故增加此注释做二次确认，默认无
    # 删除节点时除从spec中将节点删除，还需将要删除的节点ip填入，多个ip之间使用‘,’分割
    # 两步操作少之其一都不会触发节点删除
    bke.bocloud.com/appointment-deleted-nodes: "172.100.200.10"

    将节点信息从Spec中删除。

    yaml
    spec:
  clusterConfig:
    nodes:                
    - hostname: master-1  
      ip: 172.100.200.10
      username: root      
      password: password0
      port: "22"
      role:             
      - master
      - etcd

  • 扩容操作，将新节点加入到已有集群中。

    编辑BKECluster资源。

    bash
    # bke-cluster替换为实际集群的信息
kubectl edit bc -n bke-cluster bke-cluster

    将节点信息加入到Spec中。

    yaml
    spec:
  clusterConfig:
    nodes:                
    - hostname: master-1  
      ip: 172.100.200.10
      username: root      
      password: password0
      port: "22"
      role:             
      - master
      - etcd

9. 节点 iptables FORWARD 链默认策略为 DROP 时，导致容器网络通信异常、集群初始化或创建失败 ​

  • 详细现象

    节点上存在 iptables 且 FORWARD 链默认策略为 DROP 时，可能出现以下一种或多种现象。

    1. bke init 初始化引导节点后，引导节点上的容器（镜像仓库、YUM 仓库、Chart 仓库）服务正常启动，但引导集群（k3s）中的 Pod 间通信异常或 Pod 访问外部服务超时。
    2. 引导集群部署 openFuyao 管理面时，部分 Pod（如 cluster-api-provider-bke 控制器）出现网络不通，日志中存在连接超时或拒绝等报错。
    3. openFuyao 前端管理面访问超时，在引导节点上通过 curl 访问后端服务可正常输出，但在其余节点上执行 curl 访问则超时或不通。
    4. 业务集群节点初始化或节点加入集群过程中，镜像拉取超时，节点无法加入集群。
    5. 集群创建后，跨节点 Pod 通信失败，CoreDNS 解析超时，Calico BGP 会话无法建立。

  • 解决方法

    在出现上述现象的节点上，手动将 iptables FORWARD 链默认策略修改为 ACCEPT。

    bash
    # 查看当前 FORWARD 链默认策略
iptables -t filter -nvL FORWARD

# 将 FORWARD 链默认策略设置为 ACCEPT
iptables -t filter -P FORWARD ACCEPT

    如需在引导节点初始化之前预先设置，可以在执行 bke init 之前执行上述命令。

  • 问题拓展

    iptables FORWARD 链默认策略为 DROP 的常见来源包括：

    • 系统安装时启用了 firewalld 防火墙，firewalld 默认将 FORWARD 链策略设为 DROP。即使后续停止了 firewalld 服务，已设置的 iptables 策略不会自动恢复为 ACCEPT。
    • 安全加固场景中，管理员手动将 FORWARD 链策略设为 DROP 以限制未授权的流量转发。
    • 部分 Linux 发行版（如某些最小化安装的 CentOS/RHEL）默认将 FORWARD 策略设为 DROP。

10. 安装过程中 /etc/resolv.conf 被 NetworkManager 刷新为默认内容，导致节点网络异常 ​

  • 问题原因

    安装过程中，NetworkManager（NM）服务会管理节点的 DNS 配置，并将 /etc/resolv.conf 刷新为默认内容，覆盖已配置的有效 DNS 服务器，导致节点域名解析异常，进而引发网络不通、镜像拉取失败、组件通信超时等问题。

  • 解决方法

    修改 NetworkManager 的配置，设置 dns=none，禁止 NetworkManager 管理 DNS 配置。

    bash
    # 编辑 NetworkManager 主配置文件
vi /etc/NetworkManager/NetworkManager.conf

    在 [main] 段中新增或修改如下配置。

    ini
    [main]
dns=none

    保存后重启 NetworkManager 服务使配置生效，并确认 /etc/resolv.conf 中的 DNS 配置正确。

    bash
    # 重启 NetworkManager 服务
systemctl restart NetworkManager
# 确认 resolv.conf 内容未被覆盖为默认配置
cat /etc/resolv.conf

  • 问题拓展

    dns=none 表示 NetworkManager 不再写入或更新 /etc/resolv.conf，由管理员自行维护 DNS 配置。安装前建议提前配置，避免安装过程中被意外刷新。

11. 引导节点 k3s 容器一直间断重启 ​

  • 详细现象

    在引导节点执行 ps -ef | grep k3s 和 nerdctl ps -a，发现k3s server会间断重启。 使用nerdctl logs kubernetes发现日志中有 failed to run iptables command to create KUBE-ROUTER-OUTPUT chain due to running [/bin/aux/iptables -t filter -S KUBE-ROUTER-OUTPUT 1 --wait]: exit status 3。

  • 问题原因

    执行lsmod | grep -E 'ip_tables|iptable_filter'无输出。 出现上述现象的原因是k3s在启动网络组件时，因为宿主机内核的iptables相关模块缺失，导致网路策略控制器初始化失败，触发panic并退出。

  • 解决方法

    可以执行以下命令加载对应模块：

    bash
    modprode ip_tables
modprode iptables_filter
modprode iptables_nat

12. 单节点集群两个coredns pod中一个会偶发Pending ​

  • 详细现象

    创建的单节点集群执行kubectl get pod -n kube-system | grep coredns发现一个状态是Running，一个状态是Pending。

  • 解决方法

    执行以下命令将 CoreDNS 副本降为 1 即可。对于单节点环境，1 个 CoreDNS 副本已经完全足够提供 DNS 解析服务。

    bash
    kubectl scale deployment coredns --replicas=1 -n kube-system

13. 配置 chart 类型 addon 时 chartRepo 校验失败，或安装过程中 chart 组件拉取失败 ​

  • 详细现象

    1. 创建集群时配置了 type: chart 的 addon（如 logging-package），bke cluster create 报错类似：

      text
      failed calling webhook "vbkecluster.kb.io": ... context deadline exceeded

      或 Validating Webhook 超时（默认约 10s），无法创建 BKECluster。

    2. 集群创建已通过，但安装 chart 组件时拉取失败，日志类似：

      text
      failed to pull chart: ... Get "https://<chartRepo-ip>:443/v2/charts/...": connection reset by peer

      实际请求落到了 chartRepo 的 IP，而不是域名。

  • 问题原因

    1. 配置了 chart 类 addon 后，bke-controller-manager 的 Validating Webhook 会对 chartRepo 做连通性探测。探测耗时可能超过 webhook 默认超时（10s），导致 admission 超时失败。
    2. bke-controller-manager 默认 dnsPolicy 为 ClusterFirst，依赖集群 DNS（CoreDNS）。在 CoreDNS 未就绪、不可用，或 Pod 无法正确解析外网域名时，ResolveReachableChartRepo 会回退到 chartRepo.ip；对公有仓使用 HTTPS 直连 IP 时，常出现 TLS/SNI/CDN 导致的 connection reset by peer，chart 拉取失败。

  • 解决方法

    场景一：chartRepo 校验 / Webhook 超时

    将 vbkecluster.kb.io 的 webhook 超时延长为 30s（按实际索引调整；可用下面命令确认 webhook 下标）。

    bash
    # 查看 vbkecluster.kb.io 在 webhooks 列表中的下标
kubectl get validatingwebhookconfiguration bke-validating-webhook-configuration \
  -o jsonpath='{range .webhooks[*]}{.name}{"\n"}{end}' | nl -v 0

# 将对应下标的 timeoutSeconds 设置为 30（示例中假设下标为 0）
kubectl patch validatingwebhookconfiguration bke-validating-webhook-configuration --type json -p '[
  {"op":"replace","path":"/webhooks/0/timeoutSeconds","value":30}
]'

    修改后重新执行 bke cluster create。

    场景二：安装过程中 chart 组件拉取失败

    将 cluster-system 命名空间下 bke-controller-manager 的 dnsPolicy 从默认的 ClusterFirst 改为 None，使其使用 Deployment 中已配置的 dnsConfig.nameservers（如 8.8.8.8）解析外网域名，避免错误回退到 chartRepo IP。

    bash
    kubectl -n cluster-system patch deployment bke-controller-manager --type strategic -p '{
  "spec": {
    "template": {
      "spec": {
        "dnsPolicy": "None"
      }
    }
  }
}'
kubectl -n cluster-system rollout status deployment/bke-controller-manager

    确认 Pod 生效：

    bash
    kubectl -n cluster-system get pod -l control-plane=controller-manager \
  -o jsonpath='{.items[0].spec.dnsPolicy}{"\n"}'
# 期望输出：None

    然后按下面任一方式重试 chart 安装：

    1. 推荐：确认 dnsPolicy / chartRepo 已可达后，删除并重建集群重新安装。

    2. 从 status.addonStatus 移除失败项，再打 retry 注解触发调谐：

      bash
      # 步骤 1：移除失败的 chart 项（示例为 logging-package；请按实际名称/命名空间修改）
kubectl -n <bke-ns> get bkecluster <bke-name> -o json | \
  jq '(.status.addonStatus) |= map(select(.name != "logging-package"))' | \
  kubectl -n <bke-ns> replace --subresource=status -f -

# 步骤 2：打 retry 注解，触发重新调谐
kubectl -n <bke-ns> annotate bkecluster <bke-name> bke.bocloud.com/retry=

    3. 手工用 helm/OCI 将 chart 安装到目标集群。

  • 问题拓展

    • 延长 webhook 超时只能缓解连通性探测过慢导致的 admission 失败，不能替代 chart 仓库真实可达。
    • dnsPolicy: None 后，Pod 完全依赖 dnsConfig 中的 nameserver；请确认 bke-controller-manager 的 dnsConfig.nameservers 已配置且可访问外网 DNS。
    • 离线或无法访问公网场景，建议将 chart 上传到引导节点本地 chart 仓库（如 38080），并把 chartRepo 指向该可达地址，而不是依赖公网 cr.openfuyao.cn。
在GitCode上查看源文件

遵循 木兰宽松许可证第2版（MulanPSL2）

版权所有 © 2026 openFuyao 保留一切权利ICP备案号：粤A2-20044005号-306粤公网安备44030002007300号
隐私政策法律声明关于cookies
隐私政策法律声明关于cookies
遵循木兰宽松许可证第2版（MulanPSL2）
版权所有 © 2026 openFuyao 保留一切权利
粤公网安备44030002007300号ICP备案号：粤A2-20044005号-306