Rancher 新建托管集群（uat1）节点注册失败排查与修复报告

日期：2026-07-30
场景：在 Rancher（v2.14.3，https://ai-ear.cn:16443）中新建 RKE2 托管集群 uat1，按生成的注册命令在节点 sza122031.local（192.168.122.31）执行 system-agent-install.sh 失败
执行脚本：worker/rke2/branch/new_cluster_server.sh

1. 问题总览

注册脚本在 .31 上执行失败，且修复后 provisioning 过程中又连续暴露两个问题，共 3 个故障点：

#	故障点	报错特征	根因
1	system-agent 安装直接退出	`Aborting system-agent installation due to requested strict CA verification with no CA checksum provided`	Rancher `agent-tls-mode` 默认为 strict，但证书是公共 CA（DigiCert）签发，无内部 CA 可下发
2	RKE2 安装器镜像拉取失败	`http: server gave HTTP response to HTTPS client`（拉取 `192.168.122.156:30000/...`）	私有仓库为 HTTP，集群未配置 registry mirror 的 `http://` endpoint
3	traefik Pod 无法创建	`plugin type="portmap" failed (add): failed to open iptables: exec: "iptables": executable file not found`	新节点模板精简，未安装 iptables 二进制（hostPort 的 portmap 插件依赖宿主机 iptables）

2. 排查与修复过程

2.1 STRICT_VERIFY 导致安装中止

排查：手工带 sh -x 重跑下载的 system-agent-install.sh，发现脚本内嵌 export STRICT_VERIFY='true'，未传 --ca-checksum 即 fatal 退出；同时验证 curl https://ai-ear.cn:16443/cacerts 返回 0 字节（Rancher 使用公共 CA 签发的 ai-ear.cn 证书，无内部 CA 可下发），因此 --ca-checksum 路线不可行。

修复（推荐做法：公共 CA 证书应使用 system-store 模式）：

bash

# 在 Rancher 所在集群执行
kubectl patch settings.management.cattle.io agent-tls-mode \
  --type merge -p '{"value":"system-store"}'

# 注册节点时，将下载脚本中的 STRICT_VERIFY 置为 false（已写入脚本文件）
curl -fL https://ai-ear.cn:16443/system-agent-install.sh \
  | sed "s/^export STRICT_VERIFY='true'/export STRICT_VERIFY='false'/" \
  | sudo sh -s - --server https://ai-ear.cn:16443 --label 'cattle.io/os=linux' \
       --token <TOKEN> --etcd --controlplane --worker

branch/new_cluster_server.sh 已更新为上述带 sed 的版本。公共 CA（DigiCert）在 Rocky Linux 系统 CA 信任库中，system-store 模式下 agent 可正常完成 TLS 校验。

2.2 私有镜像仓库 HTTP 被当作 HTTPS 访问

排查：journalctl -u rancher-system-agent 显示拉取 192.168.122.156:30000/rancher/system-agent-installer-rke2:v1.35.6-rke2r1 时报 http: server gave HTTP response to HTTPS client；节点上 /etc/rancher/agent/registries.yaml 为 {"configs":{},"mirrors":null}，集群 spec 中 registries 为空（镜像地址由 Rancher 全局 system-default-registry 改写，但缺少 mirror endpoint 声明）。

修复：

bash

kubectl patch clusters.provisioning.cattle.io -n fleet-default uat1 --type merge -p '{
  "spec":{"rkeConfig":{"registries":{"mirrors":{
    "192.168.122.156:30000":{"endpoint":["http://192.168.122.156:30000"]}
  }}}}
}'

约 1 分钟后 plan 下发，节点 registries.yaml 自动更新，rke2-server 成功启动。

2.3 节点缺少 iptables 二进制

排查：rke2-traefik Pod 反复 FailedCreatePodSandBox：portmap 插件找不到宿主机 iptables。该节点模板极简（连 iptables.service 单元都不存在）。

修复：

bash

dnf install -y iptables-nft ipset
# /usr/sbin/iptables 就绪后，traefik 自动恢复 1/1 Running

