# 本地三节点同构验收

## 链路边界

本地验收不使用旧 `simulation` 请求模式。压测端发送正式 Gemini `generateContent` 和正式
多参考图视频请求，完整经过：

```text
双 TLS 入口 → API 鉴权与 validation 门禁 → 生产候选路由
→ Base64 解码及媒体物化 → PostgreSQL/River → Worker/租约
→ 真实 Gemini/Volces 客户端 → 协议模拟上游
→ 结果持久化 → 独立钱包结算 → 独立回调收集器 → 客户端响应
```

只有候选已经确定后的 Base URL 和凭据被验收 Run 替换。模拟上游实现真实协议、延迟、
异步轮询及示例媒体返回；API、Worker、候选选择、账务和恢复代码不走测试旁路。

## 资源和工具

本地集群名固定为 `easyai-acceptance-local`，包含三个 k3d/K3s server：

| 节点 | Docker 上限 | 调度职责 |
|---|---:|---|
| server-0 / ningbo | 4 CPU / 8 GiB | API、Worker、PostgreSQL |
| server-1 / hongkong | 4 CPU / 8 GiB | API、Worker、PostgreSQL |
| server-2 / los-angeles | 2 CPU / 4 GiB | 控制面和 etcd，`NoSchedule` |

Docker Desktop 必须配置至少 24 GiB 内存；脚本只检查，不修改 Docker 设置。k3d、K3s 和
CNPG 版本及 SHA-256 位于
`deploy/kubernetes/local-acceptance/dependencies.lock`。高并发阶段使用宿主原生架构镜像，
最后才导入 release manifest 中精确的 `linux/amd64@sha256` 制品做启动、迁移和媒体冒烟。

```bash
scripts/acceptance/local-cluster.sh install-tools
scripts/acceptance/local-cluster.sh preflight
```

失败的 `up` 默认保留集群。只有下面的显式命令会销毁：

```bash
scripts/acceptance/local-cluster.sh down --confirm
```

## 脱敏生产快照

先使用只有 `SELECT` 权限的数据库角色导出 `acceptance-snapshot/v1`：

```bash
AI_GATEWAY_ACCEPTANCE_SNAPSHOT_DATABASE_URL='<只读连接>' \
  scripts/acceptance/export-production-snapshot.sh \
    --release-sha <当前线上完整SHA> \
    --output .local-secrets/acceptance/production-snapshot.json
```

快照只包含一个 Gemini 图片候选和一个 `omni_video.max_images >= 9` 视频候选所需的能力、
协议、路由、限流、价格、重试和运行策略。导出器拒绝密码、Secret、Token、认证、代理和
连接串字段，文件权限固定为 `0600`，并记录配置哈希和快照 SHA-256。

本地导入必须先匹配 `acceptance_local_cluster_id` 数据库标记，否则拒绝写入。集群内创建
32 个隔离身份/API Key、独立钱包和专属 Run；Key 与 Run Token 只保存在 `0600` 临时文件，
不进入 Pod Spec、报告或日志。

## 创建与验收

源码必须已提交且工作区干净，确保本地镜像和报告中的完整 Git SHA 可复现：

```bash
scripts/acceptance/local-cluster.sh up \
  --snapshot .local-secrets/acceptance/production-snapshot.json

scripts/acceptance/run-local-acceptance.sh quick

scripts/acceptance/run-local-acceptance.sh full \
  --release-manifest dist/releases/<完整SHA>.json
```

`full` 依次执行：

1. Gemini、3/6/9 图视频、账务和回调快速验收。
2. 固定 `1+1` Worker 的 P24、P28、P32，每档完整运行三次。
3. 1000×256 KiB、128×2 MiB、32×8 MiB Gemini 与 1200/96 视频负载。
4. 40±20 ms/0.5% 丢包、上游断链 10 秒、Worker—数据库断链 30 秒。
5. 确实持有远程任务的 Worker 强杀，以及容量控制器 Leader 切换。
6. `1+1 → 1+2/2+2 → drain → 1+1` 弹性验证。
7. 80% 两小时混合流量和 120% 十分钟主动限流。
8. 精确 amd64 release 镜像的迁移、启动与媒体冒烟。

网络故障只能作用于带 `easyai.io/environment=local-acceptance` 标签的代理 Pod：

```bash
scripts/acceptance/network-fault.sh baseline
scripts/acceptance/network-fault.sh weak-link
scripts/acceptance/network-fault.sh upstream-outage
scripts/acceptance/network-fault.sh database-outage hongkong
scripts/acceptance/network-fault.sh reset
```

统一报告为 `acceptance-report/v1`，位于
`dist/acceptance/local/<run-id>/acceptance-report.json`。本地吞吐只用于筛选候选档位；
生产 certified profile 必须在线上模拟验收中重新确定。

## 不能被本地替代的门禁

本地环境不能认证真实 WireGuard 六向链路、生产磁盘、跨地域 CNPG 同步、供应商配额或
生产节点混部资源。线上 `--execute` 会重新导出生产候选配置；配置哈希与本地快照不一致时
立即停止，必须基于新快照重跑本地阻断验收。