Global Stone 多租户框架公有云改造终态方案

1. 背景与目标

Global Stone 是面向跨境电商的多租户框架，核心能力是以"租户标（TenantId）维度"实现中间件资源隔离。框架当前深度绑定阿里内部中间件生态（HSF/MetaQ/Diamond 等），通过入侵中间件生命周期（SPI Hook、Bean 代理、配置裂变）实现租户级透明隔离。

本方案目标：将框架改造为公有云版本，使第三方客户能基于公有云中间件（Dubbo+Nacos / RocketMQ / Redis / RDS 等）使用同等的多租户隔离能力；改造遵循业务 API 零改动红线，仅在框架内部用"SPI 抽象层 + 公有云适配器 + 实例模型"重写中间件适配层。（本次不覆盖非阿里云厂商适配。）

2. 公有云业务部署架构

先建立公有云上的整体部署形态——业务如何部署、依赖的中间件如何部署，这是理解整套框架的前提。

2.1 部署全景图

两种部署形态的对应关系：

2.1.1 中间件实例归属分类（谁走缺省、谁由业务设置）

关键区分维度不是中间件类型，而是无状态基础设施 vs 有状态数据存储——凡是有归属的有状态数据（数据库、缓存），都不存在"某 region 默认的实例"，必须业务声明。据此分三档：

为何 Redis/Tair 归为数据存储型：缓存虽常被当"旁路"，但其中的数据同样有归属与合规要求（会员/交易缓存等），实例由业务 provision，不存在"region 默认的缓存"，因此与数据库同档，由业务声明 endpoint。

2.2 公有云版框架内部工作原理

部署形态之下，再看一次请求在框架内部的完整链路。与阿里内部版本的最大差异：公有云下微服务南北向流量统一经“云原生网关”（MSE Cloud-Native Gateway / Higress）接入（取代内部版 Mtop 直接入流量）——网关承担协议卸载/鉴权/路由，并解析注入租户标识（X-hng = Region+Language+Zone+Currency → GL_KEY）。框架 SDK 内嵌于业务应用，入口完成租户识别与上下文初始化，全链路透传，出口按 Tenant→Namespace 映射落到公有云中间件实例。

2.3 实例模型：Region 缺省 + 数据存储业务声明

实例选择不需要复杂的多级路由。关键认知：基础设施/通道型中间件天生是“一个 region 一套、全租户共享”，不存在“不同租户连不同实例”的需求。因此框架只需维护“每个 region 连哪些基础设施/通道型实例”的映射，缺省即用本 region 对应实例；只有数据存储型才必须由业务声明。整个模型就两类：

region → 实例映射表（存于配置中心，仅基础设施/通道型，不含数据库与缓存）——这就是框架需要维护的全部：

region=eu-central-1   → { nacos: mse-fra:8848, mq: mq-fra }
region=ap-southeast-1 → { nacos: mse-sg:8848, mq: mq-sg }

运行时：CurrentRegionProvider 得到本机 region → 查此表 → 得到基础设施/通道型实例。若业务未配自定义实例，即用此缺省（绝大多数情况）。数据库与 Redis/Tair 不入此表，由业务的数据源/缓存/分片配置（global.landlord.*）直接声明。

2.4 跨实例调用（退化为例外）

• 缺省：不发生跨实例。应用只与本 region 的基础设施/通道型实例交互，数据存储也通常就近在本 region——零跨实例复杂度。
• 例外：跨 region/跨实例。仅当业务显式声明了其他 region 的数据存储实例，或发起跨 region RPC 时发生。需：① 业务配置目标实例 endpoint；② CEN 云企业网 / VPC 对等打通网络（注册面 + 数据面，Dubbo 直连 provider IP）。RPC 跨 region 走 Dubbo 多注册中心订阅 + ZoneDetector，仅为少数跨域场景保留。

3. 多租户框架模块分层与职责

在上述部署形态之上，公有云版本框架的模块分层如下——这是整套框架的骨架。

3.1 分层架构图

3.2 模块职责与依赖

3.3 依赖铁律（四条）