对应到节点初始化规范：init_kernel.sh 第 0 步安装的 iptables-services 正是为此兜底，新节点入网前必须先跑初始化脚本。

3. 修复后状态

uat1 集群节点 sza122031.local Ready（control-plane,etcd，v1.35.6+rke2r1）；
全部 Pod Running/Completed（traefik、cattle-cluster-agent、rancher-webhook 等）；
Rancher 管理对象 c-m-5rvv7vfh：Connected / Ready / AgentDeployed；
machine-plan failed-checksum 为空、plan 完整应用；
第二个节点（custom-aba9e40aa77c）随后正常进入 Provisioning 流程。

遗留观察项：Rancher UI 中 machine/rkecontrolplane 状态滞后显示 Provisioning / Waiting for Cluster control plane to be initialized（集群实际已可用）。期间观察到 agent 经 frp 隧道 watch Rancher API 偶发 HTTP/2 stream reset（每分钟自动重连，不影响 plan 应用与状态上报），状态后续自行收敛；如长时间不收敛可重启 local 集群中的 capi-controller-manager/rancher Pod 触发重新 reconcile。

4. 经验教训（新集群/新节点 checklist）

Rancher 用公共 CA 证书时：安装后立即设置 agent-tls-mode=system-store；注册命令需剔除 STRICT_VERIFY（或用 UI 重新生成）。
私有 HTTP 镜像仓库：新建集群时在 UI「Registries」中配置 mirror endpoint 为 http://<registry>，或事后按 2.2 patch，否则 agent/kubelet 默认走 HTTPS 必然失败。
节点必须先初始化：入网前执行 init_kernel.sh（安装 iptables/ipvsadm、禁用 iptables.service REJECT 规则、内核模块与 sysctl），可规避本报告问题 3 及此前的 REJECT 规则系列故障。
排障路径：journalctl -u rancher-system-agent（节点）→ kubectl get machines.cluster.x-k8s.io -n fleet-default / rkecontrolplanes.rke.cattle.io（Rancher 侧）→ 下游集群 kubectl get pods -A。

附录二：Rancher 域名切换（自签证书）与 admin 密码重置（2026-07-30）

1. 最终域名架构

浏览器 → https://ai-ear.cn:30443
  → 公网服务器 frps:30443（云安全组需放行）
  → frp 隧道（工作站 frpc：30443 → 192.168.122.20:443）
  → 集群 ingress-nginx（TLS 终止，出示 CN=ai-ear.cn 自签证书）
  → Rancher pods（3 副本）

证书体系：cert-manager v1.20.3（helm pull oci://192.168.122.156:30000/cert-manager/cert-manager --version v1.20.3 --plain-http，安装加 --set crds.enabled=true --set global.imageRegistry=192.168.122.156:30000）
自签 CA 链：ClusterIssuer/selfsigned-issuer → 根 CA Certificate/rancher-root-ca（secret cert-manager/rancher-root-ca，10 年）→ ClusterIssuer/rancher-ca-issuer → Certificate/cattle-system/tls-rancher-ingress（CN=ai-ear.cn，SAN 含 rancher.ai-ear.cn，自动续期）
根 CA 公钥备份：worker/rke2/rancher-root-ca.crt（导入客户端信任库可消除 Chrome 证书警告，见第 3 节）
Rancher 配置：hostname=ai-ear.cn、privateCA=true、server-url=https://ai-ear.cn:30443
历史遗留清理：公网 nginx 的 rancher.ai-ear.cn:443 server 块已删除；frp 16443 映射保留但不再是入口

2. 关键坑位记录

2.1 `privateCA=true` 必须预建 tls-ca secret

开启后 chart 会挂载 secret tls-ca（key 必须为 cacerts.pem），缺失则 Rancher Pod 报 FailedMount: secret "tls-ca" not found：

bash

kubectl -n cert-manager get secret rancher-root-ca -o jsonpath='{.data.tls\.crt}' | base64 -d > /root/rancher-root-ca.crt
kubectl -n cattle-system create secret generic tls-ca --from-file=cacerts.pem=/root/rancher-root-ca.crt

