# Scripts 总览

本目录集中维护通用运维脚本。约定：**在仓库根目录执行**，使用 `./scripts/...` 路径调用。

流程说明与「部署 / 验证」分工以 [`docs/00-03-测试与验证框架.md`](../docs/00-03-测试与验证框架.md) **§2 自动化验证流程** 为准；下表与之一一对应。

| §2 步骤 | 含义 | 本仓库入口 |
|--------|------|------------|
| 1 接入 | inventory、仓库同步、加载 `.env.verify` | 手工；`verify.sh` / `deploy-lab.sh` 会自动 `source scripts/.env.verify`（若存在） |
| 2 环境/清理 | 轻量：各 verify 的 teardown；重度：清实验负载 / 重装 K3s | 轻量：`VERIFY_TEARDOWN`（默认 1）；重度：`k3s-delete-lab-stacks.sh`、文档中的 `k3s-uninstall`（**勿**默认进 `run-all`） |
| 3 部署 | K3s、Longhorn、nginx 矩阵等铺栈 | **`./scripts/deploy-lab.sh`**（`k3s` / `longhorn` / `nginx-matrix` / `nginx-matrix-tls`） |
| 4～5 断言与收尾 | 按 doc 目标 kubectl/curl；本篇 teardown | **`./scripts/verify.sh`** `run` / `run-all` |
| 6 一键串联 | 按 doc_id 顺序跑全部 verify（可先 preflight） | **`./scripts/verify.sh full`**（推荐，= preflight + run-all）或 **`./scripts/verify.sh run-all`** |

真机一键验收（可选先铺栈再全量验收）：

- `./scripts/acceptance.sh`：可选先执行 `deploy-lab.sh`（由环境变量开关），再执行 `verify.sh full`。

辅助命令：

- `./scripts/verify.sh flow` — 打印与 §2 对齐的流程说明（不接 Ansible）。
- `./scripts/verify.sh preflight` — 检查 `ansible-playbook` 与 `inventory`，并对 `k3s_server` 执行 `ping`；若已装集群可设 `VERIFY_PREFLIGHT_CLUSTER=1` 再执行 `kubectl get nodes`。
- `./scripts/verify.sh list --series 04 --exclude-noop` — 支持按主序列与 noop 过滤查看执行集合。

## 验证编排环境变量（可选）

复制 [`scripts/.env.verify.example`](.env.verify.example) 为 `scripts/.env.verify` 并填写本机值；**勿提交** `scripts/.env.verify`（已在仓库 `.gitignore` 中忽略）。

其中 **`ONECLOUD_SSH`** 用于**集群外**第三方 curl 等；**`SKIP_ARMV7` / `ARMV7_SSH` / `ARMV7_NFS_SSH`**（及 01-05 的 **`ARMV7_NFS_EXPORT_PATH`**、**`ARMV7_NFS_CLIENT_SUBNET`**）由 playbook 通过环境变量读取：`SKIP_ARMV7=1`（默认）时 `01-03`/`01-05` 仅基线检查；**`SKIP_ARMV7=0` 且 SSH 已配置** 时会对 arm 主机执行 dnf 路径（Fedora/RHEL 系，见 `docs/00-05` §E）。**`ACME_EMAIL`** 供 Traefik ACME（`03-02` / `03-03`）；另有 **`VERIFY_TLS_HOSTS`**、`K3S_SERVER_HOSTNAME`、`TIMEOUT_SEC`、`LONGHORN_NAMESPACE` 等，完整列表见 [`.env.verify.example`](.env.verify.example) 文末注释。

```bash
set -a && source scripts/.env.verify && set +a
```

## 部署 K3s（推荐在控制节点或 Linux 工作机）

在仓库根（或 `cd ansible` 后改用相对路径）执行 **`./scripts/deploy-lab.sh k3s`**。若需先准备数据盘，在 **本机或 `.env.verify`** 中设 `K3S_PREPARE_STORAGE=true`（会传 `-e k3s_prepare_storage=true` 跑 `ansible/playbooks/verify/01-06.yml`）。

**密钥与执行用户**：`inventory.ini` 中私钥路径随执行用户变化；在目标节点上以非 root 用户执行时，注意私钥路径与 `ansible_user` 与文档一致。

## 验证（run-all / full）

**推荐一行**（在仓库根；需已安装 Ansible、[`ansible/inventory.ini`](../ansible/inventory.ini) 可达、`k3s_server` 可 ping；集群与入口变量已按 [`00-04`](../docs/00-04-部署环境说明.md) 与 `.env.verify` 配好）：

```bash
./scripts/verify.sh full
```

`full` = `preflight` + `run-all`。若 `nginx_entry_base`、`nodejs_entry_base` 等未写入 `scripts/.env.verify`，可先 `export nginx_entry_base=http://<入口IP>` 再执行。仅跑用例、跳过 preflight 时用 `./scripts/verify.sh run-all`。`list/run-all/full` 均支持筛选参数：`--series <XX>`、`--id-regex <regex>`、`--exclude-noop`、`--require-teardown`。

将准备项（NFS、ACME、armv7、noop 文档等）补齐后再推进“已验证”，见 [`docs/00-04-待验证项-验证前准备.md`](../docs/00-04-待验证项-验证前准备.md)。

等价多行写法（与 `full` 相同）：

```bash
./scripts/verify.sh preflight
export nginx_entry_base=http://192.168.2.61
./scripts/verify.sh run-all
```

## 目录与脚本对照

- **`verify.sh`** — doc_id 验收：`flow` / `preflight` / `full` / `list` / `run` / `run-all`
- **`deploy-lab.sh`** — 安装/铺栈：`k3s` / `longhorn` / `nginx-matrix` / `nginx-matrix-tls`
- **`k3s-delete-lab-stacks.sh`** — 按 kubectl 实况清命名空间负载（重度清场，非默认 teardown）
- **`cloudflare-delete-acme-challenge-dns.sh`** — 清理 CF 上 `_acme-challenge` DNS
- **`ssh/setup-k3s-workers-ssh.sh`** — 为 K3s 节点预配 SSH（配合 `01-06`）
- **`ssh/test-ssh.sh`** — 验证 worker 密钥登录与 sudo

## 从仓库根执行示例

```bash
./scripts/ssh/setup-k3s-workers-ssh.sh
./scripts/ssh/test-ssh.sh
./scripts/deploy-lab.sh k3s
./scripts/verify.sh preflight
./scripts/verify.sh run 02-05
```

## 说明文档

- 验证框架：[`docs/00-03-测试与验证框架.md`](../docs/00-03-测试与验证框架.md)
- 验证前准备：[`docs/00-04-待验证项-验证前准备.md`](../docs/00-04-待验证项-验证前准备.md)
- 主文档入口：`docs/00-00-构建总览.md`