1. landlord / router 只依赖 satellite-spi + satellite-core，绝不 import 任何中间件具体类。
2. satellite-adapter-* 实现 spi、调用云 SDK，运行时按环境装配（缺省一套 region 适配器）。
3. satellite-sdk 对外 API 冻结：公开类/包路径/方法签名保持不变，作为长期对外契约；改造只替换其内部实现（委托 core），不废弃、不搬迁对外入口。
4. 业务 API 零改动：TenantContext/TenantLocal/GL_KEY/global.landlord.* 签名不变。

4. 实施路线图

4.1 迭代优先级与一期范围

优先级自高到低：

1. P0 · 框架骨架与 satellite 框架设计（最高）：global-common 实例模型 SPI（CurrentRegionProvider / InstanceEndpointResolver）、global-satellite 的 spi 抽象契约层（7 能力域 Hook + 2 枢纽 SPI）、core 中立骨架、sdk 门面冻结、SPI 加载装配机制——一切中间件适配的地基，须最先完成。
2. P1 · 框架自身能力收敛：global-landlord 核心（上下文 / 配置裂变委托 SPI / 单元剔除）、global-g11n 模块改造（文案 SPI 提炼 + 配置下沉 + 依赖收敛）。
3. P1 · 各中间件适配（adapter）：Diamond→Nacos（配置样板先行）、HSF→Dubbo3、MetaQ→RocketMQ、TDDL→PolarDB、Tair / Redis、SchedulerX、Sentinel——P0 骨架就绪后并行铺开。
4. P2 · global-router（一期不迭代）：多单元路由 / 纠偏简化、RegionHSF3Router→Dubbo Router——降低优先级，顺延二期。

一期范围 = P0 + P1（框架 + 中间件适配，不含 router）；二期 = global-router 简化迁移。已剔除范围（与 §5.3.5 一致）：Switch（内部开关层废弃，能力并入 Diamond→Nacos）；OceanBase（暂不使用）。

4.2 人力分工

乔忆 / 宫治 为框架负责人，把控框架设计与整体架构、定义 SPI 契约、代码评审；萧扬 / 亮晖 负责各中间件适配能力迭代。

乔忆 / 宫治 定义并冻结 SPI 契约后，亮晖 率先跑通 Diamond→Nacos「样板改造」作为示范，萧扬 / 亮晖 按同一范式并行复制到各自中间件 adapter。

4.3 工作量估算

① 框架自身能力（含 G11n）：

② 中间件适配（区间估算，PIC 对应 §4.2 分工）：

总计为含全部项的原始评估；扣除已废弃的 Switch（2–4）与暂不使用的 OceanBase（3–6），一期中间件实际投入约 30–52 人日。一期合计 ≈ 框架 22.5 + 中间件 30–52 ≈ 52–75 人日（3 人并行，含测试）；global-router 二期另计。

4.4 里程碑流水线（7.20 – 8.20）

一期约一个月、三人并行、以周为节拍推进。乔忆 / 宫治 先打地基（SPI 契约 + 样板），为两条中间件适配泳道解锁；TDDL→PolarDB 为最长链路。

关键路径：SPI 契约（M0）→ Nacos 活样板（M1） 是一切中间件适配的前置，须按时完成；TDDL→PolarDB 跨 3 周为最长链路，紧张时可从 M2 后追加人力支援。

5. 各模块改造点（基于分层细化）

按上述分层，逐模块给出“现状 → 改造点”。

5.1 global-common（微调）

global-common 是被全体依赖的基础模块，实际内容为 EnvUtils（环境/机器信息探测）、EnvConfig、proxy（JDK/Cglib）、annotation（@AutoServiceApi/@AutoServiceImpl）、ServiceLoader 等基础工具（注：TenantContext / GL_KEY / TenantLocal 并不在此，实际定义在 global-landlord-sdk，见 §5.4）。全模块仅两个文件存在中间件耦合，均需改造：

① Diamond 配置依赖（PropertiesLoader）

