huangping/starRiverProperty
1
0
Fork 0
mirror of https://github.com/hpd840321/starRiverProperty.git synced 2026-06-09 08:20:31 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: record v2.0.17 as baseline, update service discovery doc

Browse Source 
- Mark v2.0.17 as current production baseline in AGENTS.md
- Update service discovery architecture design doc: add §6-10 for
  actual implementation state, preserve original as history (§1-5)
- Document key decisions: no ZK discovery, ConfigurationBasedServerList,
  bootstrap aligned with V1
This commit is contained in:
反编译工作区
2026-05-05 19:01:33 +08:00
parent 1c5e60f690
commit ec05aa777d
2 changed files with 149 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/AGENTS.md
+37 -3
View File
@@ -3,6 +3,8 @@
## OVERVIEW ## OVERVIEW
starRiverProperty 全仓文档集中地：架构说明、业务走查、构建环境、代码风格、运维脚本。原 `dev-support/` 内容已迁入此处。 starRiverProperty 全仓文档集中地：架构说明、业务走查、构建环境、代码风格、运维脚本。原 `dev-support/` 内容已迁入此处。
**当前基线版本：v2.0.17**（2026-05-05 生产验证通过）
## STRUCTURE ## STRUCTURE
``` ```
docs/ docs/
@@ -19,21 +21,52 @@ docs/
│ └── ORIGINAL_BUILD_JDK.txt # JDK 8 依据 │ └── ORIGINAL_BUILD_JDK.txt # JDK 8 依据
├── style/ # 代码风格 ├── style/ # 代码风格
│ └── alibaba-eclipse-codestyle.xml # P3C Eclipse Formatter │ └── alibaba-eclipse-codestyle.xml # P3C Eclipse Formatter
└── operations/ # 运维脚本 ├── operations/ # 运维脚本
└── deploy_cw_elevator_v1_lib_to_nexus.py # V1 lib → Nexus │ └── deploy_cw_elevator_v1_lib_to_nexus.py # V1 lib → Nexus
├── superpowers/
│ ├── specs/ # 设计规格文档
│ └── data/ # 分析记录与调查报告
└── sql/ # 数据库 DDL 与初始化脚本
``` ```
## WHERE TO LOOK ## WHERE TO LOOK
| Task | Location | Notes | | Task | Location | Notes |
|------|----------|-------| |------|----------|-------|
| 当前迭代排期 | `README.md` | 前端跳过、后端优先的迭代范围 | | 当前基线版本 | `AGENTS.md` | v2.0.17（2026-05-05） |
| 聚合工程关系 | `architecture/Maven聚合工程说明.md` | 模块依赖与工程定位 | | 聚合工程关系 | `architecture/Maven聚合工程说明.md` | 模块依赖与工程定位 |
| 接口契约约束 | `architecture/对外接口不变-远程调用与性能优化约定.md` | 不可扩展的 HTTP/Feign 边界 | | 接口契约约束 | `architecture/对外接口不变-远程调用与性能优化约定.md` | 不可扩展的 HTTP/Feign 边界 |
| 走查任务清单 | `architecture/对外接口不变-走查任务与状态.md` | 可修正与须确认项 | | 走查任务清单 | `architecture/对外接口不变-走查任务与状态.md` | 可修正与须确认项 |
| 代码风格配置 | `style/alibaba-eclipse-codestyle.xml` | P3C 格式化 XML | | 代码风格配置 | `style/alibaba-eclipse-codestyle.xml` | P3C 格式化 XML |
| JDK 版本依据 | `build/ORIGINAL_BUILD_JDK.txt` | JDK 8 强制依据 | | JDK 版本依据 | `build/ORIGINAL_BUILD_JDK.txt` | JDK 8 强制依据 |
| Nexus 上传 | `operations/deploy_cw_elevator_v1_lib_to_nexus.py` | V1 lib 批量部署 | | Nexus 上传 | `operations/deploy_cw_elevator_v1_lib_to_nexus.py` | V1 lib 批量部署 |
| 服务发现架构 | `superpowers/specs/2026-05-01-service-discovery-architecture-design.md` | 设计文档（实施态） |
| ConsulServerList 分析 | `superpowers/data/2026-05-05-consulserverlist-static-ip-discovery-analysis.md` | V1 vs V2 服务发现差异调查 |
## 基线版本信息
| 项目 | 内容 |
|------|------|
| **版本** | **v2.0.17** |
| **状态** | ✅ 生产环境验证通过 |
| **验证日期** | 2026-05-05 |
| **JAR 文件名** | `cw-elevator-application-V1.0.0.20211103.jar`（与 V1 一致） |
| **主类** | `cn.cloudwalk.elevator.AppApplication`（与 V1 一致） |
| **Spring Boot** | 2.1.18.RELEASE |
| **Spring Cloud** | Greenwich.SR6 |
| **JDK** | 1.8（强制） |
| **Git rev** | `1c5e60f6` |
| **配置基线** | `deploy/v2-maven/bootstrap.properties` 与 V1 生产完全一致 |
### 关键决策记录
| 决策 | 选择 | 原因 |
|------|------|------|
| 服务发现 | `discovery.enabled=false` + ConfigurationBasedServerList | 与 V1 生产一致；ZK 发现依赖已移除 |
| Feign 注解 | OpenFeign（org.springframework.cloud.openfeign.FeignClient） | V1 使用 Netflix Feign，V2 已迁移 |
| 主类名 | AppApplication（与 V1 一致） | 对齐 V1 命名 |
| JAR 文件名 | cw-elevator-application-V1.0.0.20211103.jar（固定） | 生产部署习惯，与 V1 一致 |
| 租户策略 | 新增 tenant_visitor_floor_policy 表 | 新功能，仅在配置策略后生效 |
## CONVENTIONS ## CONVENTIONS
@@ -41,3 +74,4 @@ docs/
- `docs/` 是文档唯一定位点，`dev-support/` 已废弃 - `docs/` 是文档唯一定位点，`dev-support/` 已废弃
- 格式化 XML 路径：所有 `maven-*/pom.xml` 的 `alibaba.eclipse.codestyle.path` 均指向 `docs/style/` - 格式化 XML 路径：所有 `maven-*/pom.xml` 的 `alibaba.eclipse.codestyle.path` 均指向 `docs/style/`
- 运行 JAR 还原产物不在 `docs/`，而在 `artifacts/decompiled/` - 运行 JAR 还原产物不在 `docs/`，而在 `artifacts/decompiled/`
- **后续所有开发以 v2.0.17 为基线**，在此版本基础上修改和完善
docs/superpowers/specs/2026-05-01-service-discovery-architecture-design.md
+112 -62
View File
@@ -1,87 +1,137 @@
# 电梯应用 — 服务发现架构设计 # 电梯应用 — 服务发现架构设计
**日期**：2026-05-01 **日期**：2026-05-01（初稿）/ 2026-05-05（基线更新）
**版本**：V2（与 V1 生产对齐） **版本**：v2.0.17（当前基线）
**状态**：已实施 **状态**：已实施
## 1. 核心决策 > **说明**：本文档最初记录 Dubbo/ZooKeeper 发现方案（目标架构），但在实践中发现该方案与 V1 生产实际不符。下方 §1~§5 保留为历史方案记录，§6 起为 **实际实施态**。当前基线 v2.0.17 以 §6 为准。
电梯应用（cw-elevator-application）的三个上游 Feign 客户端 **统一走 Dubbo/ZooKeeper 动态发现**，不依赖任何 `@RibbonClient` 定制或 `ConfigurationBasedServerList` 静态列表。 ---
| 上游服务 | Feign 名称 | 发现方式 | ## 实际实施态（v2.0.17）
|---------|-----------|---------|
| 人脸识别 GPU | `ninca-crk-std` | Dubbo/ZooKeeper |
| 组织组件 | `ninca-common-component-organization` | Dubbo/ZooKeeper |
| 公共组件 | `ninca-common` | Dubbo/ZooKeeper |
## 2. 服务发现链路 ### §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)
```
**关键配置**：
```properties
# bootstrap.properties — 与 V1 生产完全一致
spring.cloud.consul.discovery.enabled=false # 不启用 Consul 发现客户端
spring.cloud.consul.discovery.register=true # 仅注册自身到 Consul
```
```properties
# 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 ElevatorApplication
│ @EnableFeignClients(basePackages={...}) │ @EnableFeignClients(basePackages={...})
│ │
├── Feign Client ──→ Ribbon (默认) ──→ DiscoveryClient ──→ Dubbo Registry ├── Feign Client ──→ Ribbon (默认) ──→ DiscoveryClient ──→ Dubbo Registry
│ │
│ zookeeper://10.0.22.207:2181 │ zookeeper://10.0.22.207:2181
│ │
├── ZoneFeignClient → ninca-common ──────────────────┘
├── PersonRecordEventHandler → ninca-common-component-organization ─┘
└── ElevatorRecordSendTask → ninca-crk-std ────────────────────┘
``` ```
**启动类**：`ElevatorApplication.java` — 无 `@RibbonClients` 注解，Ribbon 走默认 `DiscoveryClient` 模式。 ### §3. 原计划配置清单（未实施）
## 3. 配置清单
### bootstrap.properties（生产）
```properties ```properties
server.port=16112 # bootstrap.properties — 原计划使用 ZK 发现
spring.application.name=elevator-app
spring.profiles.active=access-control
# Consul — 仅注册自身，不作为发现客户端
spring.cloud.consul.host=371bfca4972c43d2aefcf302d0a4a277
spring.cloud.consul.port=8500
spring.cloud.consul.discovery.enabled=false spring.cloud.consul.discovery.enabled=false
# Dubbo/ZooKeeper — 服务发现
dubbo.registry.address=zookeeper://10.0.22.207:2181 dubbo.registry.address=zookeeper://10.0.22.207:2181
dubbo.protocol.port=16107 # 实际 v2.0.17 已移除 ZK 发现依赖，此配置不生效
dubbo.provider.version=1.0
``` ```
### application.properties — 服务名映射 ### §4. 原计划 V1 vs V2 对比（未实施）
```properties | | V1 生产 | V2（原计划） |
feign.ninca-crk-std.name=ninca-crk-std |------|---------|------------|
feign.component-organization.name=ninca-common-component-organization | ninca-crk-std | ConfigurationBasedServerList | Dubbo/ZK（❌ 未实施） |
feign.ninca-common.name=ninca-common | ninca-common-component-organization | ConfigurationBasedServerList | Dubbo/ZK（❌ 未实施） |
``` | ninca-common | ConfigurationBasedServerList | Dubbo/ZK（❌ 未实施） |
> 以上均为 Feign 路由名称，不需 `ribbon.listOfServers` 或 `NIWSServerListClassName`。 ### §5. 原计划删除清单（已执行）
## 4. V1 vs V2 对比 | 文件 | 操作 | 状态 |
|------|------|------|
| | V1 生产 | V2（修复前） | V2（修复后） | | `NincaCrkStdRibbonConfiguration.java` | 删除 | ✅ 已删除 |
|------|---------|------------|------------| | `OrgServiceRibbonConfiguration.java` | 从未存在 | — |
| ninca-crk-std | Dubbo | ConfigurationBasedServerList（空→报错） | Dubbo | | `CommonServiceRibbonConfiguration.java` | 从未存在 | — |
| ninca-common-component-organization | Dubbo | ConfigurationBasedServerList（空→报错） | Dubbo | | `ElevatorApplication.java` 中 `@RibbonClients` | 删除 | ✅ 已清理 |
| ninca-common | Dubbo | ConfigurationBasedServerList（空→报错） | Dubbo |
| @RibbonClients | 无 | 3 个 | **无** |
| RibbonConfiguration 类 | 无 | 3 个 | **无** |
## 5. 删除清单
| 文件 | 操作 |
|------|------|
| `NincaCrkStdRibbonConfiguration.java` | 删除 |
| `OrgServiceRibbonConfiguration.java` | 删除 |
| `CommonServiceRibbonConfiguration.java` | 删除 |
| `ElevatorApplication.java` 中 `@RibbonClients` 块 | 删除 |
## 6. 运维说明
- 若生产 ZooKeeper (`10.0.22.207:2181`) 不可达，三个 Feign 调用将报 `Load balancer does not have available server`——此为基础设施问题，非代码缺陷。
- `deploy/v2-maven/application.properties` 中无需添加 `*.ribbon.listOfServers`。
- 本地测试时可通过 `ninca-common-component-organization.ribbon.listOfServers=127.0.0.1:18082` 覆盖 DiscoveryClient 指向桩服务（需同时设置 `NIWSServerListClassName` 全局限定或通过 `@RibbonClient` 仅在测试 Profile 启用）。