对齐文件规范

docs/01-08-双控制节点ha.md

@@ -0,0 +1,93 @@
+# 01-08-双控制节点HA（安装与准备）
+
+## TL;DR
+
+- **自动化验收（基线）**：`./scripts/verify.sh run 01-08`（只做集群可达性基线；HA 加入/切换需按本文手工演练）
+- **你需要准备**：第二个 server、外部 datastore、`6443` LB（HAProxy 等）、维护窗口与备份
+- **成功判据**：能按本文完成外部 datastore 与 LB 的准备清单；并在 `03-08` 中完成加入/切换演练
+- **失败排障**：见本文「排障」小节（datastore/LB/tls-san/6443）
+
+> 本文只讲双控制节点 HA 的安装前准备与基础环境搭建。
+> 具体集群参数切换、server 加入与迁移步骤见 `03-08-k3s-ha-集群配置与切换.md`。
+
+## 前置条件
+
+- 已完成 `01-01-k3s-控制节点含traefik.md`
+- 已完成 `01-02-k3s-工作节点.md`
+- 当前集群运行稳定，可执行维护窗口
+
+## 目标与边界
+
+- 目标：控制平面单点故障时仍可管理集群
+- 边界：家庭网关（如 OpenWrt）可能仍是整体单点
+
+## 安装准备清单
+
+1. 新增第二个 server 节点（示例 `192.168.2.63`）
+2. 准备外部数据存储（MySQL/PostgreSQL/etcd）
+3. 准备 `6443` 负载均衡（HAProxy）
+4. 备份现有 token 与关键配置
+
+### 外部 datastore 与 k3s server 最小示例
+
+以下只给出一个“最小可参考”的 PostgreSQL + k3s server 参数示意，具体地址/账号请按你自己的环境调整：
+
+- **若采用 01-01 的数据盘方案**：在 server 参数中增加 `--data-dir=/storage`，与首节点一致（第二个 server 安装时同样需要）。
+
+```bash
+# 假设外部 PostgreSQL 已创建数据库与账号：
+#   host=192.168.2.50 dbname=k3s user=k3s password=strong-password
+
+# 在首个 server（例如 192.168.2.61）上，默认数据目录：
+sudo k3s server \
+  --datastore-endpoint="postgres://k3s:strong-password@192.168.2.50:5432/k3s?sslmode=disable" \
+  --tls-san 192.168.2.61 \
+  --tls-san 192.168.2.62 \
+  --tls-san 192.168.2.63 \
+  --tls-san 192.168.2.60   # 这里示例为 LB IP
+
+# 若使用数据盘方案，增加 --data-dir=/storage，例如：
+# sudo k3s server --data-dir=/storage \
+#   --datastore-endpoint="postgres://..." --tls-san ...
+```
+
+> 说明：上面的命令仅作为参数示意，实际部署时建议改用 systemd unit 或官方安装脚本的额外参数（`INSTALL_K3S_EXEC=...`），并结合 `03-08-k3s-ha-集群配置与切换.md` 中的步骤执行。
+
+### 从现有 worker 升级为第二控制节点（推荐路径）
+
+在家庭实验室环境中，第二个控制节点通常可以直接复用一台已有的 worker 节点。整体思路是：
+
+1. **确认 worker 节点健康**：  
+   - 已按 `01-02-k3s-工作节点.md` 正常加入集群；  
+   - 无关键 Pod 仅运行在该节点（可先用 `kubectl drain` 或手动迁移工作负载）。
+2. **在 `01-08` 阶段完成外部 datastore 与 LB 准备**：
+   - 不要立即改动现有 server/worker 的 systemd 配置，只确保 datastore/LB 均已就绪。  
+3. **在 `03-09` 中按步骤将该 worker 替换为 server**：  
+   - 停止该节点上的 `k3s-agent` 服务（或执行官方卸载脚本）；  
+   - 使用与首个 server 相同的 token/datastore/LB 地址重新以 `server` 角色安装 k3s；  
+   - 最终形成“2 个 server + 若干 worker”的目标拓扑。
+
+> 具体切换命令与顺序详见：`03-08-k3s-ha-集群配置与切换.md` 中的操作步骤。
+
+## 基础验证
+
+```bash
+kubectl get nodes -o wide
+kubectl get pods -A
+```
+
+## 风险提示
+
+- 这是高级改造，建议在业务稳定后执行
+- 执行前务必做完整备份
+
+## 下一步
+
+## 排障
+
+- **LB 6443 不通**：先在客户端 `curl -k https://<lb_ip>:6443/ping`；再在各 server 检查监听与防火墙放行。
+- **加入第二个 server 后 kubeconfig 指向错误地址**：确认 `--tls-san` 包含 LB IP/域名与各 server IP，并更新 kubeconfig server 地址。
+- **外部 datastore 连接失败**：检查连接串、网络 ACL、防火墙、账号权限；在 server 上用 `psql/mysql` 先手工连通再跑 k3s 参数。
+
+- `03-08-k3s-ha-集群配置与切换.md`
+