• 现状：PropertiesLoader 直接 import com.taobao.diamond.client.Diamond + com.taobao.diamond.client.impl.DiamondUnitSite，通过 loadFromDiamond() / loadFromFileAndDiamond() 从 Diamond 拉取配置——Diamond.getConfig(dataId, groupId, timeout) 拉取；DiamondUnitSite.getDiamondUnitEnv(unit) 按单元拉取。EnvUtils 加载 env-deploy.properties（环境部署/多租户相关配置）即经由此路径。
• 改造点：Diamond 读取下沉到 satellite-spi 的 TenantConfigService（由 nacos adapter 实现），PropertiesLoader 不再直连 com.taobao.diamond.*；DiamondUnitSite 的多单元语义随「剔除单元」移除，改为按 region 缺省解析。

② EnvUtils 机器/单元信息探测

• 现状：EnvUtils 直接 import com.taobao.config.client.services.ConfigClientService（getEnvByIp(ip) 按 IP 查单元标）与 HSF com.taobao.hsf.node.MachineGroupService / com.taobao.hsf.util.HSFServiceContainer（查机器分组）；对外出口 getCurrentUnit() 返回 currentEnv（单元标），供全框架单元判定。
• 改造点：getCurrentUnit() 标记废弃，语义迁移到 region——新增 RegionContext 承载本机 region，由 CurrentRegionProvider 从公有云环境变量/容器元数据填充；机器分组/单元探测去除 HSF MachineGroupService/HSFServiceContainer 与 ConfigClientService 依赖。

5.2 global-g11n（中等改造）

global-g11n（国际化能力）仅含 global-g11n-sdk，是业务方直接使用的对外 SDK：对外 API G11n / G11nContext / G11nAdmin 及模型 LocaleKey / LocaleSpec / Region / CurrencyUnit 等签名冻结不变（landlord 的 GLKey 依赖 LocaleKey，g11n 是其底层依赖）。业务逻辑（货币换算、locale 解析、文案格式化）与公有云无关，改造只切中间件耦合。四处耦合点：

① Diamond 配置（同 §5.1 common 手法）

• 现状：G11nConfigLoader / G11nScenarioLoader 直连 com.taobao.diamond.client.Diamond + ManagerListener，从 group=global.g11n, dataId=base.config 加载国际化基础配置（语言/货币/地区/时区/场景）并监听变更。
• 改造点：下沉到 satellite-spi 的 TenantConfigService + ConfigChangeListener（nacos adapter 实现），去除 com.taobao.diamond.*。

② MCMS 文案中心（本模块最大改造点）

• 现状：McmsTextResource2Repo / McmsTextResourceRepo 等一批 com.alibaba.mcms.* 类拉取多语言文案；依赖已是 provided + optional。利好：文案能力已有接口抽象 TextResourceRepo（McmsTextResource2Repo implements TextResourceRepo）。
• 改造点：将 TextResourceRepo 提升为正式 SPI；MCMS 实现拆为可选 adapter（内部环境装配）；公有云提供默认实现（本地资源文件 / Nacos 配置承载文案），业务亦可接入自有文案系统；未接入时降级为 key 回显。

③ MTOP 网关上下文

• 现状：RequestCommonCollectUtils 用 com.taobao.mtop.api.agent.MtopContext 从 MTOP 请求采集 locale。
• 改造点：抽象为中立的请求上下文采集，MTOP 作为可选适配；公有云走标准 HTTP header / Dubbo attachment 采集 locale。

④ 依赖收敛

• 现状：依赖 global-satellite-sdk（巨石），用其 Satellite / BootLogger / PathMarkUtils / ExistUtils 等 log/utils。
• 改造点：依赖收敛到 satellite-spi + satellite-core（与 landlord/router 一致），仅用其中立能力。

5.3 global-satellite（核心改造）

global-satellite 是整个框架的中间件底座，也是巨石所在，改造是全案重头戏。它当前已内建一套 hook/proxy 扩展点机制（见 §5.3.2），改造并非推倒重来，而是沿模块边界把已有机制切开：抽象契约（spi）、中立骨架（core）、中间件实现（adapter）、对外门面（sdk）四层各归其位。

5.3.1 模块拆分与分层

依赖方向：adapter → core → spi → common；sdk → core + adapter；业务/landlord/router 只依赖 spi + core（依赖铁律 §3.3）。

