wangbo
e05922b0f4
实现本地三节点 K3s 同构环境、脱敏生产快照、Gemini 图片和多参考图视频协议模拟、统一验收报告及故障注入。\n\n新增 Worker 容量控制器、资源与连接预算、任务恢复保护，并将生产验收拆分为 validation 执行和人工 CAS 放量。\n\n验证包括 Go 全量测试、PostgreSQL HTTP 集成测试、go vet、OpenAPI、ShellCheck、前端检查、迁移及发布脚本测试。
107 lines
4.4 KiB
Markdown
107 lines
4.4 KiB
Markdown
# 本地三节点同构验收
|
||
|
||
## 链路边界
|
||
|
||
本地验收不使用旧 `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` 会重新导出生产候选配置；配置哈希与本地快照不一致时
|
||
立即停止，必须基于新快照重跑本地阻断验收。
|