开启后 /cacerts 端点开始下发根 CA（新节点注册可用 --ca-checksum，注册脚本已按此更新）。

2.2 NodePort 直连不能作为访问入口

将 rancher svc 改为 NodePort 30443 后直连，TLS 出示的是 Rancher dynamiclistener 内置证书（CN=dynamic，与 SNI 无关），ingress 证书只在 ingress-nginx 层出示。因此 frp 隧道必须指向节点 443（ingress），NodePort 仅保留不用。

2.3 `agent-tls-mode` 变更受 webhook 保护

从 system-store 改回 strict 被 Rancher webhook 拒绝（AgentTlsStrictCheck condition ... isn't 'True'），需等下游集群 agent 全部按新 CA 回连成功后才允许变更。当前保持原状。

3. Chrome 证书警告处理

自签 CA 不在系统信任库，Chrome 报 ERR_CERT_AUTHORITY_INVALID 属预期。临时可「高级 → 继续访问」；彻底解决：将 rancher-root-ca.crt 导入客户端信任库（Linux 放 /etc/pki/ca-trust/source/anchors/ + update-ca-trust；Windows 导入"受信任的根证书颁发机构"；macOS 钥匙串"始终信任"）。根 CA 有效期 10 年，导入一次即可。

4. admin 密码重置实录

现象：bootstrap-secret 中的引导密码登录报"密码错误"。根因：admin 用户对象（user-srdng）的 password 字段为空（hasPw: False），引导流程异常导致引导密码失效。注意：CATTLE_BOOTSTRAP_PASSWORD 环境变量方式对此场景无效（pod 重启后仍无法登录）。

有效重置方法（直接写入 bcrypt 哈希）：

bash

NEWPW=$(openssl rand -hex 12)
HASH=$(htpasswd -bnBC 10 "" "$NEWPW" | tr -d ':\n')   # 无 htpasswd 则 dnf install -y httpd-tools
kubectl patch users.management.cattle.io user-srdng \
  --type merge -p "{\"password\":\"$HASH\",\"mustChangePassword\":true}"

# 验证（HTTP 200 即成功）
curl -sk --cacert rancher-root-ca.crt --resolve ai-ear.cn:443:192.168.122.20 \
  -X POST "https://ai-ear.cn/v3-public/localProviders/local?action=login" \
  -H "Content-Type: application/json" \
  -d "{\"username\":\"admin\",\"password\":\"$NEWPW\"}" -o /dev/null -w "%{http_code}\n"

重置后已用 kubectl set env deploy/rancher -n cattle-system CATTLE_BOOTSTRAP_PASSWORD- 移除注入的环境变量（防止后续重启再次触发重置）。`mustChangePassword=xxx 首次登录 UI 会被强制改密。

5. 当前状态速查（2026-07-30 收尾）

项	状态
Rancher	3/3 Running，https://ai-ear.cn:30443 可登录（admin 密码已重置）
证书	cert-manager 自签 CA 链就绪，`tls-rancher-ingress` CN=ai-ear.cn
server-url	`https://ai-ear.cn:30443`
uat1 集群	machine 被删除，节点 192.168.122.31 已被清理回干净状态，可用 `branch/new_cluster_server.sh`（已更新为 :30443 + `--ca-checksum`）重新注册
导航页	https://ai-ear.cn/doc/ Rancher 卡片已指向 :30443

附录三：内外网域名分离架构（2026-07-30 最终态）

需求

外网：仅需访问 Rancher UI → https://ai-ear.cn:30443（经 frp 隧道）
内网：部署托管集群、agent 回连 → https://ai-ear.cn（443，内网直连集群，不经公网绕圈）

最终架构

访问方	域名	解析路径
公网用户/宿主机浏览器	`https://ai-ear.cn:30443`	公网 DNS → 8.153.84.140 → frps:30443 → frp 隧道 → 192.168.122.20:443（ingress）
公网用户/宿主机浏览器	`https://ai-ear.cn`（文档站）	公网 DNS → 8.153.84.140 → nginx 主站（不受影响）
内网 VM（agent/注册）	`https://ai-ear.cn`（443）	libvirt dnsmasq 静态解析 → 192.168.122.20/21/22 → 直连集群 ingress

