starRiverProperty/docs/superpowers/data/2026-05-05-consulserverlist-static-ip-discovery-analysis.md

# ConsulServerList 静态固定后：IP 直连服务发现分析

> **日期**：2026-05-05
> **分析范围**：`maven-cw-elevator-application`、`maven-intelligent-cwoscomponent`
> **状态**：待后续排查

---

## 1. 问题背景

电梯应用（cw-elevator-application）的三个上游 Feign 客户端在 `spring.cloud.consul.discovery.enabled=false` 的情况下，无法通过 Consul 动态发现服务实例。当前解决方式是将 Ribbon 的 `ServerList` 固定为 `ConfigurationBasedServerList`，直接配置静态 IP 列表绕过 Consul。

但 V1 生产（星中心）中**并没有**这些静态 IP 配置，却仍在正常运行——这个差异需要深入排查。

---

## 2. 服务发现链路现状

### 2.1 V2 当前架构

```
业务代码 → @FeignClient(name = "ninca-crk-std")
              │
              ▼
         Ribbon LoadBalancer
              │
              ▼
         ConfigurationBasedServerList         ← 由 application.properties 强制指定
              │
              ▼
         ninca-crk-std.ribbon.listOfServers   ← 直接返回硬编码 IP:Port
              │
              ▼
         目标 HTTP 服务
```

### 2.2 V1 生产（星中心）架构——未文档化的差异

```
业务代码 → @FeignClient(name = "ninca-crk-std")
              │
              ▼
         Ribbon LoadBalancer
              │
              ▼
         ??? (无 ConfigurationBasedServerList 配置)
              │
              ▼
         ??? (无 listOfServers 配置)
```

**V1 生产没有 `ribbon.listOfServers`，但 Feign 调用工作正常——原因未知。**

---

## 3. 涉及的上游服务与 Feign 客户端

### 3.1 `ninca-crk-std`（CRK 人脸识别 GPU）

| Feign 客户端 | 模块 | @FeignClient name | 当前解析方式 |
|-------------|------|-------------------|-------------|
| `VisitorFeignClient.java` | elevator-service | `${feign.ninca-crk-std.name:ninca-crk-std}` | Ribbon → `listOfServers=10.128.161.95:16106` |
| `AcsRecordThreeSendFeignClient.java` | intelligent-cwoscomponent-rest | `${feign.ninca-crk-std.name:ninca-crk-std}` | Ribbon → 同上 |

另有非 Feign 路径：`AcsElevatorRecordServiceImpl` 通过 `@Value("${ninca-crk-std.ip}")` + `RestTemplate` 直连 CRK，与 Feign 无关。

### 3.2 `ninca-common-component-organization`（组织组件）

| Feign 客户端 | @FeignClient name | @FeignClient url | 当前解析方式 |
|-------------|-------------------|-----------------|-------------|
| `PersonFeignClient.java` | `ninca-common-component-organization` | **`http://127.0.0.1:33011`**（硬编码） | **绕过 Ribbon，直接 URL** |
| `OrganizationFeignClient.java` | `${feign.component-organization.name}` | 无 | Ribbon → `listOfServers=127.0.0.1:33011` |
| `LabelFeignClient.java` | `${feign.component-organization.name}` | 无 | Ribbon → 同上 |
| `ImageStorePersonFeignClient.java` | `${feign.component-organization.name}` | 无 | Ribbon → 同上 |
| `ImageStoreFeignClient.java` | `${feign.component-organization.name}` | 无 | Ribbon → 同上 |
| `ApplicationImageStoreFeignClient.java` | `${feign.component-organization.name}` | 无 | Ribbon → 同上 |

### 3.3 `ninca-common`（公共组件）

| Feign 客户端 | @FeignClient name | 当前解析方式 |
|-------------|-------------------|-------------|
| `ZoneFeignClient.java` | `${feign.ninca-common.name:ninca-common}` | Ribbon → **无 `listOfServers` 配置** |
| `FileFeign.java` | `${feign.ninca-common.name:ninca-common}` | Ribbon → 同上 |
| `SysettingAreaFeignClient.java` | `${feign.ninca-common.name:ninca-common}` | Ribbon → 同上 |

> **⚠️ `ninca-common` 没有任何 `ribbon.listOfServers` 配置。如果 Feign 调用到达此服务，会因空列表失败。**

---

## 4. 配置差异矩阵

### 4.1 V2 deploy/v2-maven/application.properties（当前验证环境）