5.3.2 现有 hook/proxy 机制与演进路径

satellite 早已内建 SPI 扩展点机制，改造是复用并沿模块切开，不是新建：

• 扩展点契约：@SatelliteHookApi（= @Extends(AutoServiceApi)）标注 hook 接口，@SatelliteHook（= @Extends(AutoServiceImpl)，带 Level KERNEL/PLUGIN/USER + order）标注实现——本质是 common @AutoServiceApi/@AutoServiceImpl 的语义别名。
• 编排引擎：HookUtils 基于 ServiceLoader.getOrLoad 加载全部实现，按 Level+order 升/降序排序并缓存，形成 AOP 式增强链。
• 中间件实现：proxy/*（SatelliteDiamond / SatelliteHSFProxyUtils 等 100+ 文件）是 hook 的默认实现，直连中间件。
• 新范式已落地：config 域已用「spi 接口 + Holder + adapter」替换老 hook 路径——spi/config/TenantConfigService + TenantConfigServiceHolder（现状类名，落地按 §5.3.3 命名规范更名为 SatelliteConfigHook 体系；双检锁 + ServiceLoader + fail-fast，Spring 下由自动配置 set 注入）+ adapter-diamond 实现。这是「保留对外接口、逐步替换内部实现」的活样板，其余中间件照此推进。

两类加载机制的分工（演进方向）：

一个必须处理的障碍：现有 hook 接口部分不中立——如 HSFConsumerProxyHook 直接 import com.taobao.hsf...ServiceMetadata，而 DiamondHook 是纯净的。提炼到 spi 时，强耦合中间件类型的接口需清洗类型（用中立模型替代）或整体归入 adapter 层。

5.3.3 satellite-spi（抽象契约层）

定义 7 能力域接口 + 2 枢纽 SPI，方法签名尽量对齐现有代理类以降低 landlord 侧改动量。

命名规范（统一风格）：所有能力域 SPI 采用 Satellite 前缀 + Hook 后缀（如 SatelliteConfigHook）。已落地的 config 域现状类 TenantConfigService / TenantConfigServiceHolder / ConfigChangeListener（见 §5.3.2、§5.1、§5.2）在落地时按此规范重命名为 SatelliteConfigHook / SatelliteConfigHookHolder / SatelliteConfigChangeListener；下文凡出现 Tenant* 旧名均指现状代码，终态统一收敛到 Satellite*Hook 体系。

两个枢纽 SPI（实例模型落地入口）：

• CurrentRegionProvider：getCurrentRegion()，从环境变量/容器元数据解析本机 region（替代 getCurrentUnit()）。
• InstanceEndpointResolver：按中间件分类分两类解析 endpoint——基础设施/通道型用 region 缺省（查 region → 实例 映射，全租户共用；仅当业务显式配自定义实例时覆盖）；数据存储型无 region 缺省、必须业务声明，未声明则 fail-fast。不做租户级/服务级多级路由。

5.3.4 satellite-core（中立骨架层）

• 现状：原 satellite/proxy 100+ 文件与中间件强耦合，且门面/骨架/裂变逻辑散落其中。
• 改造点：抽出中间件中立的公共逻辑——代理骨架（CGLIB/JDK/Javassist 模板）、Hook 编排、配置裂变引擎、实例解析编排；不 import 任何中间件类。这是「保留对外接口、逐步替换内部实现」的承接层，供各 adapter 复用。

5.3.5 satellite-adapter-*（中间件适配层）

每个 adapter 实现对应能力域 SPI、对接一个公有云中间件、连实例时统一走 InstanceEndpointResolver。十个中间件的映射与改造要点如下。

改造要点：

• satellite-adapter-dubbo（HSF→Dubbo）：LandlordHSF3Router/RegionHSF3Router → Dubbo AbstractRouter，保留 GL_KEY 解析 + EnvRule（percent/tag）灰度；删除跨单元选址，改为 namespace/registry 选择 + ZoneDetector。Filter → Dubbo Filter SPI（RpcContext 透传几乎不变）。Consumer/Provider Bean 代理 ReferenceConfig/ServiceBean。
• satellite-adapter-rocketmq（MetaQ→RocketMQ）：Send/Consume Hook 包路径替换 + 签名微调；GL_KEY 透传用 Message.putUserProperty()；删除跨单元转发，ConsumerGroup/Topic 裂变保留（默认发本 region 实例）。
• satellite-adapter-nacos（Diamond→Nacos）：配置裂变 {tenantId}_{groupId} → dataId={groupId} + group={tenantId}（用 group 承载租户，规避 dataId 爆炸）；内部 Switch 开关层废弃，不再迁移；多单元 env 删除，改为 InstanceEndpointResolver 选实例。同时承担 Dubbo 注册中心（namespace 分子域）。
• satellite-adapter-rds（TDDL/OceanBase→SPI）：SatelliteDbHook 三方法；三种适配器——RDS（MyBatis Interceptor + ThreadLocal WHERE 注入）/ DRDS（Hint + 分库键）/ ShardingSphere；SQL AST 改写无法复刻时降级到租户独立 DataSource 物理隔离。属数据存储型：对 DB 不提供 region 缺省，实例来自业务数据源声明，未配置则 fail-fast。
• satellite-adapter-redis（Tair/Redis→Redis）：{tenantId}@ 前缀复用；LandlordJedis/LandlordRdb3 基于开源 Jedis/Lettuce 重写，代理模式不变。属数据存储型：缓存亦为有状态数据，对 Redis 不提供 region 缺省，实例来自业务声明，未配置则 fail-fast。
• satellite-adapter-schedulerx / satellite-adapter-sentinel：SchedulerX 验证公云版 GridJobContext CGLIB 代理兼容性；Sentinel 直接用开源版。

5.3.6 satellite-sdk（对外门面层·冻结）

• 对外稳定 API 门面层·长期保留：对外公开的类（Satellite 入口 / api / filter）、包路径、方法签名 100% 冻结不变，作为业务方唯一稳定入口。
• 改造手法：把内部原本直连中间件的实现掏空并委托到 satellite-core + satellite-adapter-*（只替换内部“实现”、对外“模块”接口保持不变），sdk 自身不 import 任何中间件类；现有 HookUtils / TenantConfigServiceHolder 等装配工具随之下沉 core。
• 明确不废弃——与早期“过渡壳”思路的关键区别：业务侧 import 无需迁移。

5.3.7 SPI 加载与装配机制

• 主干：ServiceLoader + 自研 @AutoServiceApi/@AutoServiceImpl 注解处理器（生成 META-INF/services），运行时扫描装配 adapter。
• 单实现能力域：走 XxxServiceHolder 双检锁获取（如 TenantConfigServiceHolder），无实现则 fail-fast 提示接入对应 adapter。
• 多实现增强链：走 HookUtils 按 Level+order 编排。
• 可选覆盖：Spring 环境下允许 Bean 覆盖（@ConditionalOnProperty + Holder.set()），如 adapter-diamond 的 @ConditionalOnProperty(global.stone.config.provider=diamond) + @ConditionalOnMissingBean；但 SPI 自动发现为主装配路径。

5.4 global-landlord（中等改造）

global-landlord 是租户上下文生命周期、配置裂变、GL_KEY 协议与 Bean 代理的核心承载。对外 API Landlord / LandlordContext / LandlordAdmin / LandlordProtocol 及模型 TenantContext / TenantSpec / GLKey / TenantLocal / TenantBeanFactory 签名冻结（业务零改动铁律）——LandlordContext 已是纯委托门面（TenantContextAdmin），零中间件耦合；GL_KEY（_GL_K = {oeId}_{siteId}@{country}|{lang}|{currency}|{region}）作为跨进程透传载体保留，由 Dubbo attachment / RocketMQ userProperty 承接。改造聚焦切中间件直连 + 剔除单元。

子模块与耦合分布：

① 配置加载与裂变（admin/*）→ 委托 SPI

• 现状：LandlordConfigLoader 直连 com.taobao.diamond.client.Diamond + ManagerListener；proxy/tbsession/LandlordTaobaoSessionManager 直连 DiamondEnv / DiamondUnitSite（含多单元）；LandlordPropertiesLoader（786 行）/ LandlordConfigHolder（696 行）依赖 satellite-sdk 工具（Satellite / HookUtils / PathMarkUtils）。
• 改造点：Diamond 直连去除，配置读取与裂变委托 SatelliteConfigHook（nacos adapter）+ InstanceEndpointResolver；DiamondUnitSite 多单元语义随「剔除单元」移除，改按 region 缺省解析；所用 satellite 工具随 satellite-core 下沉联动。

② 中间件插件（plugins/*）→ 归位 satellite-adapter

• 现状：plugins/hsf/*（LandlordServerFilterHook / LandlordClientFilterHook / LandlordHSFProviderProxyHook，直连 com.taobao.hsf + eagleeye）、plugins/message/*（直连 com.taobao.metaq.client）、plugins/diamond/*（Diamond hook）——均实现 satellite 的 @SatelliteHook 扩展点。
• 改造点：按中间件归位——hsf → satellite-adapter-dubbo（实现 SatelliteRpcHook）、message → satellite-adapter-rocketmq（SatelliteMessageHook）、diamond → satellite-adapter-nacos（SatelliteConfigHook）；landlord 侧只保留租户语义定制（如往 header 写 GL_KEY），中间件 API 实现下沉 adapter。plugins/guava（本地缓存）中立，保留或下沉 core。

③ 依赖收敛

• 现状：landlord-sdk 依赖 satellite-sdk（巨石），并用 com.taobao.eagleeye.EagleEye（TenantInnerContext（576 行）/ utils/*）做跨线程与跨调用透传。
• 改造点：依赖收敛到 satellite-spi + satellite-core（依赖收敛铁律）；eagleeye 透传改为中立透传抽象，复用 satellite eagleeye-context plugin 的公有云适配。

④ 单元剔除（重点）

• 删除：admin/protocol/LandlordUnitSelectors、admin/tolerance/*（AServerUnitRules / DiamondUnitRules / LandlordUnitRulesSelector / UnitSelectorLoader）、LandlordUnitConfigHolder、model/protocol/*UnitSelector（FixedUnitSelector / TenantUnitSelector / FixedTenantUnitSelector）。
• TenantSpec 移除单元字段（sourceUnit/targetUnit/deployUnits 等迁移语义），保留子域身份（oeId/siteId）；单元判定统一走 CurrentRegionProvider。

⑤ bridge / bridge-bom 体系 → 保留接入面、底层收敛 adapter

• 现状：global-landlord-bom 提供按需引入的分中间件 starter（landlord-diamond-starter / -hsf-starter / -metaq-*-starter / -tair-starter / -tddl-starter / -schedulerx-starter / -switch-starter），每个直连对应中间件；landlord-bridge 集成打包（provided：alibaba-middleware:sdk / ons-client / schedulerx-client）。
• 改造点：保留“业务按需引 starter”的接入形态（业务体验不变），底层实现收敛到 satellite-adapter-*——各 landlord-xxx-starter 变为「引 satellite-adapter-xxx + landlord 装配」的薄壳；中间件坐标替换为公有云版（diamond→nacos、hsf→dubbo、metaq→rocketmq、tair→redis、tddl→公有云 DB）；landlord-switch / -switch-starter 随 Switch 废弃移除。

5.5 global-router（大改造 / 简化）

• 现状：多单元路由引擎——单元路由匹配、流量纠偏、跨单元消息路由（EnvRule.unit、UnitSelector、RegionHSF3Router 等）。
• 改造点：剔除跨单元路由/纠偏/多单元订阅；保留子域逻辑隔离、实例选择、灰度（percent/eagleEyeTag）；RegionHSF3Router 迁为 Dubbo Router。

单元剔除影响一览：

5.6 构建与插件

• global-framework-bom：统一 SDK 版本，纳入 core/adapter 新模块；Spring Boot/JDK 版本升级在此收口。
• satellite-plugins/*：trace/druid/collect/eagleeye/slf4jmdc/load-analyze 等可观测/隔离插件，仅随中间件包路径微调，机制不改。
• global-stone-plugin：插件加载机制（注：根 pom 现无此模块，仅历史 target 残留，落地时确认是否恢复）。