starRiverProperty/docs/superpowers/specs/2026-05-01-v2-test-env-setup-design.md

V2 全系统功能测试环境搭建 — 设计文档

日期: 2026-05-01 状态: 待实施 关联: AGENTS.md, maven-cw-elevator-application/deploy/

---

1. 目标

搭建 cw-elevator-application V2 (v2.0.7) 的全系统集成功能测试环境，包含电梯应用及其所有上下游依赖服务（CRK人脸识别、报警、cwos-manager、ninca-common、component-organization等），能够：

• 一键搭建全部 17 个组件
• 运行 V1 vs V2 API 对拍测试
• 验证 V2.0.7 租户访客固定楼层功能
• 验证 CRK 联动、报警联动等端到端链路
• 15-20 分钟内完成从零到全部验证

---

2. 环境约束

约束	值
部署方式	本机进程 (Java服务) + Docker 容器 (基础组件)
MySQL	复用现有: 192.168.3.12:3307, root/123456
JDK	Java 8 (/usr/lib/jvm/java-8-openjdk-amd64)
Maven	3.5+
Docker	已安装, docker compose 可用
代码分支	release/cw-elevator-v1-lib-min-risk
测试范围	全系统集成 — 全部 17 个组件

---

3. 组件清单

3.1 基础组件 (Docker)

#	组件	端口	来源
I1	Consul	8500	已有 deploy/consul-docker/docker-compose.yml
I2	Redis	6379	需要新增 compose 条目 (redis:7-alpine)
I3	Kafka + Zookeeper	9092, 2181	需要新增 compose 条目 (bitnami/kafka:3.6)
I4	Nginx (前端代理)	8090	已有 docker-compose.frontend-local.yml

3.2 应用服务 (本机进程)

#	组件	端口	来源	数据库
A1	ninca-common-backend	33010	星中心/ninca_common_01-ninca_common_backend.tar.gz	ninca_common
A2	component-organization	33011	星中心/ninca_common_component_organization_01-...tar.gz	component-organization
A3	cwos-system-api	3333	星中心/cwos_system_api_01-cwos_system_api/ (已解压)	—
A4	cwos-manager	3721	Docker Harbor 镜像 (已有 compose)	cwos_manager
A5	cwos-portal	33008	星中心/cwos_portal SQL 备份 → 重建	cwos_portal
A6	snap-app	33012	星中心/ninca_common_snap_app_01-...tar.gz	—
A7	vehicle-app	33013	星中心/ninca_common_vehicle_app_01-...tar.gz	—
A8	person-file-app	33014	星中心/ninca-person-file-app-V2.9.2_20210216.tar.gz	—
A9	monitor-app	33015	星中心/ninca_common_monitor_app_01-...tar.gz	—
A10	CRK-std	16106 (app), 16114 (mgmt)	星中心/ninca_crk_std_01-ninca_crk_std_backend/ (JAR已就绪)	ninca_crk_std
A11	alarm-app	17011 (app), 17211 (mgmt)	星中心/ninca_qk_alarm_app_01-ninca_qk_alarm_app/ (JAR已就绪)	alarm_deploy
A12	elevator V2	18081	Maven 构建 maven-cw-elevator-application	cw-elevator-application
A13	elevator V1	18080	对照基线 (已有 JAR)	cw-elevator-application

3.3 数据库 (MySQL 192.168.3.12:3307)

数据库	备份文件	大小
cw-elevator-application	data_backup/12_*.sql.gz + 34_*.sql.gz	158M + 2.5G
ninca_crk_std	(含在 CRK 配置中，需确认备份)	—
alarm_deploy	data_backup/alarm_deploy_*.sql.gz	15M
cwos_manager	data_backup/cwos_manager_*.sql.gz	51K
cwos_portal	data_backup/cwos_portal_*.sql.gz	212M
ninca_common	data_backup/ninca_common_*.sql.gz	6M
component-organization	data_backup/component-organization_*.sql.gz	212M
ods	data_backup/ods_*.sql.gz	485K
cloudwalk_device_thirdparty	data_backup/cloudwalk_device_thirdparty_*.sql.gz	4K
g / p / 12 / 34	其他备份	小量