```properties
# Feign 服务名映射
feign.ninca-crk-std.name=ninca-crk-std
feign.component-organization.name=ninca-common-component-organization
feign.ninca-common.name=ninca-common

# ninca-crk-std: 强制 ConfigurationBasedServerList + 静态 IP
ninca-crk-std.ribbon.NIWSServerListClassName=com.netflix.loadbalancer.ConfigurationBasedServerList
ninca-crk-std.ribbon.listOfServers=10.128.161.95:16106

# ninca-common-component-organization: 同上
ninca-common-component-organization.ribbon.NIWSServerListClassName=com.netflix.loadbalancer.ConfigurationBasedServerList
ninca-common-component-organization.ribbon.listOfServers=127.0.0.1:33011

# ninca-common: ❌ 无任何 Ribbon 配置
```

### 4.2 V2 deploy/v1-legacy/application.properties

```properties
ninca-crk-std.ribbon.NIWSServerListClassName=com.netflix.loadbalancer.ConfigurationBasedServerList
ninca-crk-std.ribbon.listOfServers=10.128.161.95:16106
# ❌ component-organization 和 ninca-common 无 Ribbon 配置
```

### 4.3 V1 生产（星中心/cw-elevator-application-V1.0.0.20211103/application.properties）

```properties
feign.ninca-crk-std.name=ninca-crk-std
feign.component-organization.name=ninca-common-component-organization
feign.ninca-common.name=ninca-common
ninca-crk-std.ip=10.0.22.102:16106
# ❌ 无任何 ribbon.listOfServers 配置
# ❌ 无任何 NIWSServerListClassName 配置
# ✅ discovery.enabled=false（bootstrap.properties）
```

---

## 5. NincaCrkStdRibbonConfiguration 源码删除问题

| 文件 | 状态 | 位置 |
|------|------|------|
| `NincaCrkStdRibbonConfiguration.java` | ❌ **源码已删除** | `cw-elevator-application-starter/src/main/java/cn/cloudwalk/ribbon/` 目录存在但为空 |
| `NincaCrkStdRibbonConfiguration.class` | ✅ 旧 fat JAR 中残留 | `deploy/v2-maven/cw-elevator-application-2.0.0/BOOT-INF/classes/cn/cloudwalk/ribbon/` |
| `ElevatorApplication.java` | ❌ 当前无 `@RibbonClient`/`@RibbonClients` | 启动类已清理 |

**影响**：新的 V2 构建不再包含 `NincaCrkStdRibbonConfiguration.class`。但由于 `application.properties` 中已有 `NIWSServerListClassName`，功能不受影响——属性配置和 Java 配置实现相同目的。

**残留风险**：旧 JAR 的 `NincaCrkStdRibbonConfiguration` 被 `@RibbonClients` 引用。如果旧 JAR 中的 `ElevatorApplication.class` 有 `@RibbonClients({@RibbonClient(configuration=NincaCrkStdRibbonConfiguration.class)})`，而新的构建没有这个类，会导致 `ClassNotFoundException`。需要确认 `ElevatorApplication.java` 是在哪个提交中完全移除了 `@RibbonClients`。

---

## 6. PersonFeignClient URL 硬编码问题

Commit: `ff9a9ed6` — `fix(test): hardcode PersonFeignClient url to local stub for test env`

```java
// 改前:
@FeignClient(name = "${feign.component-organization.name:ninca-common-component-organization}",
    path = "/component/person", fallback = PersonFeignClientFallback.class)

// 改后:
@FeignClient(name = "ninca-common-component-organization",
    url = "http://127.0.0.1:33011",
    path = "/component/person", fallback = PersonFeignClientFallback.class)
```

**改动影响**：
- `name` 从可配置占位符改为硬编码
- 新增 `url` 强制指向 `127.0.0.1:33011`（本地 stub）
- `name` 硬编码后，即使去掉 `url`，Ribbon 客户端名也不再跟随 `feign.component-organization.name` 配置

**提交说明**：`NOTE: PersonFeignClient url change is test-only, revert before production`

---

## 7. 待排查项

### P0 — V1 生产服务发现机制

V1 生产（星中心 `bootstrap.properties`）中 `spring.cloud.consul.discovery.enabled=false`，且没有任何 `ribbon.listOfServers` 配置。需要确认：
- V1 生产的 Feign 客户端到 CRK/组织组件的调用路径是否实际被执行？
- 如果执行，ConsulServerList 在 `discovery.enabled=false` 下是否仍能从 Consul HTTP API 获取实例？
- Spring Cloud Edgware.SR3 的 `ConsulServerList` 在 `discovery.enabled=false` 时到底如何行为？

