基本框架

2026-03-21 04:36:06 +08:00
commit de1be1dbe5
125 changed files with 10302 additions and 0 deletions
--- a/docs/01-02-k3s-工作节点.md
+++ b/docs/01-02-k3s-工作节点.md
@@ -0,0 +1,147 @@
+# 01-02-k3s-工作节点与 Traefik 部署配置
+
+> 本文已合并原 `01-02-k3s-工作节点.md`。
+> 目标：完成工作节点加入 + Traefik 入口部署基线，并验证「**入口节点集合**的 `:80` 可达」。
+>
+> 若需一键自动化安装多节点集群，可直接用 `01-07-节点初始化-ansible-实践.md`。
+
+## 前置条件
+
+- 已完成 `01-01-k3s-控制节点含traefik.md`
+- 已拿到 token：默认方案为 `/var/lib/rancher/k3s/server/token`；若控制节点采用**数据盘方案**则为 `/storage/server/token`
+- 控制节点可执行 `kubectl`
+- **方案二（数据盘）**：若工作节点也使用数据盘，需先挂载数据盘并创建 `/storage`
+
+## 工作节点加入集群（在工作节点执行）
+
+与 01-01 存储方案一致：控制节点用默认则工作节点用方案一；控制节点用数据盘则建议工作节点也用方案二，便于统一路径。
+
+### 方案一：默认数据目录
+
+```bash
+curl -sfL https://get.k3s.io | \
+  K3S_URL=https://192.168.2.61:6443 \
+  K3S_TOKEN=<TOKEN> \
+  sh -
+```
+
+### 方案二：数据盘（自定义数据目录）
+
+确保数据盘已挂载到 `/storage` 后执行：
+
+```bash
+curl -sfL https://get.k3s.io | sh -s - agent \
+  --data-dir=/storage \
+  --server https://192.168.2.61:6443 \
+  --token <TOKEN>
+```
+
+将 `<TOKEN>` 替换为从控制节点读取的 token 内容；若控制节点使用数据盘，token 路径为 `/storage/server/token`。
+
+## 防火墙基线（部署即做）
+
+> **执行节点**：在**每台**运行 k3s 且使用 firewalld 的节点上执行（控制节点 + 工作节点）。  
+> **是否必须**：使用 firewalld 的发行版（如 FCOS/Fedora）**必须**执行，否则跨节点流量可能被拦截；未使用 firewalld 的节点可跳过。  
+> 防火墙与下方 Traefik 入口**两者都需要做**，不是二选一。防火墙部分：2.1 脚本 或 2.2 手动，**二选一**即可。
+
+说明（FCOS/Fedora 重点）：
+
+- FCOS/Fedora 默认 firewalld 转发策略较严格。
+- K3s 负责集群网络组件（如 flannel、kube-proxy）与规则下发，但**不会自动完成你宿主机 firewalld 的 zone 接口归类策略**。
+- 入口 Pod（Traefik/svclb-traefik）可能调度到任意节点，且回包路径会经过该节点本地的 `flannel.1` / `cni0`，不一定绕控制节点。
+- 若某个节点上 `flannel.1 <-> cni0` 的转发被 firewalld 拦截，该节点上的入口流量就会在某些调度/流向下异常，即使其它节点正常。
+
+### 2.1 脚本方式（推荐）
+
+脚本实现：等待 `flannel.1`、`cni0` 出现后，将其加入 firewalld 的 `trusted` 区域，并**持久化**（`--permanent` + `--reload`），重启后仍生效。  
+早期排障时，曾只在控制节点手工执行过少量临时放行命令即可恢复访问，那是因为当时入口 Pod 全在控制节点、所有回包都经由控制节点；  
+但在“Traefik 可跑在任意节点、部分节点被选为入口节点”的设计下，每个启用 firewalld 的 k3s 节点都必须持久放行本机 `flannel.1/cni0`，否则一旦入口 Pod 或业务 Pod 调度到该节点，就可能在该节点上重现同类故障。
+
+在**每台** k3s 节点上分别执行：
+
+```bash
+./scripts/diag/firewalld/setup-k3s-firewalld-interfaces.sh
+```
+
+### 2.2 手动方式（不使用脚本）
+
+在**每台** k3s 节点上分别执行：
+
+```bash
+sudo firewall-cmd --zone=trusted --add-interface=flannel.1
+sudo firewall-cmd --zone=trusted --add-interface=cni0
+sudo firewall-cmd --permanent --zone=trusted --add-interface=flannel.1
+sudo firewall-cmd --permanent --zone=trusted --add-interface=cni0
+sudo firewall-cmd --reload
+```
+
+## Traefik 入口节点范围（在控制节点执行，必须做）
+
+为需要对外暴露 80/443 的节点打标签，使 Traefik 的 svclb 调度到这些**入口节点**。按你的节点名和 IP 替换 `ylc61`、`ylc62` 等：
+
+### 3.1 手工方式（直接 kubectl 打标签）
+
+```bash
+# 示例：选择 ylc61/ylc62 作为入口节点
+kubectl label node ylc61 svccontroller.k3s.cattle.io/enablelb=true --overwrite
+kubectl label node ylc62 svccontroller.k3s.cattle.io/enablelb=true --overwrite
+kubectl label node ylc61 svccontroller.k3s.cattle.io/lbpool=edge --overwrite
+kubectl label node ylc62 svccontroller.k3s.cattle.io/lbpool=edge --overwrite
+```
+
+你可以根据需要选择 1 台、2 台、3 台或全部 4 台节点作为入口节点；被打上上述两个标签的节点将承载 Traefik/svclb 暴露的 80/443 入口。
+
+### 3.2 Ansible 方式（推荐，集中管理入口节点）
+
+也可以在 [`ansible/group_vars/all.yml`](../ansible/group_vars/all.yml) 中配置入口节点列表 `k3s_ingress_nodenames`（示例：`ylc61`、`ylc62`），由 `k3s-init-and-install.yml` 自动打标签。
+
+运行：
+
+```bash
+cd ansible
+ansible-playbook -i inventory.ini playbooks/k3s-init-and-install.yml
+```
+
+若 `k3s_ingress_nodenames` 为空（默认），Ansible 会对**所有节点**打入口标签，与早期行为一致；  
+填写后则仅对列出的节点打标签，实现「按需选择入口节点」。
+
+**可选（02-05 / 03-02 矩阵 M1/M3 需要）**：若要用 `02-05-nginx-验证矩阵-一键部署.md` 或 `03-02-k3s-traefik-acme.md` 中 M1（随机一台控制节点）、M3（随机一台工作节点），需为节点打角色标签。在控制节点执行：
+
+```bash
+# 控制节点打标（按实际控制节点名改，可多台）
+kubectl label node ylc61 node-role.kubernetes.io/control-plane= --overwrite
+# 工作节点打标（按实际工作节点名改，可多台）
+kubectl label node ylc62 node-role.kubernetes.io/worker= --overwrite
+kubectl label node ylc63 node-role.kubernetes.io/worker= --overwrite
+```
+
+未打标时，M1/M3 会 Pending，可改用 M2/M4 的 hostname 指定节点或见 02-05 排障小节。
+
+## 验证命令（在控制节点执行）
+
+```bash
+sudo systemctl status k3s-agent --no-pager
+kubectl get nodes -o wide
+kubectl -n kube-system get svc traefik -o wide
+kubectl -n kube-system get pods -l app=svclb-traefik -o wide
+sudo firewall-cmd --zone=trusted --list-interfaces
+
+# 对入口节点的 IP 做 HTTP 验证（示例：入口节点为 192.168.2.61 / 192.168.2.62）
+curl -I --max-time 3 http://192.168.2.61:80
+curl -I --max-time 3 http://192.168.2.62:80
+```
+
+## 预期
+
+- 工作节点显示 `Ready`
+- `trusted` 中可看到 `flannel.1 cni0`
+- 被标记为入口节点的 IP:80（示例中为 `192.168.2.61`、`192.168.2.62`）可返回 Traefik 响应（常见 `404`）
+
+## 失败排查
+
+- 若出现 `502/跨节点不通/admin-prohibited`，看：`06-01-k3s-networkpolicy-故障排查.md`
+
+## 下一步
+
+- `03-01-k3s-traefik-dashboard.md`
+- `04-03-k3s-nginx-demo.md`