实施要点

server-url=https://ai-ear.cn（settings.management.cattle.io）：下游 agent 回连、UI 生成的注册命令均使用内网地址。
内网 DNS 用 libvirt dnsmasq 集中下发（优于逐台改 /etc/hosts）——在宿主机执行（--live --config 热生效+持久化，无需重启网络）：
bash
```
for ip in 192.168.122.20 192.168.122.21 192.168.122.22; do
  virsh -c qemu:///system net-update default add dns-host \
    "<host ip='$ip'><hostname>ai-ear.cn</hostname></host>" --live --config
done
```
dnsmasq 对同名多 IP 轮询返回，具备一定容错。新加入的 VM 自动获得解析，无需任何配置。
坑：静态解析对宿主机本机同样生效（systemd-resolved 会把查询转发到 192.168.122.1），导致宿主机访问 ai-ear.cn 也走内网、文档站打不开。修复：宿主机 /etc/hosts 固定公网 IP（files 优先级高于 DNS）：
bash
```
echo "8.153.84.140 ai-ear.cn" | sudo tee -a /etc/hosts
```
注册脚本 branch/new_cluster_server.sh 已更新：--server https://ai-ear.cn + 从 https://ai-ear.cn/cacerts 动态计算 --ca-checksum。
各节点上临时添加的 /etc/hosts 条目已全部清理，DNS 为唯一解析来源。

验证

内网：集群节点 curl --cacert rancher-root-ca.crt https://ai-ear.cn/healthz → HTTP 200（remote_ip 为 192.168.122.20/21/22 之一，直连）
外网：curl --cacert rancher-root-ca.crt https://ai-ear.cn:30443/healthz → HTTP 200（经 frp 隧道，出示 CN=ai-ear.cn 证书）

Rancher 新建托管集群（uat1）节点注册失败排查与修复报告 ​

1. 问题总览 ​

2. 排查与修复过程 ​

2.1 STRICT_VERIFY 导致安装中止 ​

2.2 私有镜像仓库 HTTP 被当作 HTTPS 访问 ​

2.3 节点缺少 iptables 二进制 ​

3. 修复后状态 ​

4. 经验教训（新集群/新节点 checklist） ​

附录二：Rancher 域名切换（自签证书）与 admin 密码重置（2026-07-30） ​

1. 最终域名架构 ​

2. 关键坑位记录 ​

2.1 privateCA=true 必须预建 tls-ca secret ​

2.2 NodePort 直连不能作为访问入口 ​

2.3 agent-tls-mode 变更受 webhook 保护 ​

3. Chrome 证书警告处理 ​

4. admin 密码重置实录 ​

5. 当前状态速查（2026-07-30 收尾） ​

附录三：内外网域名分离架构（2026-07-30 最终态） ​

需求 ​

最终架构 ​

实施要点 ​

验证 ​

Rancher 新建托管集群（uat1）节点注册失败排查与修复报告

1. 问题总览

2. 排查与修复过程

2.1 STRICT_VERIFY 导致安装中止

2.2 私有镜像仓库 HTTP 被当作 HTTPS 访问

2.3 节点缺少 iptables 二进制

3. 修复后状态

4. 经验教训（新集群/新节点 checklist）

附录二：Rancher 域名切换（自签证书）与 admin 密码重置（2026-07-30）

1. 最终域名架构

2. 关键坑位记录

2.1 `privateCA=true` 必须预建 tls-ca secret

2.2 NodePort 直连不能作为访问入口

2.3 `agent-tls-mode` 变更受 webhook 保护

3. Chrome 证书警告处理

4. admin 密码重置实录

5. 当前状态速查（2026-07-30 收尾）

附录三：内外网域名分离架构（2026-07-30 最终态）

需求

最终架构

实施要点

验证