---

4. 配置统一化

4.1 环境变量 (config/env.sh)

# 基础设施
MYSQL_HOST=192.168.3.12
MYSQL_PORT=3307
MYSQL_USER=root
MYSQL_PASS=123456
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASS=1qaz!QAZ
CONSUL_HOST=127.0.0.1
CONSUL_PORT=8500
KAFKA_HOST=127.0.0.1
KAFKA_PORT=9092
ZK_HOST=127.0.0.1
ZK_PORT=2181

# 服务端口
PORT_ELEVATOR_V2=18081
PORT_ELEVATOR_V1=18080
PORT_CRK_STD=16106
PORT_CRK_MGMT=16114
PORT_ALARM=17011
PORT_ALARM_MGMT=17211
PORT_CWOS_PORTAL=33008
PORT_COMPONENT_ORG=33011
PORT_NINCA_COMMON=33010
PORT_CWOS_MANAGER=3721
PORT_SYSTEM_API=3333
PORT_SNAP=33012
PORT_VEHICLE=33013
PORT_PERSON_FILE=33014
PORT_MONITOR=33015
PORT_NGINX=8090

# Java
JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
JAVA_OPTS="-Xmx2048m -Xms512m"

4.2 配置替换规则

每个 Java 服务的 application.properties / bootstrap.properties 中需要替换：

原始值 (生产)	替换为 (测试)
mysql_01.mysql_ip	192.168.3.12
redis_01.redis_ip	127.0.0.1
371bfca.... (Consul UUID host)	127.0.0.1
44700995e.... (Kafka broker 1)	127.0.0.1:9092
0837a70b5.... (Kafka broker 2)	(移除，仅保留一个 broker)
10.128.161.95 (内网 IP 地址)	127.0.0.1
10.0.22.207 (内网 ZK)	127.0.0.1:2181
10.128.123.108 (内网 DB)	192.168.3.12
10.0.22.102 (内网 CRK IP)	127.0.0.1
3306 (生产 DB 端口)	3307

---

5. 脚本设计

5.1 文件结构

源码/scripts/test-env/
├── docker-compose.infra.yml      # 合并 Consul+Redis+Kafka+Nginx
├── config/
│   ├── env.sh                     # 统一环境变量
│   ├── consul/consul-config.json  # Consul 初始化配置
│   └── service-templates/         # 配置文件模板 (.properties 模板)
├── setup.sh                       # 主入口: 一键搭建
├── start-all.sh                   # 启动全部服务
├── stop-all.sh                    # 停止全部服务
├── health-check.sh                # 探活检查
├── prepare-db.sh                  # 数据库恢复
├── prepare-services.sh            # 解压 + 配置注入
├── build-elevator-v2.sh           # 编译 V2 电梯应用
└── verify-functional.sh           # 功能验证

5.2 启动依赖拓扑

I1 Consul ──┐
I2 Redis ───┤  (Docker 并行启动)
I3 Kafka ───┤
I4 Nginx ───┘

A1 ninca-common ─────────────────────────┐
A2 component-org ←── common ─────────────┤
A3 system-api ←── manager ───────────────┤
A4 cwos-manager (Docker) ────────────────┤
A5 cwos-portal ←── org + manager ────────┤
A6 snap-app ←── portal + common ─────────┤
A7 vehicle-app ←── portal + common ──────┤
A8 person-file ←── portal ───────────────┤
A9 monitor-app (独立) ───────────────────┤
A10 CRK-std ←── portal + org + elevator ─┤
A11 alarm-app ←── portal + org + Kafka ──┤
A12 elevator-V2 ←── CRK + portal + org ──┤
A13 elevator-V1 (对拍对照) ───────────────┘

5.3 主入口执行流程

