xiaozhi-esp32-server/docs/unified-fastapi-platform/real-environment-handoff.md

真实环境测试交接

1. 何时交接

只有 质量门禁 的 RC 自动化退出条件全部满足，才进入本清单。以下情况不属于 真实环境阻塞，必须由开发阶段解决：

• 本地依赖无法安装或镜像无法构建。
• 虚拟设备协议不一致。
• Fake Provider 成功/错误/取消契约失败。
• 数据库、Redis、文件权限或配置广播失败。
• 缺少测试脚本、日志字段或复现步骤。

2. 外部资产

资产	最低要求	提供方
ESP32	至少一台生产使用型号；记录固件版本	Hardware QA
网络	局域网与公网 WSS；可控制弱网/断网	Ops/QA
模型凭证	实际计划启用的 ASR、LLM、TTS，必要时 VLLM	Service owner
MQTT/UDP	受支持版本的 gateway、broker 和端口	Integration/Ops
RAGFlow	受支持版本、测试数据集和访问凭证	Knowledge owner
可选服务	短信、声纹、语音克隆、MCP、Memory	对应服务 owner
目标主机	计划上线的 CPU/GPU/架构、Docker/Compose 或编排平台	Ops
域名证书	HTTPS/WSS 域名、证书和反向代理权限	Ops

凭证不得写入 Issue、PR、测试产物或仓库；通过部署环境的 Secret 管理提供。

3. 必测场景

设备与音频

• 首次启动、OTA、激活和绑定。
• WebSocket 鉴权和长连接保持。
• 唤醒、单轮/连续对话、打断、静音超时和重连。
• 真实麦克风、扬声器、AEC、Opus 帧节奏和中文/非中文语音。
• 弱网、高延迟、短时断网和服务滚动发布。

Provider

• 每个计划启用 Provider 的成功、流式、空结果、超时、限流和凭证错误。
• ASR 音频格式、TTS 音频参数、LLM 工具调用及取消行为。
• 供应商控制台侧请求量、错误和费用符合预期。

外部集成

• MQTT/UDP 上下行音频与控制消息。
• RAGFlow 上传、解析、检索、删除和故障补偿。
• Vision 图片上传、鉴权、大小/格式限制和真实结果。
• 按实际启用范围验证短信、声纹、语音克隆、MCP 和通讯录呼叫。

部署

• 全新安装、已有数据升级、滚动发布和回滚。
• 非 root 文件权限、模型卷、上传卷和日志采集。
• API、realtime、jobs 独立健康与告警。
• 目标容量下的连接数、CPU/GPU、内存、带宽和响应时间。

4. 证据格式

每条真实用例记录：

Case ID：
日期/测试人：
硬件与固件：
服务版本/Commit：
外部服务及版本：
网络与部署环境：
步骤：
预期：
实际：
日志/指标/录屏位置：
结果：Pass / Fail / Blocked
缺陷链接：

敏感字段在上传前脱敏。失败必须能关联到服务器会话 ID、设备 ID 的脱敏标识和时间窗口。

5. 上线判定

生产批准至少要求：

• 选定 ESP32/固件矩阵通过。
• 实际启用的 Provider 和外部集成通过，不要求未启用供应商全部真实联调。
• 目标环境升级与回滚演练通过。
• 没有 P0/P1 缺陷。
• 监控、告警、值守和回滚负责人明确。

未提供的外部能力应标记为“未验收/不可启用”，不得以自动化 Mock 结果改为 Pass。