XiTest · Tech Architecture

XiTest 技术架构设计

编排器 + 四大 Worker + HIL + 存储 + 可观测

文档编号：D2-P7-TECH-001 · 版本：v1.0 · 发布：2026-05-05

分层架构 · 水平扩展 · 全链路可观测

5

架构层

100+

Worker 规模

48h

HIL 压测时长

XiTest 技术架构设计

摘要

本文档是 XiTest v1.0 的完整技术架构设计，覆盖控制面（Orchestrator）、数据面（Worker Pool / HIL Controller / UI Runner）、存储（PostgreSQL / MinIO / ES）、可观测（Prometheus / Grafana / OpenTelemetry）五个架构层，以及各层之间的协议、接口与水平扩展策略。 面向测试框架开发者、DevOps 工程师、平台运维。

文档层级

本文档是 D2-P7-TECH-001（Spec 的技术实现视角），配合 Spec 和 API 使用。

---

1. 架构总览

1.1 五层分层模型

graph TB
    subgraph L0["L0 · 接入层"]
        CLI[xitest CLI]
        Web[Web UI]
        CI[CI 系统<br/>GitHub Actions / GitLab CI]
    end

    subgraph L1["L1 · API 网关层"]
        Gw[API Gateway<br/>REST + gRPC]
    end

    subgraph L2["L2 · 编排层"]
        Orch[Orchestrator<br/>Go + gRPC]
        Sched[Scheduler<br/>优先级队列]
    end

    subgraph L3["L3 · 执行层"]
        UnitW[Unit Worker Pool]
        IntegW[Integration Worker Pool]
        HILW[HIL Controller]
        UIW[UI Worker<br/>Playwright]
    end

    subgraph L4["L4 · 存储与观测"]
        DB[(PostgreSQL)]
        S3[(MinIO/S3)]
        ES[(ElasticSearch)]
        Prom[(Prometheus)]
    end

    CLI --> Gw
    Web --> Gw
    CI --> Gw
    Gw --> Orch
    Orch --> Sched
    Sched --> UnitW
    Sched --> IntegW
    Sched --> HILW
    Sched --> UIW
    UnitW --> DB
    IntegW --> S3
    HILW --> DB
    UIW --> S3
    Orch --> ES
    Orch --> Prom

    class CLI,Web,CI xyL4
    class Gw xyL3
    class Orch,Sched xyL2
    class UnitW,IntegW,HILW,UIW xyL3
    class DB,S3,ES,Prom xySuccess

1.2 设计原则

原则	说明
控制面/数据面分离	Orchestrator 只做调度，不执行测试，水平扩展不影响计算
无状态 Worker	所有 Worker 可随意启停，状态存于 DB/S3
容器化隔离	每个测试用例跑在独立 Docker 容器，互不污染
异步消息	Worker 通过 gRPC Stream 上报进度，避免轮询
可观测优先	每条 trace 可从 CLI 追到 Worker 到 HIL 到报告
失败优先重试	环境类失败自动重试 ≤ 3 次，非算法类失败不计入失败率

---

2. 编排层设计

2.1 Orchestrator 核心职责

• 接收 CLI / CI / API 提交的测试请求
• 解析用例集（resolve suite / tags / priorities）
• 分配给对应 Worker Pool（Unit / Integration / HIL / UI）
• 追踪运行状态，聚合结果
• 触发报告生成 + 通知

2.2 调度器（Scheduler）

graph LR
    Req[测试请求]
    Req --> Parse[用例解析]
    Parse --> Prio[优先级分组<br/>P0/P1/P2]
    Prio --> Q0[P0 Tapeout 队列]
    Prio --> Q1[P1 发版队列]
    Prio --> Q2[P2 Nightly 队列]
    Q0 --> Assign[Worker 分配]
    Q1 --> Assign
    Q2 --> Assign
    Assign --> Exec[执行]

    class Req xyL5
    class Parse,Prio,Assign xyL2
    class Q0,Q1,Q2 xyL3
    class Exec xySuccess

调度策略：

• P0（Tapeout）：独占 HIL 资源，插队任何其他任务
• P1（发版闸门）：优先使用空闲 Worker
• P2（Nightly）：空闲时间窗口执行，可被 P0/P1 打断

2.3 状态机

状态	含义	可转移到
PENDING	已入队，等待分配	SCHEDULED / CANCELLED
SCHEDULED	已分配 Worker	RUNNING / FAILED
RUNNING	正在执行	PASSED / FAILED / TIMEOUT
RETRYING	失败重试中	RUNNING / FAILED
PASSED	通过	(终态)
FAILED	失败	(终态)
TIMEOUT	超时	(终态)
CANCELLED	用户取消	(终态)

---

3. Worker Pool 设计

3.1 Unit Worker