setup.sh:
  Phase 1: 环境检查 (< 10s)
    ├── JDK 8 检查
    ├── Maven 检查
    ├── Docker 检查
    ├── MySQL 连通性检查 (192.168.3.12:3307)
    └── 端口冲突检查

  Phase 2: 数据库准备 (~5min)
    ├── 创建所有数据库 (如不存在)
    ├── 解压并导入 11 个 SQL 备份
    └── 执行 V2 DDL (tenant_visitor_floor_policy.sql)

  Phase 3: Docker 启动 (~30s)
    ├── docker compose up infra
    ├── 等待 Consul Ready
    ├── 等待 Kafka Ready
    └── 启动 Nginx

  Phase 4: 服务准备 (~5-10min)
    ├── 解压 5 个 tar.gz
    ├── 从模板生成各服务配置文件
    ├── 编译 V2 电梯应用
    └── 同步 JAR 到 deploy/

  Phase 5: 服务启动 (~2min)
    ├── 按拓扑序依次启动 13 个 Java 服务
    ├── 每个服务启动后探活确认
    └── 失败自动重试 (max 3 次)

  Phase 6: 验证 (~2min)
    ├── 全端口探活
    ├── Consul 注册检查
    ├── V1/V2 API 对拍 (pytest)
    └── 输出验证报告

  总耗时: ~15-20 分钟

---

6. 验证矩阵

ID	验证项	命令/方法	通过标准
H1	所有端口可达	nc -z 127.0.0.1 <port> x 15	全部 open
H2	所有 HTTP 健康检查	curl /actuator/health x 8	全部 200 + UP
H3	Consul 服务注册	curl :8500/v1/agent/services	10+ 服务已注册
F1	V1/V2 API 对拍	pytest tools/elevator_api_parity/tests/	全部通过
F2	V2.0.7 UC-01 基线	不传 floorIds, 无策略	floorList 全集
F3	V2.0.7 UC-01 固定楼层	不传 floorIds, 有策略	floorList ∩ allow
F4	V2.0.7 无交集	allow 与 floorList 无交集	错误码 76260532
F5	V2.0.7 被访人无楼层	personId 无楼层	错误码 76260531
F6	V2.0.7 UC-02	显式传 floorIds	不读策略表
F7	CRK 联动	curl CRK → 电梯回调	CRK 日志有 Feign 记录
F8	报警 Kafka 消费	提交事件 → alarm 日志	Kafka 消息到达
F9	Nginx 前端代理	curl :8090	cwos-portal 首页
I1	MySQL 连通	mysql -h 192.168.3.12 -P3307 -e 'SELECT 1'	1

---

7. 已知风险与缓解

风险	影响	缓解
星中心/*.tar.gz 内 JAR 版本与 DB 备份不匹配	启动失败	从同一时间点导出 (2026-04-23) 的 DB 备份对齐
Docker Kafka 首次启动慢	Phase 3 超时	脚本增加 60s 等待 + 重试逻辑
V2 Maven 编译需 Nexus 私服	编译失败	已有 build_nexus_only.sh 降级方案
cwos-portal 无独立 JAR	无法启动	从 DB 备份 cwos_portal 库确认部署方式
端口冲突 (已有进程占用)	启动失败	Phase 1 预先检查, 用 lsof 检测并提示
ES (Elasticsearch) 依赖	alarm 启动可能失败	alarm application.properties 配置 ES, 需 Docker 添加

---

8. 未解决问题

1. cwos-portal 部署方式: 星中心中没有 cwos-portal 的 JAR 或 tarball, 仅 DB 备份中有 cwos_portal 数据。需确认其部署形态 (fat JAR? war? Docker?)。
2. cwos-system-api 启动入口: cwos_system_api_01-cwos_system_api/ 已解压, 需确认 JAR 入口和端口。
3. Elasticsearch: alarm 依赖 ES (elasticsearch.ip), 是否需要在 Docker Compose 中添加 ES 容器？
4. Dubbo/ZK: V1 电梯 bootstrap 配置有 Dubbo + ZK, V2 是否需要？可以在 Docker Compose 中添加 ZK。

---

9. 产出物

• 源码/scripts/test-env/docker-compose.infra.yml — 基础组件 Docker Compose
• 源码/scripts/test-env/setup.sh — 一键搭建脚本
• 源码/scripts/test-env/config/env.sh — 统一环境变量
• 源码/scripts/test-env/config/service-templates/ — 14 个配置模板
• 源码/scripts/test-env/start-all.sh / stop-all.sh — 启停脚本
• 源码/scripts/test-env/verify-functional.sh — 功能验证脚本