starRiverProperty/docs/superpowers/specs/2026-05-01-service-discovery-architecture-design.md

电梯应用 — 服务发现架构设计

日期：2026-05-01（初稿）/ 2026-05-05（基线更新） 版本：v2.0.17（当前基线） 状态：已实施

说明：本文档最初记录 Dubbo/ZooKeeper 发现方案（目标架构），但在实践中发现该方案与 V1 生产实际不符。下方 §1~§5 保留为历史方案记录，§6 起为 实际实施态。当前基线 v2.0.17 以 §6 为准。

---

实际实施态（v2.0.17）

§6. 实际服务发现架构

电梯应用（cw-elevator-application）的三个上游 Feign 客户端通过 Ribbon + ConfigurationBasedServerList + 静态 IP 列表 实现服务寻址，与 V1 生产行为一致。

上游服务	Feign 名称	实际发现方式
人脸识别 GPU	ninca-crk-std	ConfigurationBasedServerList（V1 同）
组织组件	ninca-common-component-organization	ConfigurationBasedServerList（V1 同）
公共组件	ninca-common	ConfigurationBasedServerList（V1 同）

§7. 实际发现链路

业务代码 → @FeignClient(name = "${feign.xxx.name:...}")
              │
              ▼
         Feign → Ribbon LoadBalancer
              │
              ▼
         ConfigurationBasedServerList          ← discovery.enabled=false 时 Ribbon 默认
              │                                    （无 Consul/ConsulServerList 参与）
              ▼
         {name}.ribbon.listOfServers           ← 从 application.properties 读取
              │
              ▼
         目标 HTTP 服务 (IP:Port)

关键配置：

# bootstrap.properties — 与 V1 生产完全一致
spring.cloud.consul.discovery.enabled=false    # 不启用 Consul 发现客户端
spring.cloud.consul.discovery.register=true     # 仅注册自身到 Consul

# application.properties — 服务名映射（运行时需按环境配置）
feign.ninca-crk-std.name=ninca-crk-std
feign.component-organization.name=ninca-common-component-organization
feign.ninca-common.name=ninca-common
# 静态 IP 列表由环境中 application.properties 按需配置：
# ninca-crk-std.ribbon.listOfServers=10.0.22.102:16106
# ninca-common-component-organization.ribbon.listOfServers=...

§8. V1 vs V2 对比（实施态）

	V1 生产	V2 v2.0.17
ninca-crk-std	ConfigurationBasedServerList	ConfigurationBasedServerList ✅
ninca-common-component-organization	ConfigurationBasedServerList	ConfigurationBasedServerList ✅
ninca-common	ConfigurationBasedServerList	ConfigurationBasedServerList ✅
@RibbonClients	无	无 ✅
RibbonConfiguration 类	无	无 ✅
bootstrap.properties	见星中心	完全一致 ✅
主类名	AppApplication	AppApplication ✅
JAR 文件名	cw-elevator-application-V1.0.0.20211103.jar	一致 ✅

§9. 关键设计决策

决策	选择	原因
Consul 发现	discovery.enabled=false	与 V1 生产一致；只注册不发现
服务寻址	ConfigurationBasedServerList	Ribbon 默认行为，无需额外配置
ZK 发现依赖	已从 POM 移除	V1 没有该依赖，V2 不需要引入
静态 IP 配置	通过 {name}.ribbon.listOfServers 注入	与 V1 生产实际部署方式一致

§10. 运维说明

• 每台服务器需配置本机的 listOfServers（三台服务器各自指向本机或对端实例）。
• 若使用 Consul 做健康检查，discovery.enabled=false 不影响 Consul 注册（register=true）。
• 测试环境可使用 application-test.properties 覆盖 listOfServers 指向本地桩服务。

---

历史方案记录（目标架构，未实施）

以下 §1~§5 为 2026-05-01 设计的目标架构，实际 v2.0.17 未采用此方案。保留以记录设计历史。

§1. 原计划核心决策

电梯应用的三个上游 Feign 客户端 统一走 Dubbo/ZooKeeper 动态发现，不依赖任何 @RibbonClient 定制或 ConfigurationBasedServerList 静态列表。

上游服务	Feign 名称	原计划发现方式
人脸识别 GPU	ninca-crk-std	Dubbo/ZooKeeper（❌ 未实施）
组织组件	ninca-common-component-organization	Dubbo/ZooKeeper（❌ 未实施）
公共组件	ninca-common	Dubbo/ZooKeeper（❌ 未实施）

§2. 原计划服务发现链路（未实施）

ElevatorApplication
  │ @EnableFeignClients(basePackages={...})
  │
  ├── Feign Client ──→ Ribbon (默认) ──→ DiscoveryClient ──→ Dubbo Registry
  │                                                    zookeeper://10.0.22.207:2181

§3. 原计划配置清单（未实施）

# bootstrap.properties — 原计划使用 ZK 发现
spring.cloud.consul.discovery.enabled=false
dubbo.registry.address=zookeeper://10.0.22.207:2181
# 实际 v2.0.17 已移除 ZK 发现依赖，此配置不生效

§4. 原计划 V1 vs V2 对比（未实施）

	V1 生产	V2（原计划）
ninca-crk-std	ConfigurationBasedServerList	Dubbo/ZK（❌ 未实施）
ninca-common-component-organization	ConfigurationBasedServerList	Dubbo/ZK（❌ 未实施）
ninca-common	ConfigurationBasedServerList	Dubbo/ZK（❌ 未实施）

§5. 原计划删除清单（已执行）

文件	操作	状态
NincaCrkStdRibbonConfiguration.java	删除	✅ 已删除
OrgServiceRibbonConfiguration.java	从未存在	—
CommonServiceRibbonConfiguration.java	从未存在	—
ElevatorApplication.java 中 @RibbonClients	删除	✅ 已清理