• 运行环境：Docker + Google Test / Catch2
• 输入：算法仓库代码 + 测试二进制
• 输出：JUnit XML + stdout/stderr
• 并行度：单机 16，集群 200+
• 资源：2 vCPU / 4 GB 内存 / 任务

3.2 Integration Worker

• 运行环境：Docker + Python 3.11 + NumPy/SciPy + xy-test-runner
• 输入：YAML 用例 + 金标 WAV + 算法 DLL/SO
• 输出：metrics.json + 对比波形 + 通过/失败
• 并行度：单机 8，集群 100+
• 资源：4 vCPU / 8 GB 内存 / 任务
• 关键能力：
• 音频加载：支持 WAV / FLAC / 24bit / 32bit float
• 指标计算：频响 FFT / THD+N 谐波分析 / SNR 静音段 / 延迟互相关
• 容差判定：对比 expected 容差 + 生成 diff 图

3.3 HIL Controller

见第 4 章 "HIL 子系统详细设计" HIL 详细架构。

3.4 UI Worker

• 运行环境：Docker + Playwright（Chromium/WebKit/Firefox）+ Node.js
• 输入：Playwright 脚本 + 基准截图
• 输出：截图 + pixelmatch 差异报告 + trace 视频
• 并行度：单机 4，集群 30+
• 资源：2 vCPU / 4 GB 内存 + GPU（可选）

---

4. HIL 子系统详细设计

4.1 HIL 硬件栈

graph TB
    HILCtrl[HIL Controller<br/>Python]

    HILCtrl --> JTAG[JTAG 烧录器]
    HILCtrl --> PSU[可编程电源]
    HILCtrl --> Temp[恒温箱]
    HILCtrl --> Sound[专业声卡]

    JTAG --> EVB[XiDSP EVB]
    PSU --> EVB
    Temp --> EVB
    Sound --> EVB

    Sound --> ADC[EVB ADC 输入]
    Sound --> DAC[EVB DAC 输出]

    class HILCtrl xyL2
    class JTAG,PSU,Temp,Sound xyL3
    class EVB,ADC,DAC xyL0

4.2 HIL 执行流水线

阶段	动作	耗时
1. 预热	EVB 上电 + 温度稳定	30 s
2. 烧录	JTAG + XiStudio CLI 烧录固件	60 s
3. 自检	EVB 启动自检 + JTAG 调试握手	10 s
4. 播放	声卡向 EVB 输入金标 WAV	10-60 s
5. 采集	同步采集 EVB 输出	同上
6. 分析	离线计算声学指标	20 s
7. 判定	对比预期 + 生成报告	5 s

4.3 故障注入子系统

类型	硬件	参数
电压	Rigol DP832	±20% · 1-100 Hz 波动
温度	Espec SH-262	-40 ~ +85°C · 梯度 ±5°C/min
EMC	Teseq NSG-4070	IEC 61000-4-3 标准
时钟	Si5395	抖动注入 ±100 ppm

4.4 资源调度

• 独占模式：48h 压测 · 需提前 24h 预约 · 只有 P0 任务
• 共享模式：用例级切换 · 用例间需重新烧录 · P1/P2 任务
• 优先级抢占：P0 任务可打断 P1/P2 · 被打断任务重新排队

---

5. 存储与数据模型

5.1 PostgreSQL 核心表

表	主要字段	用途
runs	id, suite, status, started_at, finished_at, trigger	测试运行元数据
cases	id, name, category, tags, yaml_hash	用例定义
case_results	run_id, case_id, status, duration, metrics	单用例结果
baselines	case_id, version, wav_path, approved_by	金标基线历史
workers	id, type, status, last_heartbeat	Worker 注册表

5.2 MinIO / S3 对象存储

• golden/：金标 WAV（长期保留）
• runs/<run-id>/output/：实际输出 WAV（保留 90 天）
• runs/<run-id>/diff/：频响/波形对比图（保留 90 天）
• runs/<run-id>/ui-screenshots/：UI 截图（保留 30 天）
• runs/<run-id>/report.html：归档 HTML 报告（保留 2 年）

5.3 ElasticSearch 日志索引

• 索引模式：xitest-logs-YYYY.MM
• 字段：run_id / case_id / worker_id / level / message / trace_id
• 保留期：90 天热 + 1 年冷存档

---

6. 可观测性设计

6.1 Metrics（Prometheus）

指标	类型	标签
xitest_runs_total	Counter	suite, status
xitest_case_duration_seconds	Histogram	category, result
xitest_worker_active	Gauge	type
xitest_hil_queue_length	Gauge	priority
xitest_false_failure_ratio	Gauge	-

6.2 Tracing（OpenTelemetry）

• 从 CLI 到 Orchestrator 到 Worker 全链路 trace
• HIL 特殊：从 Worker 到 EVB JTAG 也插 span（硬件级追踪）
• 导出到 Jaeger / Tempo

