fix(deploy): 补齐集群备份兼容与切换前门禁

阿里云 OSS 的 S3 兼容层要求 virtual-hosted addressing，且 boto3 需要使用 Signature V2。本提交为 Barman 的归档、备份、保留与恢复统一挂载 AWS 配置，并将实际 WAL 归档和近期全备设为切换硬门禁。

同时补充 CNPG/etcdutl 固定版本安装、显式主库切换、三节点逐台停机、OSS 快照下载校验与远端临时 Secret 清理。已通过 ShellCheck、Kustomize、服务端 dry-run、迁移测试、发布脚本测试、敏感信息扫描及生产 precutover 验收。

docs/operations/k3s-ha-runbook.md

@@ -26,7 +26,7 @@ pnpm install --frozen-lockfile
 pnpm lint
 pnpm test
 pnpm build
-shellcheck scripts/cluster/*.sh deploy/kubernetes/easyai-ai-gateway-cluster-release
+shellcheck -x -P . scripts/cluster/*.sh deploy/kubernetes/easyai-ai-gateway-cluster-release
 kubectl kustomize deploy/kubernetes/production >/dev/null
 ./tests/ci/migrations-test.sh
 node scripts/ci-validate-migrations.mjs <当前线上完整GitSHA>
@@ -45,6 +45,7 @@ node scripts/ci-validate-migrations.mjs <当前线上完整GitSHA>
 ./scripts/cluster/bootstrap-k3s.sh backup
 ./scripts/cluster/harden-node-network.sh
 ./scripts/cluster/bootstrap-k3s.sh install
+./scripts/cluster/verify-k3s-quorum.sh --execute
 ./scripts/cluster/verify-cluster.sh precutover
 ```
 
@@ -57,18 +58,34 @@ K3s containerd 同时配置 Docker Hub、GHCR 与 Quay 的镜像端点；已有
 ./scripts/cluster/configure-k3s-registries.sh
 ```
 
+`verify-k3s-quorum.sh` 会依次停止并恢复洛杉矶、香港、宁波 K3s，确认每次剩余两个
+server 都保持 etcd quorum。宁波停机可能令香港数据库副本晋升；首次切换前如需恢复宁波
+初始主库，显式执行 `promote-cnpg-primary.sh`，故障恢复流程不得自动回切。
+
 ### 3. 平台和入口预置
 
 ```bash
 ./scripts/cluster/bootstrap-platform.sh prepare dist/releases/<SHA>.json
+./scripts/cluster/install-cnpg-plugin.sh
+./scripts/cluster/install-etcdutl.sh
 ./scripts/cluster/install-nginx-edges.sh prepare
 ./scripts/cluster/install-certificate-sync.sh
 ./scripts/cluster/install-legacy-cleaner.sh
 ```
 
-`prepare` 将应用副本保持在 0，但启动 CNPG 双实例、WAL 归档和每日备份。SecretStore
+`prepare` 将应用副本保持在 0，但启动 CNPG 双实例、WAL 归档和每日备份。OSS 的 Barman
+链路使用 `s3.oss-cn-shanghai.aliyuncs.com`、virtual-hosted addressing 和 boto3
+Signature V2；`AWS_CONFIG_FILE` 通过 CNPG projected ConfigMap 同时挂载到主库、副本及恢复
+集群。预检会强制产生并归档一个新 WAL，并要求 48 小时内至少存在一份完成的全量备份。
+SecretStore
 的 4 个值从旧 volume 直接导入 Kubernetes Secret，脚本只校验数量与总字节数，不打印值。
 
+首次切换前如滚动安装令主库落在香港，可显式切回宁波。故障晋升后禁止自动执行该命令：
+
+```bash
+./scripts/cluster/promote-cnpg-primary.sh easyai-postgres-1
+```
+
 ### 4. 02:00–04:00 切换
 
 先执行只读预检：
@@ -86,7 +103,8 @@ K3s containerd 同时配置 Docker Hub、GHCR 与 Quay 的镜像端点；已有
 脚本依次启用维护页、停止旧 API、完整备份旧 PostgreSQL、上传 OSS、恢复 CNPG、比对数据库
 版本/扩展/catalog/表数/序列/关键行数/抽样 ID、运行 digest 固定 migrator、冻结 Worker 启动
 两地应用、做 NodePort 验收，再切换双 NGINX。公开流量提交后，先启用香港 Worker，再启用宁波
-Worker。旧 Docker PostgreSQL 和数据卷停止但保留，不自动删除。
+Worker。脚本等待切换后的 CNPG 全量备份状态变为 `completed` 后，才停止旧 Docker
+PostgreSQL；数据卷继续保留，不自动删除。
 
 在公共流量提交前，任一步失败或耗时超过 10 分钟都会恢复旧 Docker 与旧 NGINX。公共流量
 提交后禁止自动切回旧数据库，避免双写分叉。