**验证方法**：
```bash
# 在 V1 生产进程上查 Ribbon 实际使用的 ServerList 实现类
# 通过 RibbonLoadBalancerProbeRunner 日志（如果有）
# 或通过 jstack 分析 Feign 调用链

# 查看 Spring Cloud Consul 版本（决定 ConsulServerList 行为）
unzip -p V1.jar lib/spring-cloud-consul-discovery-*.jar META-INF/MANIFEST.MF
```

### P1 — ninca-common 缺少静态 IP 配置

`ZoneFeignClient`（空间服务）和 `FileFeign`（文件服务）调用 `ninca-common`，但没有任何 `listOfServers` 配置。需要：
- 确认这些 Feign 客户端在 V1/V2 中是否实际被调用
- 如果被调用，补充 `ninca-common.ribbon.listOfServers` 配置

### P1 — PersonFeignClient 生产就绪检查

- 确认 `url = "http://127.0.0.1:33011"` 在构建生产 JAR 前被 revert
- 恢复 `name = "${feign.component-organization.name:ninca-common-component-organization}"` 的占位符形式

### P2 — NincaCrkStdRibbonConfiguration 清理残留

- 决定是否恢复源码（保留 Java config 方式）或完全依赖 properties
- 如果依赖 properties，删除 `cn/cloudwalk/ribbon/` 空目录清除残留

### P2 — V1 vs V2 Ribbon 配置对齐文档

- 在 `docs/architecture/` 中记录 V1 生产的真实服务发现机制
- 明确 V2 增加 `ribbon.listOfServers` 的理由和适用范围

---

## 8. 关键文件定位

| 文件 | 路径 |
|------|------|
| ElevatorApplication.java | `maven-cw-elevator-application/cw-elevator-application-starter/src/main/java/cn/cloudwalk/elevator/ElevatorApplication.java` |
| NincaCrkStdRibbonConfiguration.java | **已删除**（旧路径：`.../ribbon/NincaCrkStdRibbonConfiguration.java`） |
| RibbonLoadBalancerProbeRunner.java | `.../debug/RibbonLoadBalancerProbeRunner.java` |
| ElevatorUpstreamServiceNames.java | `.../debug/ElevatorUpstreamServiceNames.java` |
| PersonFeignClient.java | `maven-intelligent-cwoscomponent/intelligent-cwoscomponent-rest/.../person/feign/PersonFeignClient.java` |
| V2 deploy application.properties | `maven-cw-elevator-application/deploy/v2-maven/application.properties` |
| V2 deploy test properties | `maven-cw-elevator-application/deploy/v2-maven/application-test.properties` |
| V1 生产 config | `星中心/cw-elevator-application-V1.0.0.20211103/application.properties` |
| V1 生产 bootstrap | `星中心/cw-elevator-application-V1.0.0.20211103/bootstrap.properties` |
| V1 fat JAR internal props | `星中心/.../cw-elevator-application-V1.0.0.20211103.jar!/application.properties` |
| 提交：清理 @RibbonClients | `373b5501` |
| 提交：PersonFeignClient url 硬编码 | `ff9a9ed6` |
| 提交：添加 ZK discovery 依赖 | `6b5898d0` |
| 提交：添加 NincaCrkStdRibbonConfiguration | `0a6ac955` |
| 架构设计文档 | `docs/superpowers/specs/2026-05-01-service-discovery-architecture-design.md` |

---

## 9. 附录：Ribbon ServerList 在 Spring Cloud Edgware 中的默认行为

Spring Cloud Edgware.SR3（V1 使用的版本）中，当 `spring.cloud.consul.discovery.enabled=false`：

```
ConsulDiscoveryClient       → @ConditionalOnProperty(enabled=true) → bean NOT created
ConsulServerList            → depends on DiscoveryClient → can't be created
Fallback                    → ConfigurationBasedServerList (Ribbon 默认)
ConfigurationBasedServerList → reads "{name}.ribbon.listOfServers" from Environment
                               if absent → returns empty list
```

V2（Spring Cloud Greenwich + Boot 2.1.x）表现相同。

如果 V1 生产确实没有 `listOfServers` 但 Feign 调用正常，则说明：
1. Feign 客户端的调用链路本身不在 CRK/组织组件上执行，或者
2. Spring Cloud Edgware 的 ConsulServerList 在 `discovery.enabled=false` 时有特殊处理（需要反编译 `ConsulServerList.class` 确认），或者
3. V1 生产运行时通过其他方式注入了 `listOfServers`（如 Consul KV、`SPRING_APPLICATION_JSON`、JVM 参数）

---

*本文档为代码走查与配置分析生成，需结合生产环境运行时证据进一步排查。*