6.3 告警规则

规则	阈值	处理
全局假失败率 > 1%	持续 1h	通知 DevOps on-call
HIL 队列 > 30	持续 30m	通知测试平台 lead
Worker 可用率 < 80%	持续 15m	自动扩容（如 K8s HPA）
报告生成耗时 > 5m	持续	通知 DevOps

---

7. 水平扩展策略

7.1 Worker 弹性

• 基于 Prometheus 指标（队列长度 / Worker 负载）触发 K8s HPA
• Unit Worker：2-200 动态扩缩
• Integration Worker：4-100 动态扩缩
• UI Worker：固定 4-30（Playwright 资源重）
• HIL Worker：物理资源 · 不可弹性扩展（需预算采购）

7.2 Orchestrator 高可用

• 3 节点部署 · etcd 选主
• 状态持久化在 PostgreSQL · Orchestrator 可随时重启
• API Gateway 前置 Nginx / Envoy · 自动健康检查切流

7.3 存储扩展

• PostgreSQL：读写分离 + 按月分表（case_results_2026_05）
• MinIO：多节点 Erasure Code
• ES：按月索引 + ILM 自动冷热迁移

---

8. 安全与合规

8.1 访问控制

• 认证：SSO（OIDC）· 内部 Okta / Azure AD
• 授权：RBAC · 角色：Viewer / Contributor / Admin / Tapeout-Gate
• API Token：短时令牌（1h）· CI 使用长期令牌（30d 轮转）

8.2 敏感数据

• 金标 WAV 可能包含专有调音曲线 → 加密存储
• 算法代码 → 私有 Git + SSO 访问
• HIL 测试固件 → 专用仓库 + 访问审计

8.3 审计

• 所有金标更新记录（谁 / 何时 / 审批人）
• Tapeout 放行记录（不可删除 · 长期存档）
• 报告访问日志（查询 / 下载 · 保留 1 年）

---

9. 部署架构

9.1 推荐部署（v1.0 生产）

组件	规模	资源
API Gateway	3 实例	2c4g · Nginx
Orchestrator	3 实例	4c8g · Go
Unit Worker	50-200	2c4g · Docker
Integration Worker	20-100	4c8g · Docker
UI Worker	10-30	2c4g + GPU · Docker
HIL Worker	5-20（物理）	专用机柜
PostgreSQL	主+2从	8c32g + 1TB SSD
MinIO	6 节点	8c16g + 10TB/node
ES	3 节点	8c32g + 2TB/node
Prometheus + Grafana	1 实例	4c16g + 500G

9.2 K8s 命名空间规划

• xitest-control：Orchestrator / API Gateway
• xitest-workers：Unit / Integration / UI Worker
• xitest-storage：PostgreSQL / MinIO / ES
• xitest-obs：Prometheus / Grafana / Jaeger
• xitest-hil：HIL Controller（nodeSelector: hil-node）

---

10. 性能基准（v1.0 目标）

场景	用例数	耗时	Worker
Smoke（提交即跑）	50	≤ 5 min	16 Unit
PR Integration	300	≤ 20 min	16 Integration
Nightly Regression	1000	≤ 2 h	16 Integration
Tapeout-Full（HIL）	1000	24-48 h	10 HIL
UI Regression	100	≤ 45 min	10 UI

---

11. 已知技术债与演进

11.1 v1.0 已知技术债

• HIL 烧录串行：每次烧录 60s，未来可改用 On-Chip Bootloader 并行（v1.1）
• UI 跨分辨率：2K/4K 需手动配置（v1.2 自动化）
• AI 用例生成：v1.0 不具备，需 XiMind v1.1 配合

11.2 v1.1+ 演进方向

• 分布式 HIL 跨集群调度
• XiMind AI 编排测试用例
• 故障注入扩展（更多硬件故障模式）
• 测试结果知识图谱（失败用例聚类 · 根因推荐）

---

12. 附录

12.1 关联文档

• XiTest 产品概述
• XiTest PRD v1.0
• XiTest 产品规格书
• XiTest API 规范
• XiAlgo 技术架构
• XiDSP 技术架构

12.2 技术栈版本矩阵

组件	版本
Go	1.22+
Python	3.11+
Docker	24+
K8s	1.28+
PostgreSQL	15+
MinIO	RELEASE.2024+
ES	8.12+
Prometheus	2.50+
Playwright	1.42+
Google Test	1.14+

12.3 版本历史

版本	日期	要点
v1.0	2026-05-05	首版 · 五层架构 + HIL + UI + 水平扩展

---

tech-arch.md · D2-P7-TECH-001 · v1.0 · 2026-05-05 · Xisound 研发中心 · 测试与工具团队