Add migration doc (#2974)
diff --git a/content/zh-cn/blog/integration/how-to-proxy-dubbo-in-higress.md b/content/zh-cn/blog/integration/how-to-proxy-dubbo-in-higress.md
index e80030f..c20a2b3 100644
--- a/content/zh-cn/blog/integration/how-to-proxy-dubbo-in-higress.md
+++ b/content/zh-cn/blog/integration/how-to-proxy-dubbo-in-higress.md
@@ -1,10 +1,10 @@
---
aliases:
- /zh/overview/what/ecosystem/gateway/higress/
-description: "使用 Higress 作为 Dubbo 网关"
+description: "使用 Higress 作为 Dubbo 网关，代理 dubbo 协议服务。"
linkTitle: 如何通过 Higress 网关代理 Dubbo 服务
title: 如何通过 Higress 网关代理 Dubbo 服务
-date: 2023-04-01
+date: 2024-04-01
tags: ["网关", "生态"]
---
{{% alert title="注意" color="warning" %}}
@@ -14,6 +14,8 @@
Higress提供了从HTTP协议到Dubbo协议进行转换的功能，用户通过配置协议转换，可以将一个Dubbo服务以HTTP接口暴露出来，从而用HTTP请求实现对Dubbo接口的调用。本文将通过一个示例来介绍如何用Higress配置HTTP到Dubbo的协议转换。该示例会引导您轻松地部署一个Nacos server和一个Dubbo服务，然后通过Ingress将HTTP请求转发到注册在Nacos上的Dubbo服务，并通过Higress的协议转换能力完成对Dubbo服务的HTTP调用。
+<img style="max-width:800px;height:auto;" src="/imgs/v3/tasks/gateway/http-to-dubbo.png"/>
+
以下是一个使用 `Higress + dubbo协议 + Nacos注册中心` 的完整示例：[dubbo-samples-gateway-higress-dubbo](https://github.com/apache/dubbo-samples/tree/master/2-advanced/dubbo-samples-gateway/dubbo-samples-gateway-higress/dubbo-samples-gateway-higress-dubbo)。
## 前提条件
diff --git a/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/multi-protocols.md b/content/zh-cn/blog/java/codeanalysis/multiple-protocols-on-one-port.md
similarity index 75%
rename from content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/multi-protocols.md
rename to content/zh-cn/blog/java/codeanalysis/multiple-protocols-on-one-port.md
index 826dece..0e7e83f 100644
--- a/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/multi-protocols.md
+++ b/content/zh-cn/blog/java/codeanalysis/multiple-protocols-on-one-port.md
@@ -5,13 +5,14 @@
description: ""
linkTitle: 单端口多协议
title: 发布使用不同协议的多个服务，通过单端口监听
-type: docs
-weight: 5
+date: 2024-3-19
+author: 陈景明
+tags: ["源码解析", "协议"]
+description: >
+ Dubbo3 框架支持在单个端口发布多个不同的协议，比如可以同时发布 dubbo、triple 协议，本文介绍 Dubbo 是如何实现单端口多协议发布的。
---
-
-## 特性说明
通过对protocol进行配置，dubbo3可以支持端口的协议复用。
比如使用Triple协议启动端口复用后，可以在相同的端口上为服务增加
Dubbo协议支持，以及Qos协议支持。这些协议的识别都是由一个统一的端口复用
@@ -132,45 +133,3 @@
-
-
-文档编写中...
-
-Dubbo3 HTTP 协议支持仍在建设中，目前最新的 3.3 开发分支已经有初版原型供体验。正式的生产可用版本预计会在 3.4/3.4 的某个正式版本发布。
-
-以下是 Dubbo3 HTTP 协议与编程模式计划支持的几种业务场景：
-* 调用 http 协议的微服务体系
-* 发布 http 协议的服务
-* 多协议发布，一个服务同时发布 http&dubbo 协议
-
-## 调用 http 协议的微服务体系
-一个典型的应用场景是 Dubbo 调用 Spring Cloud 开发的微服务体系。
-
-不同体系的互通，最关键的两点便是地址格式与编码协议的兼容，只要 Dubbo 能自动发现 SpringCloud 体系的地址并能基于 HTTP 协议进行通信即可。Dubbo3 可以做到：
-* 支持 SpringCloud 体系的服务发现地址格式
-* 支持 HTTP+JSON 的数据传输格式
-
-
-
-基于以上分析，当我们需要调用 Spring Cloud 体系的服务时，只需要在 Dubbo 侧编写标准的 Dubbo Reference 服务引用就可以。同时，为了简化开发工作，**Dubbo 支持标准的 Spring Web 注解**，因此，如果你可以直接在 Dubbo 中复用 Spring Cloud 中的接口定义：
-
-Spring Cloud 侧的服务定义：
-```java
-interface SpringCloudRestService {
- //xxx
-}
-```
-
-在 Dubbo 侧唯一要做的工作就是定义 Dubbo Reference：
-
-```java
-@DubboReference
-private SpringCloudRestService restService;
-```
-
-## 发布 http 协议的服务
-
-
-## 多协议发布
-
-
diff --git a/content/zh-cn/blog/java/proposals/_index.md b/content/zh-cn/blog/java/proposals/_index.md
new file mode 100644
index 0000000..cfafe94
--- /dev/null
+++ b/content/zh-cn/blog/java/proposals/_index.md
@@ -0,0 +1,7 @@
+---
+title: "方案设计"
+linkTitle: "方案设计"
+weight: 30
+---
+
+
diff --git a/content/zh-cn/blog/java/proposals/service-discovery-migration.md b/content/zh-cn/blog/java/proposals/service-discovery-migration.md
new file mode 100644
index 0000000..94cabc1
--- /dev/null
+++ b/content/zh-cn/blog/java/proposals/service-discovery-migration.md
Binary files differ
diff --git a/content/zh-cn/overview/mannual/java-sdk/quick-start/deploy.md b/content/zh-cn/overview/mannual/java-sdk/quick-start/deploy.md
index edac8d4..f1a09a5 100644
--- a/content/zh-cn/overview/mannual/java-sdk/quick-start/deploy.md
+++ b/content/zh-cn/overview/mannual/java-sdk/quick-start/deploy.md
@@ -1,6 +1,6 @@
---
description: 快速部署Dubbo应用
-linkTitle: 快速部署Dubbo应用
+linkTitle: 部署Dubbo应用
title: 快速部署Dubbo应用
type: docs
weight: 3
diff --git a/content/zh-cn/overview/mannual/java-sdk/reference-manual/config/spring/annotation.md b/content/zh-cn/overview/mannual/java-sdk/reference-manual/config/spring/annotation.md
deleted file mode 100644
index 349329b..0000000
--- a/content/zh-cn/overview/mannual/java-sdk/reference-manual/config/spring/annotation.md
+++ /dev/null
@@ -1,12 +0,0 @@
----
-aliases:
- - /zh/docs3-v2/java-sdk/reference-manual/config/annotation/
- - /zh-cn/docs3-v2/java-sdk/reference-manual/config/annotation/
-description: 以 Spring 注解开发 Dubbo 应用
-linkTitle: Annotation 配置
-title: Annotation 配置
-type: docs
-weight: 3
----
-
-建议使用 Spring Boot 开发模式，您也可以在此查看 <a href="https://github.com/apache/dubbo-samples/tree/master/2-advanced/dubbo-samples-annotation" target="_blank">无 Spring Boot 的 Spring 注解开发模式示例</a>
diff --git a/content/zh-cn/overview/mannual/java-sdk/reference-manual/config/spring/spring-boot.md b/content/zh-cn/overview/mannual/java-sdk/reference-manual/config/spring/spring-boot.md
index 67a3f71..7e7cb1e 100644
--- a/content/zh-cn/overview/mannual/java-sdk/reference-manual/config/spring/spring-boot.md
+++ b/content/zh-cn/overview/mannual/java-sdk/reference-manual/config/spring/spring-boot.md
@@ -13,7 +13,13 @@
## application.yaml
-`application.properties(application.yaml)` 支持的配置项与 [配置参考手册](../properties) 中描述的基本是一一对应的。
+以下是 Dubbo 框架支持的配置组件列表，可以在 Spring Boot 配置文件中指定所需配置：
+
+### 配置示例
+
+```yaml
+
+```
### dubbo
* [**dubbo.application** - `org.apache.dubbo.config.ApplicationConfig`](../../properties#dubboapplication)
@@ -23,12 +29,13 @@
* [**dubbo.protocol** - `org.apache.dubbo.config.ProtocolConfig`](../../properties#dubboprotocol)
* [**dubbo.provider** - `org.apache.dubbo.config.ProviderConfig`](../../properties#dubboprovider)
* [**dubbo.registry** - `org.apache.dubbo.config.RegistryConfig`](../../properties#dubboregistry)
+* [**dubbo.metrics** - `org.apache.dubbo.config.MetricsConfig`](../../properties#dubbometrics)
+* [**dubbo.tracing** - `org.apache.dubbo.config.TracingConfig`](../../properties#dubbotracing)
* [**dubbo.ssl** - `org.apache.dubbo.config.SslConfig`](../../properties#dubbossl)
* ~~[**dubbo.monitor** - `org.apache.dubbo.config.MonitorConfig`](../../properties#dubbomonitor)~~
* ~~[**dubbo.module** - `org.apache.dubbo.config.ModuleConfig`](../../properties#dubbomodule)~~
### dubbo.metrics
-* [**dubbo.metrics** - `org.apache.dubbo.config.MetricsConfig`](../../properties#dubbometrics)
* [**dubbo.metrics.aggregation** - `org.apache.dubbo.config.nested.AggregationConfig`](../../properties#dubbometricsaggregation)
* [**dubbo.metrics.histogram** - `org.apache.dubbo.config.nested.HistogramConfig`](../../properties#dubbometricshistogram)
* [**dubbo.metrics.prometheus** - `org.apache.dubbo.config.nested.PrometheusConfig`](../../properties#dubbometricsprometheus)
@@ -36,7 +43,6 @@
* [**dubbo.metrics.prometheus.pushgateway** - `org.apache.dubbo.config.nested.PrometheusConfig$Pushgateway`](../../properties#dubbometricsprometheuspushgateway)
### dubbo.tracing
-* [**dubbo.tracing** - `org.apache.dubbo.config.TracingConfig`](../../properties#dubbotracing)
* [**dubbo.tracing.baggage.correlation** - `org.apache.dubbo.config.nested.BaggageConfig$Correlation`](../../properties#dubbotracingbaggage.correlation)
* [**dubbo.tracing.tracing-exporter.otlp-config** - `org.apache.dubbo.config.nested.ExporterConfig$OtlpConfig`](../../properties#dubbotracingtracing-exporterotlp-config)
* [**dubbo.tracing.tracing-exporter.zipkin-config** - `org.apache.dubbo.config.nested.ExporterConfig$ZipkinConfig`](../../properties#dubbotracingtracing-exporterzipkin-config)
@@ -45,8 +51,6 @@
* [**dubbo.tracing.sampling** - `org.apache.dubbo.config.nested.SamplingConfig`](../../properties#dubbotracingsampling)
* [**dubbo.tracing.tracing-exporter** - `org.apache.dubbo.config.nested.ExporterConfig`](../../properties#dubbotracingtracing-exporter)
-
-
-## starters
+## starter列表
starter 列表、版本、对应的组件版本
\ No newline at end of file
diff --git a/content/zh-cn/overview/mannual/java-sdk/reference-manual/faq/0/1.md b/content/zh-cn/overview/mannual/java-sdk/reference-manual/faq/0/1.md
index cbd45f1..eaf2cb8 100644
--- a/content/zh-cn/overview/mannual/java-sdk/reference-manual/faq/0/1.md
+++ b/content/zh-cn/overview/mannual/java-sdk/reference-manual/faq/0/1.md
@@ -10,9 +10,6 @@
---
-
-
-
服务端的线程资源耗尽了。
默认情况下，Dubbo 服务端的业务线程数是 200 个。如果多个并发请求量超过了 200，就会拒绝新的请求，抛出此错误。
diff --git a/content/zh-cn/overview/mannual/java-sdk/reference-manual/faq/0/2.md b/content/zh-cn/overview/mannual/java-sdk/reference-manual/faq/0/2.md
index 8ebd937..573dd56 100644
--- a/content/zh-cn/overview/mannual/java-sdk/reference-manual/faq/0/2.md
+++ b/content/zh-cn/overview/mannual/java-sdk/reference-manual/faq/0/2.md
@@ -10,10 +10,6 @@
---
-
-
-
-
### 可能的原因
这个提示是指用户配置的值与属性本身所需的数据类型并不匹配。比如 `dubbo.comsumer.threads` 属性只能接受数值属性，但是用户所输入的值混入了字母。
diff --git a/content/zh-cn/overview/mannual/java-sdk/reference-manual/protocol/triple.md b/content/zh-cn/overview/mannual/java-sdk/reference-manual/protocol/triple.md
index 921ab09..323a48d 100644
--- a/content/zh-cn/overview/mannual/java-sdk/reference-manual/protocol/triple.md
+++ b/content/zh-cn/overview/mannual/java-sdk/reference-manual/protocol/triple.md
@@ -126,7 +126,7 @@
如果你记得 triple 协议原生支持 cURL 访问，即类似 `org.apache.dubbo.springboot.demo.idl.Greeter/greet` 的访问模式。通过增加以上注解后，即可为 triple 服务额外增加 REST 风格访问支持，如 `demo/greet` 的 GET 请求。
-### Spring Web
+### Spring Web注解
Spring MVC 服务定义范例：
```java
@RestController
@@ -137,7 +137,7 @@
}
```
-### JAX-RS
+### JAX-RS注解
JAX-RS 服务定义范例：
```java
@Path("/demo")
@@ -148,18 +148,165 @@
}
```
-## 性能指标
+## 异常类型传递
+Provider 端产生的业务异常需要作为响应值返回给 Consumer 客户端，消费端可以使用 `try catch` 捕获可能抛出的异常：
+```java
+try {
+ greeterProxy.echo(REQUEST_MSG);
+} catch (YourCustomizedException e) {
+ e.printStackTrace();
+ } catch (RpcException e) {
+ e.printStackTrace();
+}
+```
-## 协议实现
-列一些 java 实现中的细节内容，可以配置或调整的选项等。
+Dubbo 框架会在 provider 侧根据如下流程发送异常类型响应，不是所有业务异常都能原样返回，对于无法处理的异常类型，都会被框架封装成 `RpcException` 类型返回：
-### 网络配置
-* 心跳检测
-* 网络传输包设置
-* 连接超时等
+
-### 线程模型
+## 附录
+### Protobuf与Java原生数据类型对比
+
+对于计划从 Java 接口完全迁移到 Protobuf 的用户而言，这里的信息可供参考，用以了解类型迁移可能面临的限制，Protobuf 描述语言是否能完全描述 Java 数据类型。
+
+本文对比了Protobuf和Java Interface这2种IDL的差异，帮助Dubbo协议开发者了解Protobuf，为后续转到Triple协议和Grpc协议做铺垫。
+
+#### 1. 数据类型
+
+##### 1.1. 基本类型
+
+| ptoto类型 | java类型 |
+| ---- | ---- |
+double | double
+float | float
+int32 | int
+int64 | long
+uint32 | int[注]
+uint64 | long[注]
+sint32 | int
+sint64 | long
+fixed32 | int[注]
+fixed64 | long[注]
+sfixed32 | int
+sfixed64 | long
+bool | boolean
+string | String
+bytes | ByteString
+
+{{% alert title="注意" color="primary" %}}
+在Java中，无符号的32位和64位整数使用它们的有符号对数来表示，顶部位只存储在符号位中。
+{{% /alert %}}
+
+#### 2. 复合类型
+
+##### 2.1. 枚举
+
+* 原始pb代码
+
+```java.
+enum TrafficLightColor {
+ TRAFFIC_LIGHT_COLOR_INVALID = 0;
+ TRAFFIC_LIGHT_COLOR_UNSET = 1;
+ TRAFFIC_LIGHT_COLOR_GREEN = 2;
+ TRAFFIC_LIGHT_COLOR_YELLOW = 3;
+ TRAFFIC_LIGHT_COLOR_RED = 4;
+}
+```
+
+* 生成的java代码
+
+
+
+> 枚举是常量，因此采用大写
+##### 2.2. 数组
+
+* 原始pb代码
+
+```java
+message VipIDToRidReq {
+ repeated uint32 vipID = 1;
+}
+```
+
+* 生成的java代码
+
+
+
+> 底层实际上是1个ArrayList
+##### 2.3. 集合
+
+PB不支持无序、不重复的集合，只能 ``借用数组实现``，需要 ``自行去重``。
+
+##### 2.4. 字典
+
+* 原始pb代码
+
+```java
+message BatchOnlineRes {
+ map<uint32, uint32> onlineMap = 1;//在线状态
+}
+```
+
+* 生成的java代码
+
+
+
+##### 2.5. 嵌套
+
+* 原始pb代码
+
+```java
+message BatchAnchorInfoRes {
+ map<uint32, AnchorInfo> list = 1; //用户信息map列表
+}
+/*
+* 对应接口的功能: 批量或单个获取用户信息
+*/
+message AnchorInfo {
+ uint32 ownerUid = 1 [json_name="uid"]; //用户id
+ string nickName = 2 [json_name="nn"]; //用户昵称
+ string smallAvatar = 3 [json_name="savt"]; //用户头像全路径-小
+ string middleAvatar = 4 [json_name="mavt"]; //用户头像全路径-中
+ string bigAvatar = 5 [json_name="bavt"]; //用户头像全路径-大
+ string avatar = 6 [json_name="avt"]; //用户头像
+}
+```
+
+* 生成的java代码
+
+
+
+#### 3. 字段默认值
+
+* 对于字符串，默认值为空字符串。
+* 对于字节，默认值为空字节。
+* 对于bools，默认值为false。
+* 对于数字类型，默认值为零。
+* 对于枚举，默认值为第一个定义的枚举值，它必须为0。
+* 对于消息字段，未设置字段。 它的确切值是语言相关的。 有关详细信息，请参阅生成的代码指南。
+
+#### 4. 整体结构
+
+| Feature | Java Interface | Protobuf | 备注 |
+| ---- | ---- | ---- | ---- |
+| 方法重载 | √ | × | |
+| 泛型/模板化 | √ | × | |
+| 方法继承 | √ | × | |
+| 嵌套定义 | √ | 部分支持 | PB仅支持message和enum嵌套 |
+| import文件 | √ | √ | |
+| 字段为null | √ | × | |
+| 多个入参 | √ | × | PB仅支持单入参 |
+| 0个入参 | √ | × | PB必须有入参 |
+| 0个出参 | √ | × | PB必须有出参 |
+| 入参/出参为抽象类 | √ | × | PB的入参/出参必须为具象类 |
+| 入参/出参为接口 | √ | × | PB的入参/出参必须为具象类 |
+| 入参/出参为基础类型 | √ | × | PB的入参/出参必须为结构体 |
+
+#### 5. 社区资料
+* 社区主页地址：https://developers.google.cn/protocol-buffers/
+* 社区开源地址：https://github.com/google/protobuf
+* 相关jar的maven：https://search.maven.org/search?q=com.google.protobuf
diff --git a/content/zh-cn/overview/mannual/java-sdk/reference-manual/routing-rule/_index.md b/content/zh-cn/overview/mannual/java-sdk/reference-manual/routing-rule/_index.md
index 3605aa4..840914e 100755
--- a/content/zh-cn/overview/mannual/java-sdk/reference-manual/routing-rule/_index.md
+++ b/content/zh-cn/overview/mannual/java-sdk/reference-manual/routing-rule/_index.md
@@ -1,7 +1,7 @@
---
-description: "Dubbo 路由规则详解，包括条件路由、动态配置、biaoqianluyou等"
-linkTitle: 单机运维命令(QOS)
-title: QOS 操作手册
+description: "Dubbo 路由规则详解，包括条件路由、动态配置、标签路由等，可以使用这些路由规则实现流量按比例转发、金丝雀发布、流量灰度、权重调整等能力。"
+linkTitle: 路由规则
+title: 路由规则
type: docs
weight: 99
---
diff --git a/content/zh-cn/overview/mannual/java-sdk/reference-manual/serialization/serialization.md b/content/zh-cn/overview/mannual/java-sdk/reference-manual/serialization/serialization.md
index 5c0df32..ef2199f 100644
--- a/content/zh-cn/overview/mannual/java-sdk/reference-manual/serialization/serialization.md
+++ b/content/zh-cn/overview/mannual/java-sdk/reference-manual/serialization/serialization.md
@@ -9,13 +9,13 @@
weight: 1
---
-## 序列化
-以下是 Dubbo 框架支持的序列化协议列表，根据 `triple`、`dubbo` 通信协议进行分类。
+## 支持的协议列表
+以下是 Dubbo 框架支持的序列化协议列表，根据 `triple`、`dubbo` RPC 通信协议进行分类。
| <span style="display:inline-block;width:100px">RPC协议</span> | <span style="display:inline-block;width:100px">编程模式</span> | <span style="display:inline-block;width:100px">序列化协议</span> | <span style="display:inline-block;width:200px">配置方式</span> | JDK版本 | 说明 |
| --- | --- | --- | --- | --- | --- |
-| **triple** | IDL | protobuf <br/>protobuf-json | 默认值 | 8, 17, 21 | 使用 IDL 时的默认序列化方式，也可以选择 protobuf-json 序列化 |
-| | Java接口 | protobuf wrapper | serialization="hessian" | 8, 17, 21 | 这种模式下采用的是两次序列化模式，即数据先被 hessian 序列化，再由 protobuf 序列化。<br/><br/>为了支持与 IDL 同等的调用模型，易用性较好但性能略有下降 |
+| **triple** | IDL | protobuf、<br/>protobuf-json | 默认值 | 8, 17, 21 | 使用 IDL 时的默认序列化方式，client 也可以选择 protobuf-json 序列化通信，无需额外配置 |
+| | Java接口 | protobuf-wrapper | serialization="hessian" | 8, 17, 21 | 这种模式下采用的是两次序列化模式，即数据先被 hessian 序列化，再由 protobuf 序列化。<br/><br/>为了支持与 IDL 同等的调用模型，易用性较好但性能略有下降 |
| **dubbo** | Java接口 | hessian | 默认值，serialization="hessian" | 8, 17, 21 | dubbo 协议默认序列化方式，具备兼容性好、高性能、跨语言的优势(java、go、c/c++、php、python、.net) |
| | Java接口 | protostuff | serialization="protostuff" | 8 | A java serialization library with built-in support for forward-backward compatibility (schema evolution) and validation. |
| | Java接口 | gson | serialization="gson" | 8, 17, 21 | 谷歌推出的一款 json 序列化库 |
@@ -27,10 +27,63 @@
## 性能对比报告
-序列化对于远程调用的响应速度、吞吐量、网络带宽消耗等同样也起着至关重要的作用，是我们提升分布式系统性能的最关键因素之一。
+序列化对于远程调用的响应速度、吞吐量、网络带宽消耗等起着至关重要的作用，是我们提升分布式系统性能的最关键因素之一。
具体请查看 [参考手册 - 性能基准报告](/zh-cn/overview/mannual/java-sdk/reference-manual/performance/)。
+## 切换序列化协议
+
+{{% alert title="注意" color="info" %}}
+本文档适用的典型场景是 Dubbo 老用户：用户已经有大量系统运行在 Dubbo 之上，由于一些场景需要，必须将使用多年的序列化升级一个新的序列化协议。
+{{% /alert %}}
+
+在 `3.2.0` 及之后版本中, Dubbo 的服务端引入新的配置 `prefer-serialization`，该特性可以通过协商的方式将整个系统的序列化协议平滑的升级到一个全新协议。
+
+### 切换步骤
+
+序列化协议升级，需要分两步走：
+
+**1. 需要推动服务端的序列化协议升级，同时在服务端的暴露配置中需要添加 `prefer-serialization` 配置。**
+
+比如：升级前的序列化协议是 hessian2，升级的目标序列化协议是 Fastjson2 那么在服务端的暴露配置中就应该添加如下所示的配置：
+
+Spring Boot 应用 `application.properties` 配置文件中增加如下内容：
+
+```properties
+dubbo.provider.prefer-serialization=fastjson2,hessian2 #这里定义了新的协议协商顺序
+dubbo.provider.serialization=hessian2 #这是之前的序列化协议
+```
+
+或者，如果使用 xml 配置的话：
+
+```xml
+<dubbo:provider serialization="hessian2" prefer-serialization="fastjson2,hessian2" />
+```
+
+**2. 客户端和服务端都需要增加新的序列化实现必要依赖**
+
+如以上示例所示，需要确保消费端和提供端都增加 fastjson2 依赖：
+```xml
+<dependency>
+ <groupId>com.alibaba.fastjson2</groupId>
+ <artifactId>fastjson2</artifactId>
+ <version>${fastjson2.version}</version>
+</dependency>
+```
+
+{{% alert title="警告" color="warning" %}}
+要使自动协商生效，需要确保：
+* 消费者端、提供者端都是 3.2.x 及以上版本，否则配置不生效（继续使用老序列化协议）
+* 消费者端、提供者端都加上了必须的序列化实现包依赖，否则不生效（继续使用老序列化协议，个别极端场景可能报错）。
+{{% /alert %}}
+
+### 实现原理
+
+dubbo 客户端序列化协议是根据服务端的注册配置来选择的（即服务端的`serialization`配置）。在请求阶段 dubbo 会把客户端的序列化协议组装到请求头上，服务端在进行反序列化时会根据请求头来确定反序列化协议。所以，如果服务端和客户端的版本不一致就可能会出现客户端序列化不了的情况。
+
+为了解决这个情况，`3.2.0` 在客户端序列化的时候会优先使用 `prefer-serialization` 配置的协议，如果不支持 `prefer-serialization` 相关的协议，才会使用 `serialization` 配置的协议。（可以把 `serialization` 理解为一个兜底的配置）
+
+
## 安全性
以上所有序列化方式中，protobuf 序列化具有最高的安全性，而对于其他序列化机制而言，我们要防止因为任意类序列化反序列化引发的 RCE 攻击。
diff --git a/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/migration-service-discovery.md b/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/migration-service-discovery.md
new file mode 100644
index 0000000..6377ab2
--- /dev/null
+++ b/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/migration-service-discovery.md
@@ -0,0 +1,76 @@
+---
+aliases:
+ - /zh/docs3-v2/java-sdk/upgrades-and-compatibility/service-discovery/service-discovery-samples/
+ - /zh-cn/docs3-v2/java-sdk/upgrades-and-compatibility/service-discovery/service-discovery-samples/
+description: 本文具体说明了用户在升级到 Dubbo3 之后，如何快速开启应用级服务发现新特性，从接口级服务发现平滑迁移到应用级服务发现。
+linkTitle: 升级到应用级服务发现
+title: 升级到应用级服务发现
+type: docs
+weight: 3
+---
+
+{{% alert title="请注意" color="warning" %}}
+* 本文档内容并不是升级 Dubbo3 必须的，您完全可以只升级框架并使用 [框架的服务发现默认行为](zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/migration-service-discovery/#启用应用级服务发现)。
+* 本文档更适用于 Dubbo2 老用户，用于了解在升级到 Dubbo3 版本后，框架中的服务发现模型切换过程与工作原理。新用户请直接 [配置启用应用级服务发现](/zh-cn/overview/mannual/java-sdk/tasks/service-discovery/nacos/#13-配置并启用-nacos)。
+{{% /alert %}}
+
+对于 Dubbo2 老用户而言，在升级 Dubbo3 时有以下两个选择，而决策的考虑因素仅有一个：性能。
+1. 如果您的集群规模不算大，之前使用 Dubbo2 未遇到任何地址推送等性能问题，完全可以继续使用接口级别服务发现
+2. 如果您集群规模较大，之前使用 Dubbo2 遇到服务发现负载飙高等问题，则建议迁移到新的应用级服务发现
+
+基于以上决策结论，请在升级 Dubbo3 框架时调整以下配置。
+
+## 继续使用接口级服务发现
+
+在升级到 Dubbo3 框架时，您需要调整应用配置如下，（仅仅是一个配置项调整，提供者应用必须配置、消费者应用可选）：
+
+```xml
+<dubbo:application name="xxx" register-mode="interface">
+```
+
+或者
+
+```yaml
+dubbo:
+ application:
+ name: xxx
+ register-mode: interface #表示继续使用老版本服务发现模型，可选值 interface、instance、all
+```
+
+或者，以上是全局默认配置，可以根据每个注册中心来单独配置
+
+```xml
+<dubbo:registry address="nacos://localhost:8848" register-mode="interface">
+```
+
+或者
+
+```yaml
+dubbo:
+ registry:
+ address: nacos://localhost:8848
+ register-mode: interface #表示继续使用老版本服务发现模型，可选值 interface、instance、all
+```
+
+## 启用应用级服务发现(默认)
+对于老用户而言，如果要启用应用级服务发现，就需要一个平滑迁移的过程。这时需要让新升级的 Dubbo3 应用进行双注册双订阅（当前框架默认行为，因此用户无需修改任何配置，以下内容均会自行发生，注意：未来版本可能切换为应用级单注册单订阅），以确保新老服务发现模型都能兼顾。
+
+{{% alert title="请注意" color="warning" %}}
+对于新用户而言，可以直接配置 `dubbo.application.register-mode=instance`，即在一开始就配置仅使用应用级服务发现。
+{{% /alert %}}
+
+### 提供者端注册行为
+在默认情况下，Dubbo3 框架会同时注册接口级、应用级两种服务发现地址，因此，集群中的新老应用都能够正常的发现改应用地址，并正常发起调用。如下图所示：
+
+
+<img alt="dubbo应用级服务发现" style="max-width:800px;height:auto;" src="/imgs/v3/migration/provider-registration.png"/>
+
+### 消费者端订阅行为
+在默认情况下，Dubbo3 框架具备同时发现 Dubbo2 与 Dubbo3 地址列表的能力。在默认情况下，如果集群中存在可以消费的 Dubbo3 的地址，将自动消费 Dubbo3 的地址，如果不存在新地址则自动消费 Dubbo2 的地址（Dubbo3 提供了开关来控制这个行为），具体如下图所示：
+
+<img alt="dubbo应用级服务发现" style="max-width:800px;height:auto;" src="/imgs/v3/migration/consumer-subscription.png"/>
+
+### 状态收敛
+
+关于以上双注册、双订阅行为的更多详细解释，以及如何尽快完成服务发现模型的收敛，请参考博客文章 [Dubbo3 服务发现平滑迁移步骤与原理](/zh-cn/blog/2024/05/13/如果从接口级服务发现平滑迁移到应用级服务发现/)。
+
diff --git a/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/migration-triple.md b/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/migration-triple.md
index da20bd6..bc646f6 100644
--- a/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/migration-triple.md
+++ b/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/migration-triple.md
@@ -2,349 +2,106 @@
aliases:
- /zh/docs3-v2/java-sdk/upgrades-and-compatibility/migration-triple/
- /zh-cn/docs3-v2/java-sdk/upgrades-and-compatibility/migration-triple/
-description: Triple 协议迁移指南
-linkTitle: Dubbo 协议迁移至 Triple 协议
-title: Dubbo 协议迁移至 Triple 协议
+description: "如何平滑的从 dubbo 协议升级到 triple 协议。"
+linkTitle: 升级到triple协议
+title: 升级到triple协议
type: docs
-weight: 7
+weight: 2
---
-
-
-
-
-
-## Triple 协议介绍
-
-根据 Triple 设计的目标，`Triple` 协议有以下优势:
-
-- 具备跨语言交互的能力，传统的多语言多 SDK 模式和 Mesh 化跨语言模式都需要一种更通用易扩展的数据传输协议。
-- 提供更完善的请求模型，除了支持传统的 Request/Response 模型（Unary 单向通信），还支持 Stream（流式通信） 和 Bidirectional（双向通信）。
-- 易扩展、穿透性高，包括但不限于 Tracing / Monitoring 等支持，也应该能被各层设备识别，网关设施等可以识别数据报文，对 Service Mesh 部署友好，降低用户理解难度。
-- 完全兼容 grpc，客户端/服务端可以与原生grpc客户端打通。
-- 可以复用现有 grpc 生态下的组件, 满足云原生场景下的跨语言、跨环境、跨平台的互通需求。
-
-当前使用其他协议的 Dubbo 用户，框架提供了兼容现有序列化方式的迁移能力，在不影响线上已有业务的前提下，迁移协议的成本几乎为零。
-
-需要新增对接 Grpc 服务的 Dubbo 用户，可以直接使用 Triple 协议来实现打通，不需要单独引入 grpc client 来完成，不仅能保留已有的 Dubbo 易用性，也能降低程序的复杂度和开发运维成本，不需要额外进行适配和开发即可接入现有生态。
-
-对于需要网关接入的 Dubbo 用户，Triple 协议提供了更加原生的方式，让网关开发或者使用开源的 grpc 网关组件更加简单。网关可以选择不解析 payload ，在性能上也有很大提高。在使用 Dubbo 协议时，语言相关的序列化方式是网关的一个很大痛点，而传统的 HTTP 转 Dubbo 的方式对于跨语言序列化几乎是无能为力的。同时，由于 Triple 的协议元数据都存储在请求头中，网关可以轻松的实现定制需求，如路由和限流等功能。
-
-> `Triple` 协议的格式和原理请参阅 [RPC 通信协议](/zh-cn/docs/concepts/rpc-protocol/)
-
-## Dubbo2 协议迁移流程
-
-Dubbo2 的用户使用 dubbo 协议 + 自定义序列化，如 hessian2 完成远程调用。
-
-而 Grpc 的默认仅支持 Protobuf 序列化，对于 Java 语言中的多参数以及方法重载也无法支持。
-
-Dubbo3的之初就有一条目标是完美兼容 Dubbo2，所以为了 Dubbo2 能够平滑升级， Dubbo 框架侧做了很多工作来保证升级的无感，目前默认的序列化和 Dubbo2 保持一致为`hessian2`。
-
-所以，如果决定要升级到 Dubbo3 的 `Triple` 协议，只需要修改配置中的协议名称为 `tri` (注意: 不是triple)即可。
-
-接下来我们我们以一个使用 Dubbo2 协议的[工程](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration) 来举例，如何一步一步安全的升级。
-
-1. 仅使用 `dubbo` 协议启动 `provider` 和 `consumer`，并完成调用。
-2. 使用 `dubbo` 和 `tri` 协议 启动`provider`，以 `dubbo` 协议启动 `consumer`，并完成调用。
-3. 仅使用 `tri` 协议 启动 `provider`和 `consumer`，并完成调用。
-
-### 定义服务
-
-1. 定义接口
-```java
-public interface IWrapperGreeter {
-
- //...
-
- /**
- * 这是一个普通接口，没有使用 pb 序列化
- */
- String sayHello(String request);
-
-}
-```
-
-2. 实现类如下
-```java
-public class IGreeter2Impl implements IWrapperGreeter {
-
- @Override
- public String sayHello(String request) {
- return "hello," + request;
- }
-}
-```
-
-### 仅使用 triple 协议
-
-当所有的 consuemr 都升级至支持 `Triple` 协议的版本后，provider 可切换至仅使用 `Triple` 协议启动
-
-结构如图所示:
-
-
-[Provider](https://github.com/apache/dubbo-samples/blob/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationTriProvider.java)
-和 [Consumer](https://github.com/apache/dubbo-samples/blob/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationTriConsumer.java) 完成调用，输出如下:
-
-
-
-### 仅使用 dubbo 协议
-
-为保证兼容性，我们先将部分 provider 升级到 `dubbo3` 版本并使用 `dubbo` 协议。
-
-使用 `dubbo` 协议启动一个 [`Provider`](https://github.com/apache/dubbo-samples/blob/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationDubboProvider.java) 和 [`Consumer`](https://github.com/apache/dubbo-samples/blob/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationDubboConsumer.java) ,完成调用，输出如下:
-
-
-### 同时使用两协议
-
-对于线上服务的升级，不可能一蹴而就同时完成 provider 和 consumer 升级, 需要按步操作，保证业务稳定。
-第二步, provider 提供双协议的方式同时支持 dubbo + tri 两种协议的客户端。
-
-结构如图所示:
-
-
-> 按照推荐升级步骤，provider 已经支持了tri协议，所以 dubbo3的 consumer 可以直接使用 tri 协议
-
-使用`dubbo`协议和`triple`协议启动[`Provider`](https://github.com/apache/dubbo-samples/blob/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationBothProvider.java)和[`Consumer`](https://github.com/apache/dubbo-samples/blob/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationBothConsumer.java),完成调用，输出如下:
-
-
-
-
-### 实现原理
-
-通过上面介绍的升级过程，我们可以很简单的通过修改协议类型来完成升级。框架是怎么帮我们做到这些的呢？
-
-通过对 `Triple` 协议的介绍，我们知道Dubbo3的 `Triple` 的数据类型是 `protobuf` 对象，那为什么非 `protobuf` 的 java 对象也可以被正常传输呢。
-
-这里 Dubbo3 使用了一个巧妙的设计，首先判断参数类型是否为 `protobuf` 对象，如果不是。用一个 `protobuf` 对象将 `request` 和 `response` 进行 wrapper，这样就屏蔽了其他各种序列化带来的复杂度。在 `wrapper` 对象内部声明序列化类型，来支持序列化的扩展。
-
-wrapper 的`protobuf`的 IDL如下:
-```proto
-syntax = "proto3";
-
-package org.apache.dubbo.triple;
-
-message TripleRequestWrapper {
- // hessian4
- // json
- string serializeType = 1;
- repeated bytes args = 2;
- repeated string argTypes = 3;
-}
-
-message TripleResponseWrapper {
- string serializeType = 1;
- bytes data = 2;
- string type = 3;
-}
-```
-
-对于请求，使用`TripleRequestWrapper`进行包装，对于响应使用`TripleResponseWrapper`进行包装。
-
-> 对于请求参数，可以看到 args 被`repeated`修饰，这是因为需要支持 java 方法的多个参数。当然，序列化只能是一种。序列化的实现沿用 Dubbo2 实现的 spi
-
-
-## 多语言用户
-
-使用 `protobuf` 建议新服务均使用该方式，对于 Dubbo3 和 Triple 来说，主推的是使用 `protobuf` 序列化，并且使用 `proto` 定义的 `IDL` 来生成相关接口定义。以 `IDL` 做为多语言中的通用接口约定，加上 `Triple` 与 `Grpc` 的天然互通性，可以轻松地实现跨语言交互，例如 Go 语言等。
-
-将编写好的 `.proto` 文件使用 `dubbo-compiler` 插件进行编译并编写实现类，完成方法调用：
-
-
-
-从上面升级的例子我们可以知道，`Triple` 协议使用 `protbuf` 对象序列化后进行传输，所以对于本身就是 `protobuf` 对象的方法来说，没有任何其他逻辑。
-
-使用 `protobuf` 插件编译后接口如下：
-```java
-public interface PbGreeter {
-
- static final String JAVA_SERVICE_NAME = "org.apache.dubbo.sample.tri.PbGreeter";
- static final String SERVICE_NAME = "org.apache.dubbo.sample.tri.PbGreeter";
-
- static final boolean inited = PbGreeterDubbo.init();
-
- org.apache.dubbo.sample.tri.GreeterReply greet(org.apache.dubbo.sample.tri.GreeterRequest request);
-
- default CompletableFuture<org.apache.dubbo.sample.tri.GreeterReply> greetAsync(org.apache.dubbo.sample.tri.GreeterRequest request){
- return CompletableFuture.supplyAsync(() -> greet(request));
- }
-
- void greetServerStream(org.apache.dubbo.sample.tri.GreeterRequest request, org.apache.dubbo.common.stream.StreamObserver<org.apache.dubbo.sample.tri.GreeterReply> responseObserver);
-
- org.apache.dubbo.common.stream.StreamObserver<org.apache.dubbo.sample.tri.GreeterRequest> greetStream(org.apache.dubbo.common.stream.StreamObserver<org.apache.dubbo.sample.tri.GreeterReply> responseObserver);
-}
-```
-
-## Triple 新特性 Stream 流
-Stream 是 Dubbo3 新提供的一种调用类型，在以下场景时建议使用流的方式:
-
-- 接口需要发送大量数据，这些数据无法被放在一个 RPC 的请求或响应中，需要分批发送，但应用层如果按照传统的多次 RPC 方式无法解决顺序和性能的问题，如果需要保证有序，则只能串行发送
-- 流式场景，数据需要按照发送顺序处理, 数据本身是没有确定边界的
-- 推送类场景，多个消息在同一个调用的上下文中被发送和处理
-
-Stream 分为以下三种:
-- SERVER_STREAM(服务端流)
-
-- CLIENT_STREAM(客户端流)
-
-- BIDIRECTIONAL_STREAM(双向流)
-
-
-> 由于 `java` 语言的限制，BIDIRECTIONAL_STREAM 和 CLIENT_STREAM 的实现是一样的。
-
-在 Dubbo3 中，流式接口以 `SteamObserver` 声明和使用，用户可以通过使用和实现这个接口来发送和处理流的数据、异常和结束。
-
-> 对于 Dubbo2 用户来说，可能会对StreamObserver感到陌生，这是Dubbo3定义的一种流类型，Dubbo2 中并不存在 Stream 的类型，所以对于迁移场景没有任何影响。
-
-流的语义保证
-- 提供消息边界，可以方便地对消息单独处理
-- 严格有序，发送端的顺序和接收端顺序一致
-- 全双工，发送不需要等待
-- 支持取消和超时
-
-## 非 PB 序列化的流
-1. api
-```java
-public interface IWrapperGreeter {
-
- StreamObserver<String> sayHelloStream(StreamObserver<String> response);
-
- void sayHelloServerStream(String request, StreamObserver<String> response);
-}
-```
-
-> Stream 方法的方法入参和返回值是严格约定的，为防止写错而导致问题，Dubbo3 框架侧做了对参数的检查, 如果出错则会抛出异常。
-> 对于 `双向流(BIDIRECTIONAL_STREAM)`, 需要注意参数中的 `StreamObserver` 是响应流，返回参数中的 `StreamObserver` 为请求流。
-
-2. 实现类
-```java
-public class WrapGreeterImpl implements WrapGreeter {
-
- //...
-
- @Override
- public StreamObserver<String> sayHelloStream(StreamObserver<String> response) {
- return new StreamObserver<String>() {
- @Override
- public void onNext(String data) {
- System.out.println(data);
- response.onNext("hello,"+data);
- }
-
- @Override
- public void onError(Throwable throwable) {
- throwable.printStackTrace();
- }
-
- @Override
- public void onCompleted() {
- System.out.println("onCompleted");
- response.onCompleted();
- }
- };
- }
-
- @Override
- public void sayHelloServerStream(String request, StreamObserver<String> response) {
- for (int i = 0; i < 10; i++) {
- response.onNext("hello," + request);
- }
- response.onCompleted();
- }
-}
-```
-
-3. 调用方式
-```java
-delegate.sayHelloServerStream("server stream", new StreamObserver<String>() {
- @Override
- public void onNext(String data) {
- System.out.println(data);
- }
-
- @Override
- public void onError(Throwable throwable) {
- throwable.printStackTrace();
- }
-
- @Override
- public void onCompleted() {
- System.out.println("onCompleted");
- }
-});
-
-
-StreamObserver<String> request = delegate.sayHelloStream(new StreamObserver<String>() {
- @Override
- public void onNext(String data) {
- System.out.println(data);
- }
-
- @Override
- public void onError(Throwable throwable) {
- throwable.printStackTrace();
- }
-
- @Override
- public void onCompleted() {
- System.out.println("onCompleted");
- }
-});
-for (int i = 0; i < n; i++) {
- request.onNext("stream request" + i);
-}
-request.onCompleted();
-```
-
-## Protobuf 序列化的流
-
-对于 `Protobuf` 序列化方式，推荐编写 `IDL` 使用 `compiler` 插件进行编译生成。生成的代码大致如下:
-```java
-public interface PbGreeter {
-
- static final String JAVA_SERVICE_NAME = "org.apache.dubbo.sample.tri.PbGreeter";
- static final String SERVICE_NAME = "org.apache.dubbo.sample.tri.PbGreeter";
-
- static final boolean inited = PbGreeterDubbo.init();
-
- //...
-
- void greetServerStream(org.apache.dubbo.sample.tri.GreeterRequest request, org.apache.dubbo.common.stream.StreamObserver<org.apache.dubbo.sample.tri.GreeterReply> responseObserver);
-
- org.apache.dubbo.common.stream.StreamObserver<org.apache.dubbo.sample.tri.GreeterRequest> greetStream(org.apache.dubbo.common.stream.StreamObserver<org.apache.dubbo.sample.tri.GreeterReply> responseObserver);
-}
-```
-
-## 流的实现原理
-
-`Triple`协议的流模式是怎么支持的呢？
-
-- 从协议层来说，`Triple` 是建立在 `HTTP2` 基础上的，所以直接拥有所有 `HTTP2` 的能力，故拥有了分 `stream` 和全双工的能力。
-
-- 框架层来说，`StreamObserver` 作为流的接口提供给用户，用于入参和出参提供流式处理。框架在收发 stream data 时进行相应的接口调用, 从而保证流的生命周期完整。
-
-## Triple 与应用级注册发现
-
-关于 Triple 协议的应用级服务注册和发现和其他语言是一致的，可以通过下列内容了解更多。
-
-- [服务发现](/zh-cn/docs/concepts/service-discovery/)
-- [应用级地址发现迁移指南](/zh-cn/docs/migration/migration-service-discovery/)
-
-## 与 GRPC 互通
-
-通过对于协议的介绍，我们知道 `Triple` 协议是基于 `HTTP2` 并兼容 `GRPC`。为了保证和验证与`GRPC`互通能力，Dubbo3 也编写了各种从场景下的测试。详细的可以通过[这里](https://github.com/apache/dubbo-samples/blob/master/3-extensions/protocol/dubbo-samples-triple/README.MD) 了解更多。
-
-
-{{% alert title="未来: Everything on Stub" color="primary" %}}
-
-用过 `Grpc` 的同学应该对 `Stub` 都不陌生。
-Grpc 使用 `compiler` 将编写的 `proto` 文件编译为相关的 protobuf 对象和相关 rpc 接口。默认的会同时生成几种不同的 `stub`
-
-- blockingStub
-- futureStub
-- reactorStub
-- ...
-
-`stub` 用一种统一的使用方式帮我们屏蔽了不同调用方式的细节。不过目前 `Dubbo3` 暂时只支持传统定义接口并进行调用的使用方式。
-
-在不久的未来，`Triple` 也将实现各种常用的 `Stub`，让用户写一份`proto`文件，通过 `comipler` 可以在任意场景方便的使用，请拭目以待。
+{{% alert title="请注意" color="warning" %}}
+* 本文档内容并不是升级 Dubbo3 必须的，您完全可以只升级框架并继续使用 dubbo 通信协议。
+* 如果您是 Dubbo 新用户，强烈建议直接 [使用 triple 协议](/zh-cn/overview/mannual/java-sdk/tasks/protocol/) 即可。
{{% /alert %}}
+
+本文档适合服务已经运行在 dubbo 协议之上的老用户，请先参考上一篇文档 [如何从 Dubbo2 升级到 Dubbo3](../migration/) 完成框架版本升级，然后遵循以下步骤以最小改动平滑迁移到 triple 协议。
+
+以下是协议升级的架构图，展示了平滑升级过程中不同 Dubbo 应用的状态：
+
+
+<img alt="dubbo协议迁移到tirple协议" style="max-width:800px;height:auto;" src="/imgs/v3/manual/java/migration/dubbo-to-triple.png"/>
+
+按先后顺序，升级基本步骤如下：
+1. Provider 提供者侧配置单端口双协议（dubbo、triple）发布
+2. Provider 提供者侧配置首选协议为 triple（此时，提供者注册的URL地址为 `dubbo://host:port/DemoService?preferred-protocol=tri`）
+3. Consumer 消费者升级，根据情况不同有以下两种方式：
+ * 升级消费者到 3.3 版本，消费者会根据 `preferred-protocol=tri` 优先调用 triple 协议
+ * 无法升级到 3.3 版本的消费者应用，可以配置 `@DubboReference(protocol="tri")` 调用 triple 协议
+4. 推动所有应用升级到最新 Dubbo3 版本，最终所有流量都是 triple 协议
+
+{{% alert title="请注意" color="warning" %}}
+请注意，以上提到的单端口多协议、识别 `preferred-protocol` 首选协议等功能，需要 Dubbo 3.3.0+ 版本！
+{{% /alert %}}
+
+### 步骤一：提供者双协议发布
+假设我们有以下应用配置，即在 20880 端口发布 dubbo 协议：
+```yaml
+dubbo:
+ protocol:
+ name: dubbo
+ port: 20880
+```
+
+我们需要增加两个配置项，如下所示：
+
+```yaml
+dubbo:
+ protocol:
+ name: dubbo
+ port: 20880
+ ext-protocol: tri
+ preferred-protocol: tri
+```
+
+其中，
+* `ext-protocol: tri` 指定在原 20880 端口上额外发布 triple 协议，即单端口双协议发布。
+* `preferred-protocol: tri` 会随注册中心同步到 Consumer 侧，告诉 consumer 优先使用 triple 协议调用
+
+{{% alert title="注意" color="warning" %}}
+`preferred-protocol: tri` 配置仅在 3.3.0 及之后版本支持，所以即使 provider 配置了这个选项，对于 3.3.0 版本即之前的 consumer 消费端并不会生效，还是会调用 dubbo 协议。
+{{% /alert %}}
+
+### 步骤二：消费端切换协议
+提供端完成步骤一配置并重启后，消费端根据版本与配置不同，可能处于以下三种状态之一：
+
+**1. 消费端是 3.3.0 及之后版本**
+
+此类消费端会自动识别提供者 url 上的 `preferred-protocol: tri` 标记，如果发现此标记，则消费端自动使用 triple 协议调用服务，否则继续使用 dubbo 协议。
+
+**2. 消费端是 2.x 或 3.3.0 之前版本**
+
+由于低版本 Dubbo 框架不能识别 `preferred-protocol: tri` 参数，因此这部分消费者不受提供者端多协议发布的任何影响，继续调用 dubbo 协议。
+
+**3. 消费端是 2.x 或 3.3.0 之前版本，且额外指定要调用的协议**
+
+与第 2 种情况基本一致，只是这时用户可以明确的为某些服务指定使用哪种 rpc 协议，如：
+
+```java
+@DubboReference(protocol="tri")
+private DemoService demoService;
+```
+
+或者
+
+```xml
+<dubbo:reference protocol="tri" />
+```
+
+在配置了 `protocol="tri"` 后，服务的调用会使用 triple 协议。需要注意的是，在配置 `protocol="tri"` 之前，一定要确保提供端已经发布了 triple 协议支持，否则调用将会失败。
+
+{{% alert title="注意" color="warning" %}}
+* 从以上三种情况可知，协议升级过程对消费端完全无感，消费端不会因提供端的多协议配置而出现任何通信障碍。
+* 对于消费端，最简单的协议切换方式就是通过 `preferred-protocol=tri` 进行自动切换，需要两边版本都升级到 3.3.0+ 才支持。
+{{% /alert %}}
+
+### 步骤三：完全收敛到triple协议
+步骤一、二操作起来非常简单，并且保证了过程平滑，通过单端口双协议、消费端自动切换保证了整个升级过程的平滑。
+
+平滑升级意味着我们要经历一个中间态，即在某一段时间内，集群内 dubbo 协议、triple 协议共存（有些服务间通信是dubbo协议、有些服务间通信是triple协议）。如何才能推进达成终态目标那，即所有服务调用都使用 triple 协议？我们推荐使用以下两种方式达成目标：
+* 推进集群内所有 Dubbo 应用都升级到 3.3.x 最新版本，这样消费端就能自动切换到 triple 协议
+* 通过 Dubbo 框架的指标埋点，观察某个应用（作为provider）是否仍在处理 dubbo 流量，对这部分应用的上下游进行治理
+
+{{% alert title="注意" color="info" %}}
+对于 Dubbo 框架而言，集群内 dubbo 协议和 triple 协议共存的状态并不存在任何技术问题，不同的服务调用使用不同协议也很正常，因此双协议共存的中间态是完全可以接受的。但有时候为了整体方案统一，我们可能需要达成单一通信协议的终态目标。
+{{% /alert %}}
+
diff --git a/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/migration-triple.md.bak b/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/migration-triple.md.bak
new file mode 100644
index 0000000..910d130
--- /dev/null
+++ b/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/migration-triple.md.bak
@@ -0,0 +1,346 @@
+---
+aliases:
+ - /zh/docs3-v2/java-sdk/upgrades-and-compatibility/migration-triple/
+ - /zh-cn/docs3-v2/java-sdk/upgrades-and-compatibility/migration-triple/
+description: Triple 协议迁移指南
+linkTitle: Dubbo 协议迁移至 Triple 协议
+title: Dubbo 协议迁移至 Triple 协议
+type: docs
+weight: 7
+---
+
+
+## Triple 协议介绍
+
+根据 Triple 设计的目标，`Triple` 协议有以下优势:
+
+- 具备跨语言交互的能力，传统的多语言多 SDK 模式和 Mesh 化跨语言模式都需要一种更通用易扩展的数据传输协议。
+- 提供更完善的请求模型，除了支持传统的 Request/Response 模型（Unary 单向通信），还支持 Stream（流式通信） 和 Bidirectional（双向通信）。
+- 易扩展、穿透性高，包括但不限于 Tracing / Monitoring 等支持，也应该能被各层设备识别，网关设施等可以识别数据报文，对 Service Mesh 部署友好，降低用户理解难度。
+- 完全兼容 grpc，客户端/服务端可以与原生grpc客户端打通。
+- 可以复用现有 grpc 生态下的组件, 满足云原生场景下的跨语言、跨环境、跨平台的互通需求。
+
+当前使用其他协议的 Dubbo 用户，框架提供了兼容现有序列化方式的迁移能力，在不影响线上已有业务的前提下，迁移协议的成本几乎为零。
+
+需要新增对接 Grpc 服务的 Dubbo 用户，可以直接使用 Triple 协议来实现打通，不需要单独引入 grpc client 来完成，不仅能保留已有的 Dubbo 易用性，也能降低程序的复杂度和开发运维成本，不需要额外进行适配和开发即可接入现有生态。
+
+对于需要网关接入的 Dubbo 用户，Triple 协议提供了更加原生的方式，让网关开发或者使用开源的 grpc 网关组件更加简单。网关可以选择不解析 payload ，在性能上也有很大提高。在使用 Dubbo 协议时，语言相关的序列化方式是网关的一个很大痛点，而传统的 HTTP 转 Dubbo 的方式对于跨语言序列化几乎是无能为力的。同时，由于 Triple 的协议元数据都存储在请求头中，网关可以轻松的实现定制需求，如路由和限流等功能。
+
+> `Triple` 协议的格式和原理请参阅 [RPC 通信协议](/zh-cn/docs/concepts/rpc-protocol/)
+
+## Dubbo2 协议迁移流程
+
+Dubbo2 的用户使用 dubbo 协议 + 自定义序列化，如 hessian2 完成远程调用。
+
+而 Grpc 的默认仅支持 Protobuf 序列化，对于 Java 语言中的多参数以及方法重载也无法支持。
+
+Dubbo3的之初就有一条目标是完美兼容 Dubbo2，所以为了 Dubbo2 能够平滑升级， Dubbo 框架侧做了很多工作来保证升级的无感，目前默认的序列化和 Dubbo2 保持一致为`hessian2`。
+
+所以，如果决定要升级到 Dubbo3 的 `Triple` 协议，只需要修改配置中的协议名称为 `tri` (注意: 不是triple)即可。
+
+接下来我们我们以一个使用 Dubbo2 协议的[工程](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration) 来举例，如何一步一步安全的升级。
+
+1. 仅使用 `dubbo` 协议启动 `provider` 和 `consumer`，并完成调用。
+2. 使用 `dubbo` 和 `tri` 协议 启动`provider`，以 `dubbo` 协议启动 `consumer`，并完成调用。
+3. 仅使用 `tri` 协议 启动 `provider`和 `consumer`，并完成调用。
+
+### 定义服务
+
+1. 定义接口
+```java
+public interface IWrapperGreeter {
+
+ //...
+
+ /**
+ * 这是一个普通接口，没有使用 pb 序列化
+ */
+ String sayHello(String request);
+
+}
+```
+
+2. 实现类如下
+```java
+public class IGreeter2Impl implements IWrapperGreeter {
+
+ @Override
+ public String sayHello(String request) {
+ return "hello," + request;
+ }
+}
+```
+
+### 仅使用 triple 协议
+
+当所有的 consuemr 都升级至支持 `Triple` 协议的版本后，provider 可切换至仅使用 `Triple` 协议启动
+
+结构如图所示:
+
+
+[Provider](https://github.com/apache/dubbo-samples/blob/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationTriProvider.java)
+和 [Consumer](https://github.com/apache/dubbo-samples/blob/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationTriConsumer.java) 完成调用，输出如下:
+
+
+
+### 仅使用 dubbo 协议
+
+为保证兼容性，我们先将部分 provider 升级到 `dubbo3` 版本并使用 `dubbo` 协议。
+
+使用 `dubbo` 协议启动一个 [`Provider`](https://github.com/apache/dubbo-samples/blob/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationDubboProvider.java) 和 [`Consumer`](https://github.com/apache/dubbo-samples/blob/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationDubboConsumer.java) ,完成调用，输出如下:
+
+
+### 同时使用两协议
+
+对于线上服务的升级，不可能一蹴而就同时完成 provider 和 consumer 升级, 需要按步操作，保证业务稳定。
+第二步, provider 提供双协议的方式同时支持 dubbo + tri 两种协议的客户端。
+
+结构如图所示:
+
+
+> 按照推荐升级步骤，provider 已经支持了tri协议，所以 dubbo3的 consumer 可以直接使用 tri 协议
+
+使用`dubbo`协议和`triple`协议启动[`Provider`](https://github.com/apache/dubbo-samples/blob/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationBothProvider.java)和[`Consumer`](https://github.com/apache/dubbo-samples/blob/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationBothConsumer.java),完成调用，输出如下:
+
+
+
+
+### 实现原理
+
+通过上面介绍的升级过程，我们可以很简单的通过修改协议类型来完成升级。框架是怎么帮我们做到这些的呢？
+
+通过对 `Triple` 协议的介绍，我们知道Dubbo3的 `Triple` 的数据类型是 `protobuf` 对象，那为什么非 `protobuf` 的 java 对象也可以被正常传输呢。
+
+这里 Dubbo3 使用了一个巧妙的设计，首先判断参数类型是否为 `protobuf` 对象，如果不是。用一个 `protobuf` 对象将 `request` 和 `response` 进行 wrapper，这样就屏蔽了其他各种序列化带来的复杂度。在 `wrapper` 对象内部声明序列化类型，来支持序列化的扩展。
+
+wrapper 的`protobuf`的 IDL如下:
+```proto
+syntax = "proto3";
+
+package org.apache.dubbo.triple;
+
+message TripleRequestWrapper {
+ // hessian4
+ // json
+ string serializeType = 1;
+ repeated bytes args = 2;
+ repeated string argTypes = 3;
+}
+
+message TripleResponseWrapper {
+ string serializeType = 1;
+ bytes data = 2;
+ string type = 3;
+}
+```
+
+对于请求，使用`TripleRequestWrapper`进行包装，对于响应使用`TripleResponseWrapper`进行包装。
+
+> 对于请求参数，可以看到 args 被`repeated`修饰，这是因为需要支持 java 方法的多个参数。当然，序列化只能是一种。序列化的实现沿用 Dubbo2 实现的 spi
+
+
+## 多语言用户
+
+使用 `protobuf` 建议新服务均使用该方式，对于 Dubbo3 和 Triple 来说，主推的是使用 `protobuf` 序列化，并且使用 `proto` 定义的 `IDL` 来生成相关接口定义。以 `IDL` 做为多语言中的通用接口约定，加上 `Triple` 与 `Grpc` 的天然互通性，可以轻松地实现跨语言交互，例如 Go 语言等。
+
+将编写好的 `.proto` 文件使用 `dubbo-compiler` 插件进行编译并编写实现类，完成方法调用：
+
+
+
+从上面升级的例子我们可以知道，`Triple` 协议使用 `protbuf` 对象序列化后进行传输，所以对于本身就是 `protobuf` 对象的方法来说，没有任何其他逻辑。
+
+使用 `protobuf` 插件编译后接口如下：
+```java
+public interface PbGreeter {
+
+ static final String JAVA_SERVICE_NAME = "org.apache.dubbo.sample.tri.PbGreeter";
+ static final String SERVICE_NAME = "org.apache.dubbo.sample.tri.PbGreeter";
+
+ static final boolean inited = PbGreeterDubbo.init();
+
+ org.apache.dubbo.sample.tri.GreeterReply greet(org.apache.dubbo.sample.tri.GreeterRequest request);
+
+ default CompletableFuture<org.apache.dubbo.sample.tri.GreeterReply> greetAsync(org.apache.dubbo.sample.tri.GreeterRequest request){
+ return CompletableFuture.supplyAsync(() -> greet(request));
+ }
+
+ void greetServerStream(org.apache.dubbo.sample.tri.GreeterRequest request, org.apache.dubbo.common.stream.StreamObserver<org.apache.dubbo.sample.tri.GreeterReply> responseObserver);
+
+ org.apache.dubbo.common.stream.StreamObserver<org.apache.dubbo.sample.tri.GreeterRequest> greetStream(org.apache.dubbo.common.stream.StreamObserver<org.apache.dubbo.sample.tri.GreeterReply> responseObserver);
+}
+```
+
+## Triple 新特性 Stream 流
+Stream 是 Dubbo3 新提供的一种调用类型，在以下场景时建议使用流的方式:
+
+- 接口需要发送大量数据，这些数据无法被放在一个 RPC 的请求或响应中，需要分批发送，但应用层如果按照传统的多次 RPC 方式无法解决顺序和性能的问题，如果需要保证有序，则只能串行发送
+- 流式场景，数据需要按照发送顺序处理, 数据本身是没有确定边界的
+- 推送类场景，多个消息在同一个调用的上下文中被发送和处理
+
+Stream 分为以下三种:
+- SERVER_STREAM(服务端流)
+
+- CLIENT_STREAM(客户端流)
+
+- BIDIRECTIONAL_STREAM(双向流)
+
+
+> 由于 `java` 语言的限制，BIDIRECTIONAL_STREAM 和 CLIENT_STREAM 的实现是一样的。
+
+在 Dubbo3 中，流式接口以 `SteamObserver` 声明和使用，用户可以通过使用和实现这个接口来发送和处理流的数据、异常和结束。
+
+> 对于 Dubbo2 用户来说，可能会对StreamObserver感到陌生，这是Dubbo3定义的一种流类型，Dubbo2 中并不存在 Stream 的类型，所以对于迁移场景没有任何影响。
+
+流的语义保证
+- 提供消息边界，可以方便地对消息单独处理
+- 严格有序，发送端的顺序和接收端顺序一致
+- 全双工，发送不需要等待
+- 支持取消和超时
+
+## 非 PB 序列化的流
+1. api
+```java
+public interface IWrapperGreeter {
+
+ StreamObserver<String> sayHelloStream(StreamObserver<String> response);
+
+ void sayHelloServerStream(String request, StreamObserver<String> response);
+}
+```
+
+> Stream 方法的方法入参和返回值是严格约定的，为防止写错而导致问题，Dubbo3 框架侧做了对参数的检查, 如果出错则会抛出异常。
+> 对于 `双向流(BIDIRECTIONAL_STREAM)`, 需要注意参数中的 `StreamObserver` 是响应流，返回参数中的 `StreamObserver` 为请求流。
+
+2. 实现类
+```java
+public class WrapGreeterImpl implements WrapGreeter {
+
+ //...
+
+ @Override
+ public StreamObserver<String> sayHelloStream(StreamObserver<String> response) {
+ return new StreamObserver<String>() {
+ @Override
+ public void onNext(String data) {
+ System.out.println(data);
+ response.onNext("hello,"+data);
+ }
+
+ @Override
+ public void onError(Throwable throwable) {
+ throwable.printStackTrace();
+ }
+
+ @Override
+ public void onCompleted() {
+ System.out.println("onCompleted");
+ response.onCompleted();
+ }
+ };
+ }
+
+ @Override
+ public void sayHelloServerStream(String request, StreamObserver<String> response) {
+ for (int i = 0; i < 10; i++) {
+ response.onNext("hello," + request);
+ }
+ response.onCompleted();
+ }
+}
+```
+
+3. 调用方式
+```java
+delegate.sayHelloServerStream("server stream", new StreamObserver<String>() {
+ @Override
+ public void onNext(String data) {
+ System.out.println(data);
+ }
+
+ @Override
+ public void onError(Throwable throwable) {
+ throwable.printStackTrace();
+ }
+
+ @Override
+ public void onCompleted() {
+ System.out.println("onCompleted");
+ }
+});
+
+
+StreamObserver<String> request = delegate.sayHelloStream(new StreamObserver<String>() {
+ @Override
+ public void onNext(String data) {
+ System.out.println(data);
+ }
+
+ @Override
+ public void onError(Throwable throwable) {
+ throwable.printStackTrace();
+ }
+
+ @Override
+ public void onCompleted() {
+ System.out.println("onCompleted");
+ }
+});
+for (int i = 0; i < n; i++) {
+ request.onNext("stream request" + i);
+}
+request.onCompleted();
+```
+
+## Protobuf 序列化的流
+
+对于 `Protobuf` 序列化方式，推荐编写 `IDL` 使用 `compiler` 插件进行编译生成。生成的代码大致如下:
+```java
+public interface PbGreeter {
+
+ static final String JAVA_SERVICE_NAME = "org.apache.dubbo.sample.tri.PbGreeter";
+ static final String SERVICE_NAME = "org.apache.dubbo.sample.tri.PbGreeter";
+
+ static final boolean inited = PbGreeterDubbo.init();
+
+ //...
+
+ void greetServerStream(org.apache.dubbo.sample.tri.GreeterRequest request, org.apache.dubbo.common.stream.StreamObserver<org.apache.dubbo.sample.tri.GreeterReply> responseObserver);
+
+ org.apache.dubbo.common.stream.StreamObserver<org.apache.dubbo.sample.tri.GreeterRequest> greetStream(org.apache.dubbo.common.stream.StreamObserver<org.apache.dubbo.sample.tri.GreeterReply> responseObserver);
+}
+```
+
+## 流的实现原理
+
+`Triple`协议的流模式是怎么支持的呢？
+
+- 从协议层来说，`Triple` 是建立在 `HTTP2` 基础上的，所以直接拥有所有 `HTTP2` 的能力，故拥有了分 `stream` 和全双工的能力。
+
+- 框架层来说，`StreamObserver` 作为流的接口提供给用户，用于入参和出参提供流式处理。框架在收发 stream data 时进行相应的接口调用, 从而保证流的生命周期完整。
+
+## Triple 与应用级注册发现
+
+关于 Triple 协议的应用级服务注册和发现和其他语言是一致的，可以通过下列内容了解更多。
+
+- [服务发现](/zh-cn/docs/concepts/service-discovery/)
+- [应用级地址发现迁移指南](/zh-cn/docs/migration/migration-service-discovery/)
+
+## 与 GRPC 互通
+
+通过对于协议的介绍，我们知道 `Triple` 协议是基于 `HTTP2` 并兼容 `GRPC`。为了保证和验证与`GRPC`互通能力，Dubbo3 也编写了各种从场景下的测试。详细的可以通过[这里](https://github.com/apache/dubbo-samples/blob/master/3-extensions/protocol/dubbo-samples-triple/README.MD) 了解更多。
+
+
+{{% alert title="未来: Everything on Stub" color="primary" %}}
+
+用过 `Grpc` 的同学应该对 `Stub` 都不陌生。
+Grpc 使用 `compiler` 将编写的 `proto` 文件编译为相关的 protobuf 对象和相关 rpc 接口。默认的会同时生成几种不同的 `stub`
+
+- blockingStub
+- futureStub
+- reactorStub
+- ...
+
+`stub` 用一种统一的使用方式帮我们屏蔽了不同调用方式的细节。不过目前 `Dubbo3` 暂时只支持传统定义接口并进行调用的使用方式。
+
+在不久的未来，`Triple` 也将实现各种常用的 `Stub`，让用户写一份`proto`文件，通过 `comipler` 可以在任意场景方便的使用，请拭目以待。
+{{% /alert %}}
diff --git a/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/migration.md b/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/migration.md
index 34371fb..41fb53b 100644
--- a/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/migration.md
+++ b/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/migration.md
@@ -2,101 +2,303 @@
aliases:
- /zh/docs3-v2/java-sdk/reference-manual/protocol/triple/migration/
- /zh-cn/docs3-v2/java-sdk/reference-manual/protocol/triple/migration/
-description: Dubbo2 协议迁移
-linkTitle: Dubbo2 协议迁移
-title: Dubbo2 协议迁移
+description: "从 dubbo2 升级到 dubbo3：涵盖 2.6.x、2.5.x、2.7.x 等版本升级。"
+linkTitle: 升级到Dubbo3
+title: 从 dubbo2 升级到 dubbo3（涵盖 2.5.x、2.6.x、2.7.x 等版本）
type: docs
-weight: 10
+weight: 1
---
+总体来说，Dubbo2 升级到 Dubbo3 后的核心能力都是兼容的，对于 90% 以上的常规用户而言（指未做深度 SPI 扩展或源码定制的用户），可以非常简单的完成升级。
+## 2.7.x 升级 Dubbo3
+### 步骤一：升级核心依赖
+首先，在应用中增加 bom 依赖管理：
-
-## 迁移流程说明
-
-Dubbo2 的用户使用 dubbo 协议 + 自定义序列化，如 hessian2 完成远程调用。
-
-而 Grpc 的默认仅支持 Protobuf 序列化，对于 Java 语言中的多参数以及方法重载也无法支持。
-
-Dubbo3 的之初就有一条目标是完美兼容 Dubbo2，所以为了 Dubbo2 能够平滑升级， Dubbo 框架侧做了很多工作来保证升级的无感，目前默认的序列化和 Dubbo2 保持一致为 `hessian2`。
-
-所以，如果决定要升级到 Dubbo3 的 `Triple` 协议，只需要修改配置中的协议名称为 `tri` (注意: 不是 triple )即可。
-
-接下来我们以一个使用 Dubbo2 协议的[工程](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration)来举例，如何一步一步安全的升级。
-
-1. 仅使用 `dubbo` 协议启动 `provider` 和 `consumer`，并完成调用。
-2. 仅使用 `tri` 协议启动 `provider` 和 `consumer`，并完成调用。
-3. 使用 `dubbo` 协议和 `tri` 协议 启动 `provider`，以 `dubbo` 协议启动 `consumer`，并完成调用。
-
-### 定义服务
-
-1. 定义接口
-```java
-public interface IWrapperGreeter {
-
- //...
-
- /**
- * 这是一个普通接口，没有使用 pb 序列化
- */
- String sayHello(String request);
-
-}
+```xml
+<dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.dubbo</groupId>
+ <artifactId>dubbo-dependencies-bom</artifactId>
+ <version>3.3.0</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ </dependencies>
+</dependencyManagement>
```
-2. 实现类示例
-```java
-public class IGreeter2Impl implements IWrapperGreeter {
+如果您之前用的是 `org.apache.dubbo:dubbo` 依赖，请升级到以下版本（如果项目中还有其它 dubbo 子模块依赖，请一并升级版本号）：
- @Override
- public String sayHello(String request) {
- return "hello," + request;
- }
-}
+```xml
+<dependency>
+ <groupId>org.apache.dubbo</groupId>
+ <artifactId>dubbo</artifactId>
+</dependency>
```
-### 仅使用 dubbo 协议
+如果之前的应用是 Spring Boot，建议使用以下 starter 依赖方式并升级到最新版本（如果之前未使用 starter，请删除所有老的 dubbo 模块依赖，直接使用以下配置即可）：
-为保证兼容性，我们先将部分 provider 升级到 `dubbo3` 版本并使用 `dubbo` 协议。
+```xml
+<dependency>
+ <groupId>org.apache.dubbo</groupId>
+ <artifactId>dubbo-spring-boot-starter</artifactId>
+</dependency>
+```
-使用 `dubbo` 协议启动一个 [`Provider`](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationDubboProvider.java) 和 [`Consumer`](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationDubboConsumer.java) 完成调用。
-
-{{% alert title="输出结果" color="info" %}}
-
+{{% alert title="Dubbo3 相关的 Spring、Spring Boot 版本升级说明" color="warning" %}}
+Dubbo3 支持的 Spring、Spring Boot 版本兼容范围非常广：
+* 既支持 Spring 3.x ~ Spring 5.x 相关版本，同时也支持 Spring Boot 1.x ~ Spring Boot 2.x 版本。如果遇到应用无法升级高版本 Spring、Spring Boot 的情况下，可排掉 `dubbo-spring-boot-starter` 或 `dubbo` 中传递的高版本 Spring 依赖，指定项目可接受的 Spring 版本依赖即可。
+* Spring Boot 3.x 和 Spring 6 版本由于需要 JDK 17 及以上版本，请参考 [Dubbo Spring Boot 手册]() 了解详情。
{{% /alert %}}
-### 仅使用 triple 协议
+### 步骤二：升级其它组件依赖
+1. Nacos 注册中心
-当所有的 consumer 都升级至支持 `Triple` 协议的版本后，provider 可切换至仅使用 `Triple` 协议启动
+ 如果您使用的是 Nacos 注册中心，在升级到 Dubbo3 之前，请先确保 Nacos Server 升级到 2.x 版本。除了 Nacos Server 之外，我们还需要升级应用侧的 Nacos Client 依赖。
-结构如图所示:
-
+ 如果是 Spring Boot 应用，则可删除 nacos-client 依赖，直接使用 starter：
-[Provider](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationTriProvider.java)
-和 [Consumer](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationTriConsumer.java) 完成调用。
+ ```xml
+ <dependency>
+ <groupId>org.apache.dubbo</groupId>
+ <artifactId>dubbo-nacos-spring-boot-starter</artifactId>
+ </dependency>
+ ```
+ 如果您当前不是 Spring Boot 应用，则直接更新 nacos-client 到 2.x 即可：
-{{% alert title="输出结果" color="info" %}}
-
+ ```xml
+ <dependency>
+ <groupId>com.alibaba</groupId>
+ <artifactId>nacos-client</artifactId>
+ <version>2.3.0</version>
+ </dependency>
+ ```
+
+2. Zookeeper 注册中心
+
+ 如果是 Spring Boot 应用，则可删除之前老的 Zookeeper 相关依赖，直接使用 starter：
+
+ ```xml
+ <dependency>
+ <groupId>org.apache.dubbo</groupId>
+ <artifactId>dubbo-zookeeper-curator5-spring-boot-starter</artifactId>
+ </dependency>
+ ```
+
+ 请注意，以上 `dubbo-zookeeper-curator5-spring-boot-starter` 请搭配 Zookeeper Server 3.8.0+ 版本使用。如果您当前正在使用的 Zookeeper Server 版本是 3.4.x 版本，则使用以下 starter：
+
+ ```xml
+ <dependency>
+ <groupId>org.apache.dubbo</groupId>
+ <artifactId>dubbo-zookeeper-spring-boot-starter</artifactId>
+ </dependency>
+ ```
+
+ 如果不是 Spring Boot 应用，则可以使用以下依赖（推荐，需确保 Zookeeper Server 3.8.0 版本及以上）：
+
+ ```xml
+ <dependency>
+ <groupId>org.apache.dubbo</groupId>
+ <artifactId>dubbo-dependencies-zookeeper-curator5</artifactId>
+ </dependency>
+ ```
+
+ 或者（对于 Zookeeper Server 3.4.x 版本用户）
+
+ ```xml
+ <dependency>
+ <groupId>org.apache.dubbo</groupId>
+ <artifactId>dubbo-dependencies-zookeeper</artifactId>
+ </dependency>
+ ```
+ {{% alert title="Zookeeper升级注意事项" color="warning" %}}
+ 请注意在使用以上方式管理 zookeeper 客户端依赖时，请清理项目中的其它 zookeper、curator 等依赖，完全使用 dubbo 提供的版本。
+ {{% /alert %}}
+
+3. 其它组件升级
+
+ 除了注册中心之外，如果您有用到 Dubbo 的其它特性并且依赖第三方组件支持此特性，则您需要根据具体情况升级相应的组件版本，以确保组件能配合 Dubbo3 工作。
+
+{{% alert title="查看依赖的三方组件版本" color="info" %}}
+目的是确认项目中的三方依赖可以与 Dubbo3 正常工作（保持API兼容性）。正常来说，Dubbo 应用中并不会有非常多的第三方组件依赖，所以只要按需确认即可，另外，您可以参考 [Dubbo3 版本依赖的组件版本]() 确认合适的组件版本。
{{% /alert %}}
-### 同时使用 dubbo 和 triple 协议
-
-对于线上服务的升级，不可能一蹴而就同时完成 provider 和 consumer 升级, 需要按步操作，
-
-**第一步：保证业务稳定。**
-
-**第二步：provider 提供双协议的方式同时支持 dubbo + tri 两种协议的客户端。**
-
-结构如图所示:
-
-
-> 按照推荐升级步骤，provider 已经支持了 tri 协议，所以 dubbo3 的 consumer 可以直接使用 tri 协议
-
-使用 `dubbo` 协议和 `triple` 协议启动[`Provider`](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationBothProvider.java)和[`Consumer`](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationBothConsumer.java) 完成调用。
-
-{{% alert title="输出结果" color="info" %}}
-
+### 步骤三：兼容性检查
+{{% alert title="哪些用户需要做兼容性检查" color="info" %}}
+对于大部分常规用户来说，可以跳过这个环节，通常是当前对 Dubbo 有深度定制的用户需要关注（SPI 扩展或源码定制）！
{{% /alert %}}
+
+#### 检查点一：是否有 SPI 扩展
+
+1. 以下 SPI 扩展点在 Dubbo3 中已被移除，如有使用请注意：
+
+ * 事件总线。出于事件管理的复杂度原因，EventDispatcher 和 EventListener 在 Dubbo 3.x 的支持已经删除。如果有对应扩展机制的使用请考虑重构为对应 Dubbo 功能的扩展。
+
+2. 以下 SPI 扩展点的内部工作机制做了实现优化，可按需调整：
+
+ * Filter 拦截器机制。可以基于 Filter 拦截器对请求进行拦截处理，在 2.7 中支持在路由选址后再对请求进行拦截处理。Dubbo3 中新增了 `ClusterFilter` SPI 定义，相比于之前的 `Filter` 扩展点，`ClusterFilter` 可以在很大程度上降低内存的占用，对与超大规模集群有较大的收益。
+
+如果您有一些 Consumer 侧的拦截器是基于 Filter 扩展实现的，如果没有和远端的 IP 地址强绑定的逻辑，我们建议您将对应的 `org.apache.dubbo.rpc.Filter` SPI 扩展点迁移到 `org.apache.dubbo.rpc.cluster.filter.ClusterFilter` 这个新的 SPI 扩展点。
+
+{{% alert title="警告" color="info" %}}
+`org.apache.dubbo.rpc.Filter` 与 `org.apache.dubbo.rpc.cluster.filter.ClusterFilter` 在 Dubbo3 中同时支持，ClusterFilter 适配可按需调整，之前老的 Filter 实现都会继续生效，无需担心。
+{{% /alert %}}
+
+#### 检查点二：是否存在源码定制
+如果您正在使用的 Dubbo 框架包含一些私有源码定制（通过 javagent 或者 asm 等通过运行时对 Dubbo 的修改也在此范围内），则直接升级到开源 Dubbo3 版本可能有兼容性风险。对于这种非标准行为，Dubbo 无法保证其先前的兼容性，需要用户在升级前对所有源码修改进行检查，确保这部分内容完成对 Dubbo3 版本的适配后再升级上线。
+
+> 此类问题可通过一些字节码层面的工具实现，如将进程 metaspace 内容遍历导出，过滤出 Dubbo 所有相关类及调用，以识别业务中、二方包中等直接依赖或增强 Dubbo 框架内部源码的位置。判断这些源码调用在 Dubbo3 内部是否仍然存在，以决策下一步升级动作。
+
+### 步骤四：上线验证
+1. 灰度发布
+Dubbo 3 升级对于发布流程没有做特殊限制，按照正常业务发布即可。
+由于 Dubbo 是进行跨大版本的变更升级，发布中请尽可能多分批次发布，同时拉大第一批和第二批发布的时间间隔，做好充足的观察。
+发布过程中，我们建议您先升级应用的下游（也即是服务提供者），在验证服务处理正常以后再继续后续发布。
+
+2. 观测应用指标
+在发布的过程中，有以下几个纬度的指标可以判断升级是否出现问题。
+
+- 机器的 CPU、内存使用情况
+- 接口请求成功率
+- 接口请求 RT
+- 日志的报错信息
+- 自定义扩展行为是否符合预期
+
+## 2.6.x 及以下版本升级 Dubbo3
+
+以下内容是针对 2.6.x、2.5.x 及以下版本用户的，帮助了解如何升级到 Dubbo3 版本。对于这些版本的用户而言，80% 的用户都是可以通过替换依赖实现平滑升级的，按以下步骤升级并做好检查即可。
+
+### 步骤一：升级核心依赖
+
+首先，必须升级之前老的 `com.alibaba:dubbo` 依赖坐标升级为 `org.apache.dubbo:dubbo`。
+
+如下所示，将 `com.alibaba:dubbo` 依赖
+
+```xml
+<dependency>
+ <groupId>com.alibaba</groupId>
+ <artifactId>dubbo</artifactId>
+ <version>2.6.5</version>
+</dependency>
+```
+
+替换为 `org.apache.dubbo:dubbo` 依赖，其它配置文件不用修改，如下所示：
+
+```xml
+<properties>
+ <dubbo.version>3.3.0</dubbo.version>
+</properties>
+<dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.dubbo</groupId>
+ <artifactId>dubbo-dependencies-bom</artifactId>
+ <version>${dubbo.version}</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ </dependencies>
+</dependencyManagement>
+
+<dependencies>
+ <dependency>
+ <groupId>org.apache.dubbo</groupId>
+ <artifactId>dubbo</artifactId>
+ </dependency>
+</dependencies>
+```
+
+如果您是 Spring Boot 应用，则也可以使用 `org.apache.dubbo:dubbo-spring-boot-starter` 替换上面的 `org.apache.dubbo:dubbo` 依赖：
+
+```xml
+<dependencies>
+ <dependency>
+ <groupId>org.apache.dubbo</groupId>
+ <artifactId>dubbo-spring-boot-starter</artifactId>
+ </dependency>
+</dependencies>
+```
+
+### 步骤二：升级其它组件依赖
+
+您需要升级注册中心（Nacos、Zookeeper或其它）等第三方组件，具体升级方法和目标版本请参考本文前面一节的 [2.7.x 版本升级到 Dubbo3](./#步骤二升级其它组件依赖) 中的详细说明，两者操作方法完全一样。
+
+{{% alert title="请务必注意第三方组件的版本" color="info" %}}
+* 对于很多 Dubbo 2.6.x 及以下的老用户来说，可能用到的组件（如注册中心）都是比较老的版本，这时升级到 Dubbo3 之前请仔细分析一下都有哪些功能和核心依赖组件，以评估组件升级到的目标版本。
+* 对于部分 Zookeeper 用户而言，如果 Zookeeper 版本较老，建议先升级 Zookeeper Server 到 3.8.x 及以上版本，再使用 Dubbo3 的 `dubbo-zookeeper-curator5-spring-boot-starter` 管理依赖，如上文 [2.7.x 升级](./#步骤二升级其它组件依赖) 一节中所述。
+{{% /alert %}}
+
+### 步骤三：兼容性检查
+如果升级依赖后出现API或SPI扩展相关的编译错误，请参考下文。如果您的 Dubbo 用法中有很多 SPI 扩展实现、内部 API 调用、或者改了一些内核源码，则需要重点关注这一部分的兼容性检查。
+
+#### 检查点一：包名改造
+ Dubbo3 与 2.6.x 及以下版本最大的一个区别就是坐标、包名的变化：
+
+1. Maven 坐标 GAV
+
+**groupId 由 `com.alibaba` 改为 `org.apache.dubbo`**
+
+2. package
+
+**package 前缀由 `com.alibaba.dubbo.*` 改为 `org.apache.dubbo.*`**
+
+
+Maven坐标升级比较直观，只需要修改相应的pom文件就可以了；而package变更则可能会带来编译问题，但好在 Dubbo3 版本继续保留了绝大部分常用基础 API 和 SPI 的 `com.alibaba.dubbo` 适配支持，因此理论上升级 pom 后项目仍可直接编译成功。
+
+#### 检查点二：API编程接口
+
+- 注解
+
+| 注解 | 推荐的新注解 | 说明 |
+| --------------------- | ------------------ | ------------------ |
+| @Reference | @DubboReference | 消费端服务引用注解 |
+| @Service | @DubboService | 提供端服务暴露注解 |
+| @EnableDubbo | @EnableDubbo | |
+| 其他常用Spring注解API | 其他常用Spring注解API | |
+
+
+
+- 编程API
+
+| API | 说明 |
+| ----------------- | ----------------------------- |
+| ReferenceConfig | Service配置采集和引用编程接口 |
+| ServiceConfig | Service配置采集和暴露编程接口 |
+| ApplicationConfig | Application配置采集API |
+| RegistryConfig | 注册中心配置采集API |
+| ConsumerConfig | 消费端默认配置采集API |
+| ProviderConfig | 提供端默认配置采集API |
+| ProtocolConfig | RPC协议配置采集API |
+| ArgumentConfig | 服务参数级配置采集API |
+| MethodConfig | 服务方法级配置采集API |
+| ModuleConfig | 服务治理Module配置采集API |
+| MonitorConfig | 监控配置采集API |
+| RpcContext | 编程上下文API |
+
+
+#### 检查点三：SPI扩展
+
+如果公司内部有维护的自定义SPI扩展库，在业务工程升级到 Dubbo3 上线之前，请务必先确保扩展库与 Dubbo3 的兼容性。如果发现有兼容性问题，建议通过修改包名引用的方式（从实现 `com.alibaba.dubbo.*` 包名类到实现 `org.apache.dubbo.*` 包名类 ）完成升级，并重新打包。
+
+
+
+| SPI扩展点 | 说明 |
+| ------------- | ------------------------------------------------------------ |
+| Registry | 包括`RegistryFactory`, `Registry` ,`RegistryService`等扩展点 |
+| Protocol | RPC协议扩展 |
+| Serialization | 序列化协议扩展 |
+| Cluster | 集群容错策略扩展，如Failover, Failfast等 |
+| Loadbalance | 负载均衡策略扩展 |
+| Transporter | 传输框架扩展，如Netty等 |
+| Monitor | 监控中心扩展，包括MonitorFactory, Monitor, MonitorService等 |
+| Router | 路由规则扩展 |
+| Filter | 拦截器扩展 |
+
+### 步骤四：上线验证
+
+参考本文前面一节的 [2.7.x 版本升级到 Dubbo3](./#步骤四上线验证) 中讲到的验证方法。
diff --git a/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/migration.md.bak b/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/migration.md.bak
new file mode 100644
index 0000000..36d7138
--- /dev/null
+++ b/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/migration.md.bak
@@ -0,0 +1,97 @@
+---
+aliases:
+ - /zh/docs3-v2/java-sdk/reference-manual/protocol/triple/migration/
+ - /zh-cn/docs3-v2/java-sdk/reference-manual/protocol/triple/migration/
+description: Dubbo2 协议迁移
+linkTitle: Dubbo2 协议迁移
+title: Dubbo2 协议迁移
+type: docs
+weight: 10
+---
+
+## 迁移流程说明
+
+Dubbo2 的用户使用 dubbo 协议 + 自定义序列化，如 hessian2 完成远程调用。
+
+而 Grpc 的默认仅支持 Protobuf 序列化，对于 Java 语言中的多参数以及方法重载也无法支持。
+
+Dubbo3 的之初就有一条目标是完美兼容 Dubbo2，所以为了 Dubbo2 能够平滑升级， Dubbo 框架侧做了很多工作来保证升级的无感，目前默认的序列化和 Dubbo2 保持一致为 `hessian2`。
+
+所以，如果决定要升级到 Dubbo3 的 `Triple` 协议，只需要修改配置中的协议名称为 `tri` (注意: 不是 triple )即可。
+
+接下来我们以一个使用 Dubbo2 协议的[工程](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration)来举例，如何一步一步安全的升级。
+
+1. 仅使用 `dubbo` 协议启动 `provider` 和 `consumer`，并完成调用。
+2. 仅使用 `tri` 协议启动 `provider` 和 `consumer`，并完成调用。
+3. 使用 `dubbo` 协议和 `tri` 协议 启动 `provider`，以 `dubbo` 协议启动 `consumer`，并完成调用。
+
+### 定义服务
+
+1. 定义接口
+```java
+public interface IWrapperGreeter {
+
+ //...
+
+ /**
+ * 这是一个普通接口，没有使用 pb 序列化
+ */
+ String sayHello(String request);
+
+}
+```
+
+2. 实现类示例
+```java
+public class IGreeter2Impl implements IWrapperGreeter {
+
+ @Override
+ public String sayHello(String request) {
+ return "hello," + request;
+ }
+}
+```
+
+### 仅使用 dubbo 协议
+
+为保证兼容性，我们先将部分 provider 升级到 `dubbo3` 版本并使用 `dubbo` 协议。
+
+使用 `dubbo` 协议启动一个 [`Provider`](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationDubboProvider.java) 和 [`Consumer`](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationDubboConsumer.java) 完成调用。
+
+{{% alert title="输出结果" color="info" %}}
+
+{{% /alert %}}
+
+### 仅使用 triple 协议
+
+当所有的 consumer 都升级至支持 `Triple` 协议的版本后，provider 可切换至仅使用 `Triple` 协议启动
+
+结构如图所示:
+
+
+[Provider](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationTriProvider.java)
+和 [Consumer](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationTriConsumer.java) 完成调用。
+
+
+{{% alert title="输出结果" color="info" %}}
+
+{{% /alert %}}
+
+### 同时使用 dubbo 和 triple 协议
+
+对于线上服务的升级，不可能一蹴而就同时完成 provider 和 consumer 升级, 需要按步操作，
+
+**第一步：保证业务稳定。**
+
+**第二步：provider 提供双协议的方式同时支持 dubbo + tri 两种协议的客户端。**
+
+结构如图所示:
+
+
+> 按照推荐升级步骤，provider 已经支持了 tri 协议，所以 dubbo3 的 consumer 可以直接使用 tri 协议
+
+使用 `dubbo` 协议和 `triple` 协议启动[`Provider`](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationBothProvider.java)和[`Consumer`](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationBothConsumer.java) 完成调用。
+
+{{% alert title="输出结果" color="info" %}}
+
+{{% /alert %}}
diff --git a/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/protobuf&interface.md b/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/protobuf&interface.md
deleted file mode 100644
index 0cca5a7..0000000
--- a/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/protobuf&interface.md
+++ /dev/null
@@ -1,152 +0,0 @@
----
-aliases:
- - /zh/docs3-v2/java-sdk/upgrades-and-compatibility/protobuf&interface/
- - /zh-cn/docs3-v2/java-sdk/upgrades-and-compatibility/protobuf&interface/
-description: Protobuf 与 Interface 差异对比指南
-linkTitle: Protobuf vs Interface
-title: Protobuf 与 Interface
-type: docs
-weight: 6
----
-
-
-
-
-
-本文对比了Protobuf和Interface这2种IDL的差异，帮助Dubbo协议开发者了解Protobuf，为后续转到Triple协议和Grpc协议做铺垫。
-
-## 1. 数据类型
-
-### 1.1. 基本类型
-
-| ptoto类型 | java类型 |
-| ---- | ---- |
-double | double
-float | float
-int32 | int
-int64 | long
-uint32 | int[注]
-uint64 | long[注]
-sint32 | int
-sint64 | long
-fixed32 | int[注]
-fixed64 | long[注]
-sfixed32 | int
-sfixed64 | long
-bool | boolean
-string | String
-bytes | ByteString
-
-{{% alert title="注意" color="primary" %}}
-在Java中，无符号的32位和64位整数使用它们的有符号对数来表示，顶部位只存储在符号位中。
-{{% /alert %}}
-
-## 2. 复合类型
-
-### 2.1. 枚举
-
-* 原始pb代码
-
-```java.
-enum TrafficLightColor {
- TRAFFIC_LIGHT_COLOR_INVALID = 0;
- TRAFFIC_LIGHT_COLOR_UNSET = 1;
- TRAFFIC_LIGHT_COLOR_GREEN = 2;
- TRAFFIC_LIGHT_COLOR_YELLOW = 3;
- TRAFFIC_LIGHT_COLOR_RED = 4;
-}
-```
-
-* 生成的java代码
-
-
-
-> 枚举是常量，因此采用大写
-### 2.2. 数组
-
-* 原始pb代码
-
-```java
-message VipIDToRidReq {
- repeated uint32 vipID = 1;
-}
-```
-
-* 生成的java代码
-
-
-
-> 底层实际上是1个ArrayList
-### 2.3. 集合
-
-PB不支持无序、不重复的集合，只能 ``借用数组实现``，需要 ``自行去重``。
-
-### 2.4. 字典
-
-* 原始pb代码
-
-```java
-message BatchOnlineRes {
- map<uint32, uint32> onlineMap = 1;//在线状态
-}
-```
-
-* 生成的java代码
-
-
-
-### 2.5. 嵌套
-
-* 原始pb代码
-
-```java
-message BatchAnchorInfoRes {
- map<uint32, AnchorInfo> list = 1; //用户信息map列表
-}
-/*
-* 对应接口的功能: 批量或单个获取用户信息
-*/
-message AnchorInfo {
- uint32 ownerUid = 1 [json_name="uid"]; //用户id
- string nickName = 2 [json_name="nn"]; //用户昵称
- string smallAvatar = 3 [json_name="savt"]; //用户头像全路径-小
- string middleAvatar = 4 [json_name="mavt"]; //用户头像全路径-中
- string bigAvatar = 5 [json_name="bavt"]; //用户头像全路径-大
- string avatar = 6 [json_name="avt"]; //用户头像
-}
-```
-
-* 生成的java代码
-
-
-
-## 3. 字段默认值
-
-* 对于字符串，默认值为空字符串。
-* 对于字节，默认值为空字节。
-* 对于bools，默认值为false。
-* 对于数字类型，默认值为零。
-* 对于枚举，默认值为第一个定义的枚举值，它必须为0。
-* 对于消息字段，未设置字段。 它的确切值是语言相关的。 有关详细信息，请参阅生成的代码指南。
-
-## 4. 整体结构
-
-| Feature | Java Interface | Protobuf | 备注 |
-| ---- | ---- | ---- | ---- |
-| 方法重载 | √ | × | |
-| 泛型/模板化 | √ | × | |
-| 方法继承 | √ | × | |
-| 嵌套定义 | √ | 部分支持 | PB仅支持message和enum嵌套 |
-| import文件 | √ | √ | |
-| 字段为null | √ | × | |
-| 多个入参 | √ | × | PB仅支持单入参 |
-| 0个入参 | √ | × | PB必须有入参 |
-| 0个出参 | √ | × | PB必须有出参 |
-| 入参/出参为抽象类 | √ | × | PB的入参/出参必须为具象类 |
-| 入参/出参为接口 | √ | × | PB的入参/出参必须为具象类 |
-| 入参/出参为基础类型 | √ | × | PB的入参/出参必须为结构体 |
-
-## 5. 社区资料
-* 社区主页地址：https://developers.google.cn/protocol-buffers/
-* 社区开源地址：https://github.com/google/protobuf
-* 相关jar的maven：https://search.maven.org/search?q=com.google.protobuf
diff --git a/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/serialization-upgrade.md b/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/serialization-upgrade.md
deleted file mode 100644
index e96e90b..0000000
--- a/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/serialization-upgrade.md
+++ /dev/null
@@ -1,38 +0,0 @@
----
-aliases:
- - /zh/docs3-v2/java-sdk/upgrades-and-compatibility/serialization-upgrade/
- - /zh-cn/docs3-v2/java-sdk/upgrades-and-compatibility/serialization-upgrade/
-description: 无损升级序列化协议指南
-linkTitle: 序列化协议升级
-title: 序列化协议升级
-type: docs
-weight: 5
----
-
-
-
-
-
-在 `3.1.0` 版本中，Dubbo 默认支持的序列化协议新增对 Fastjson2 的支持。部分用户可能会考虑在现有的系统中对序列化协议进行升级，但服务端和客户端版本的差异可能导致客户端并不支持服务端的序列化协议。
-
-在 `3.2.0` 版本中, Dubbo 的服务端引入新的配置 `prefer-serialization`，该特性可以完美解决服务端序列化升级过程中可能带来的风险。
-
-
-### 最佳实践
-
-序列化协议升级，需要分两步走：
-
-* **首先需要推动服务端的序列化协议升级，同时在服务端的暴露配置中需要添加 `prefer-serialization` 配置。**
-> 比如：升级前的序列化协议是 hessian2，升级之后的序列化协议是 Fastjson2 那么在服务端的暴露配置中就应该添加如下所示的配置。
-
-```yaml
-dubbo.provider.prefer-serialization=fastjson2,hessian2
-dubbo.provider.serialization=hessian2
-```
-* **其次，客户端需要升级至和服务端相同版本**
-
-### 实现原理
-
-dubbo 客户端序列化协议是根据服务端的注册配置来选择的（即服务端的`serialization`配置）。在请求阶段 dubbo 会把客户端的序列化协议组装到请求头上，服务端在进行反序列化时会根据请求头来确定反序列化协议。所以，如果服务端和客户端的版本不一致就可能会出现客户端序列化不了的情况。
-
-为了解决这个情况，`3.2.0` 在客户端序列化的时候会优先使用 `prefer-serialization` 配置的协议，如果不支持 `prefer-serialization` 相关的协议，才会使用 `serialization` 配置的协议。（可以把 `serialization` 理解为一个兜底的配置）
diff --git a/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/service-discovery/_index.md b/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/service-discovery/_index.md
deleted file mode 100755
index 0e8fa2b..0000000
--- a/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/service-discovery/_index.md
+++ /dev/null
@@ -1,10 +0,0 @@
----
-aliases:
- - /zh/docs3-v2/java-sdk/upgrades-and-compatibility/service-discovery/
- - /zh-cn/docs3-v2/java-sdk/upgrades-and-compatibility/service-discovery/
-description: Dubbo 3 应用级服务发现指南
-linkTitle: 应用级服务发现
-title: 应用级服务发现
-type: docs
-weight: 4
----
diff --git a/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/service-discovery/migration-service-discovery.md b/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/service-discovery/migration-service-discovery.md
deleted file mode 100644
index a441501..0000000
--- a/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/service-discovery/migration-service-discovery.md
+++ /dev/null
@@ -1,168 +0,0 @@
----
-aliases:
- - /zh/docs3-v2/java-sdk/upgrades-and-compatibility/service-discovery/migration-service-discovery/
- - /zh-cn/docs3-v2/java-sdk/upgrades-and-compatibility/service-discovery/migration-service-discovery/
-description: 本文档专门针对使用 2.x 版本的老用户，详细阐述了升级到 3.x 后的默认地址注册与发现行为、如何平滑的迁移到新版本的地址模型。
-linkTitle: 接口级服务发现迁移至应用级服务发现指南
-title: 接口级服务发现迁移至应用级服务发现指南
-type: docs
-weight: 10
----
-
-
-
-
-
-
-总体上来说，在地址注册与发现环节，`3.x` 是完全兼容 `2.x` 版本的，这意味着，用户可以选择将集群内任意数量的应用或机器升级到 `3.x`，同时在这个过程中保持与 `2.x` 版本的互操作性。
-
-> 如关心迁移背后工作原理，请参考 [迁移规则详情与工作原理](../service-discovery-rule)
-
-## 1 快速升级步骤
-
-简单的修改 pom.xml 到最新版本就可以完成升级，如果要迁移到应用级地址，只需要调整开关控制 3.x 版本的默认行为。
-
-1. 升级 Provider 应用到最新 3.x 版本依赖，配置双注册开关`dubbo.application.register-mode=all`（建议通过全局配置中心设置，默认已自动开启），完成应用发布。
-2. 升级 Consumer 应用到最新 3.x 版本依赖，配置双订阅开关`dubbo.application.service-discovery.migration=APPLICATION_FIRST`（建议通过全局配置中心设置，默认已自动开启），完成应用发布。
-3. 在确认 Provider 的上有 Consumer 全部完成应用级地址迁移后，Provider 切到应用级地址单注册。完成升级
-
-
-
-以下是关于迁移流程的详细描述。
-
-## 2 Provider 端升级过程详解
-
-在不改变任何 Dubbo 配置的情况下，可以将一个应用或实例升级到 3.x 版本，升级后的 Dubbo 实例会默保保证与 2.x 版本的兼容性，即会正常注册 2.x 格式的地址到注册中心，因此升级后的实例仍会对整个集群仍保持可见状态。
-
-
-
-同时新的地址发现模型（注册应用级别的地址）也将会自动注册。
-
-
-
-通过 -D 参数，可以指定 provider 启动时的注册行为
-
-```text
--Ddubbo.application.register-mode=all
-# 可选值 interface、instance、all，默认是 all，即接口级地址、应用级地址都注册
-```
-
-
-
-另外，可以在配置中心修改全局默认行为，来控制所有 3.x 实例注册行为。其中，全局性开关的优先级低于 -D 参数。
-
-
-
-为了保证平滑迁移，即升级到 3.x 的实例能同时被 2.x 与 3.x 的消费者实例发现，3.x 实例需要开启双注册；当所有上游的消费端都迁移到 3.x 的地址模型后，提供端就可以切换到 instance 模式（只注册应用级地址）。对于如何升级消费端到 3.x 请参见下一小节。
-
-### 2.1 双注册带来的资源消耗
-
-双注册不可避免的会带来额外的注册中心存储压力，但考虑到应用级地址发现模型的数据量在存储方面的极大优势，即使对于一些超大规模集群的用户而言，新增的数据量也并不会带来存储问题。总体来说，对于一个普通集群而言，数据增长可控制在之前数据总量的 1/100 ~ 1/1000
-
-以一个中等规模的集群实例来说： 2000 实例、50个应用（500 个 Dubbo 接口，平均每个应用 10 个接口）。
-
- 假设每个接口级 URL 地址平均大小为 5kb，每个应用级 URL 平均大小为 0.5kb
-
- 老的接口级地址量：2000 * 500 * 5kb ≈ 4.8G
-
- 新的应用级地址量：2000 * 50 * 0.5kb ≈ 48M
-
- 双注册后仅仅增加了 48M 的数据量。
-
-
-
-## 3 Consumer 端升级过程
-
-对于 2.x 的消费者实例，它们看到的自然都是 2.x 版本的提供者地址列表；
-
-对于 3.x 的消费者，它具备同时发现 2.x 与 3.x 提供者地址列表的能力。在默认情况下，如果集群中存在可以消费的 3.x 的地址，将自动消费 3.x 的地址，如果不存在新地址则自动消费 2.x 的地址。Dubbo3 提供了开关来控制这个行为：
-
-```text
-dubbo.application.service-discovery.migration=APPLICATION_FIRST
-# 可选值
-# FORCE_INTERFACE，只消费接口级地址，如无地址则报错，单订阅 2.x 地址
-# APPLICATION_FIRST，智能决策接口级/应用级地址，双订阅
-# FORCE_APPLICATION，只消费应用级地址，如无地址则报错，单订阅 3.x 地址
-```
-
-`dubbo.application.service-discovery.migration ` 支持通过 `-D` 以及 `全局配置中心` 两种方式进行配置。
-
-
-
-
-
-
-接下来，我们就具体看一下，如何通过双订阅模式（APPLICATION_FIRST）让升级到 3.x 的消费端迁移到应用级别的地址。在具体展开之前，先明确一条消费端的选址行为：**对于双订阅的场景，消费端虽然可同时持有 2.x 地址与 3.x 地址，但选址过程中两份地址是完全隔离的：要么用 2.x 地址，要么用 3.x 地址，不存在两份地址混合调用的情况，这个决策过程是在收到第一次地址通知后就完成了的。**
-
-
-
-下面，我们看一个`APPLICATION_FIRST`策略的具体操作过程。
-
-首先，提前在全局配置中心 Nacos 配置一条配置项（所有消费端都将默认执行这个选址策略）：
-
-
-
-
-
-紧接着，升级消费端到 3.x 版本并启动，这时消费端读取到`APPLICATION_FIRST`配置后，执行双订阅逻辑（订阅 2.x 接口级地址与 3.x 应用级地址）
-
-
-
-至此，升级操作就完成了，剩下的就是框架内部的执行了。在调用发生前，框架在消费端会有一个“选址过程”，注意这里的选址和之前 2.x 版本是有区别的，选址过程包含了两层筛选：
-
-* 先进行地址列表（ClusterInvoker）筛选（接口级地址 or 应用级地址）
-* 再进行实际的 provider 地址（Invoker）筛选。
-
-
-
-ClusterInvoker 筛选的依据，可以通过 MigrationAddressComparator SPI 自行定义，目前官方提供了一个简单的地址数量比对策略，即当 `应用级地址数量 == 接口级地址数量` 满足时则进行迁移。
-
-> 其实 FORCE_INTERFACE、APPLICATION_FIRST、FORCE_APPLICATION 控制的都是这里的 ClusterInvoker 类型的筛选策略
-
-
-
-### 3.1 双订阅带来的资源消耗
-
-双订阅不可避免的会增加消费端的内存消耗，但由于应用级地址发现在地址总量方面的优势，这个过程通常是可接受的，我们从两个方面进行分析：
-
-1. 双订阅带来的地址推送数据量增长。这点我们在 ”双注册资源消耗“ 一节中做过介绍，应用级服务发现带来的注册中心数据量增长非常有限。
-2. 双订阅带来的消费端内存增长。要注意双订阅只存在于启动瞬态，在ClusterInvoker选址决策之后其中一份地址就会被完全销毁；对单个服务来说，启动阶段双订阅带来的内存增长大概能控制在原内存量的 30% ~ 40%，随后就会下降到单订阅水平，如果切到应用级地址，能实现内存 50% 的下降。
-
-
-
-### 3.2 消费端更细粒度的控制
-
-除了全局的迁移策略之外，Dubbo 在消费端提供了更细粒度的迁移策略支持。控制单位可以是某一个消费者应用，它消费的服务A、服务B可以有各自独立的迁移策略，具体是用方式是在消费端配置迁移规则：
-
-
-```yaml
-key: demo-consumer
-step: APPLICATION_FIRST
-applications:
- - name: demo-provider
- step: FORCE_APPLICATION
-services:
- - serviceKey: org.apache.dubbo.config.api.DemoService:1.0.0
- step: FORCE_INTERFACE
-```
-
-使用这种方式能做到比较精细迁移控制，但是当下及后续的改造成本会比较高，除了一些特别场景，我们不太推荐启用这种配置方式。
-[迁移指南](../service-discovery-rule/)官方推荐使用的全局的开关式的迁移策略，让消费端实例在启动阶段自行决策使用哪份可用的地址列表。
-
-
-
-## 4 迁移状态的收敛
-
-为了同时兼容 2.x 版本，升级到 3.x 版本的应用在一段时间内要么处在双注册状态，要么处在双订阅状态。
-
-解决这个问题，我们还是从 Provider 视角来看，当所有的 Provider 都切换到应用级地址注册之后，也就不存在双订阅的问题了。
-
-### 4.1 不同的升级策略影响很大
-
-毫无疑问越早越彻底的升级，就能尽快摆脱这个局面。设想，如果可以将组织内所有的应用都升级到 3.x 版本，则版本收敛就变的非常简单：升级过程中 Provider 始终保持双注册，当所有的应用都升级到 3.x 之后，就可以调整全局默认行为，让 Provider 都变成应用级地址单注册了，这个过程并不会给 Consumer 应用带来困扰，因为它们已经是可以识别应用级地址的 3.x 版本了。
-
-如果没有办法做到应用的全量升级，甚至在相当长的时间内只能升级一部分应用，则不可避免的迁移状态要持续比较长的时间。
-在这种情况下，我们追求的只能是尽量保持已升级应用的上下游实现版本及功能收敛。推动某些 Provider 的上游消费者都升级到 Dubbo3，这样就可以解除这部分 Provider 的双注册，要做到这一点，可能需要一些辅助统计工具的支持。
-
-1. 要能分析出应用间的依赖关系，比如一个 Provdier 应用被哪些消费端应用消费，这可以通过 Dubbo 提供的服务元数据上报能力来实现。
-2. 要能知道每个应用当前使用的 dubbo 版本，可以通过扫描或者主动上报手段。
diff --git a/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/service-discovery/service-discovery-rule.md b/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/service-discovery/service-discovery-rule.md
deleted file mode 100644
index cb9c91c..0000000
--- a/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/service-discovery/service-discovery-rule.md
+++ /dev/null
Binary files differ
diff --git a/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/service-discovery/service-discovery-samples.md b/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/service-discovery/service-discovery-samples.md
deleted file mode 100644
index 4fab199..0000000
--- a/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/service-discovery/service-discovery-samples.md
+++ /dev/null
@@ -1,84 +0,0 @@
----
-aliases:
- - /zh/docs3-v2/java-sdk/upgrades-and-compatibility/service-discovery/service-discovery-samples/
- - /zh-cn/docs3-v2/java-sdk/upgrades-and-compatibility/service-discovery/service-discovery-samples/
-description: 本文具体说明了用户在升级到 Dubbo 3.0 之后如何快速开启应用级服务发现新特性。
-linkTitle: 应用级服务发现迁移示例
-title: 应用级服务发现迁移示例
-type: docs
-weight: 5
----
-
-
-
-
-
-
-应用级服务发现为应用间服务发现的协议，因此使用应用级服务发现需要消费端和服务端均升级到 Dubbo 3.0 版本并开启新特性（默认开启）才能在链路中使用应用级服务发现，真正发挥应用级服务发现的优点。
-## 开启方式
-### 服务端
-应用升级到 Dubbo 3.0 后，服务端自动开启接口级 + 应用级双注册功能，默认无需开发者修改任何配置
-
-### 消费端
-应用升级到 Dubbo 3.0 后，消费端自动始接口级 + 应用级双订阅功能，默认无需开发者修改任何配置。建议在服务端都升级到 Dubbo 3.0 并开启应用级注册以后通过规则配置消费端关闭接口级订阅，释放对应的内存空间。
-
-## 详细说明
-### 服务端配置
-
-1. 全局开关
-
-应用配置（可以通过配置文件或者 -D 指定）`dubbo.application.register-mode` 为 instance（只注册应用级）、all（接口级+应用级均注册）开启全局的注册开关，配置此开关后，默认会向所有的注册中心中注册应用级的地址，供消费端服务发现使用。
-> [参考示例](https://github.com/apache/dubbo-samples/blob/master/2-advanced/dubbo-samples-service-discovery/dubbo-servicediscovery-migration/dubbo-servicediscovery-migration-provider2/src/main/resources/dubbo.properties)
-
-```
-# 双注册
-dubbo.application.register-mode=all
-```
-```
-# 仅应用级注册
-dubbo.application.register-mode=instance
-```
-
-2. 注册中心地址参数配置
-
-注册中心的地址上可以配置 `registry-type=service` 来显示指定该注册中心为应用级服务发现的注册中心，带上此配置的注册中心将只进行应用级服务发现。
-> [参考示例](https://github.com/apache/dubbo-samples/blob/master/2-advanced/dubbo-samples-service-discovery/dubbo-demo-servicediscovery-xml/servicediscovery-provider/src/main/resources/spring/dubbo-provider.xml)
-
-```xml
-<dubbo:registry address="nacos://${nacos.address:127.0.0.1}:8848?registry-type=service"/>
-```
-### 消费端订阅模式
-FORCE_INTERFACE：仅接口级订阅，行为和 Dubbo 2.7 及以前版本一致。
-APPLICATION_FIRST：接口级 + 应用级多订阅，如果应用级能订阅到地址就使用应用级的订阅，如果订阅不到地址则使用接口级的订阅，以此保证迁移过程中最大的兼容性。（注：由于存在同时进行订阅的行为，此模式下内存占用会有一定的增长，因此在所有服务端都升级到 Dubbo 3.0 以后建议迁移到 FORCE_APPLICATION 模式降低内存占用）
-FORCE_APPLICATION：仅应用级订阅，将只采用全新的服务发现模型。
-### 消费端配置
-
-1. 默认配置（不需要配置）
-
-升级到 Dubbo 3.0 后默认行为为接口级+应用级多订阅，如果应用级能订阅到地址就使用应用级的订阅，如果订阅不到地址则使用接口级的订阅，以此保证最大的兼容性。
-
-2. 订阅参数配置
-
-应用配置（可以通过配置文件或者 -D 指定）`dubbo.application.service-discovery.migration` 为 `APPLICATION_FIRST` 可以开启多订阅模式，配置为 `FORCE_APPLICATION` 可以强制为仅应用级订阅模式。
-具体接口订阅可以在 `ReferenceConfig` 中的 `parameters` 中配置 Key 为 `migration.step`，Value 为 `APPLICATION_FIRST` 或 `FORCE_APPLICATION` 的键值对来对单一订阅进行配置。
-> [参考示例](https://github.com/apache/dubbo-samples/blob/master/2-advanced/dubbo-samples-service-discovery/dubbo-servicediscovery-migration/dubbo-servicediscovery-migration-consumer/src/test/java/org/apache/dubbo/demo/consumer/DemoServiceConfigIT.java)
-
-```java
-System.setProperty("dubbo.application.service-discovery.migration", "APPLICATION_FIRST");
-```
-```java
-ReferenceConfig<DemoService> referenceConfig = new ReferenceConfig<>(applicationModel.newModule());
-referenceConfig.setInterface(DemoService.class);
-referenceConfig.setParameters(new HashMap<>());
-referenceConfig.getParameters().put("migration.step", mode);
-return referenceConfig.get();
-```
-
-3. 动态配置（优先级最高，可以在运行时修改配置）
-
-此配置需要基于配置中心进行推送，Key 为应用名 + `.migration` （如 `demo-application.migraion`），Group 为 `DUBBO_SERVICEDISCOVERY_MIGRATION`。规则体配置详见[接口级服务发现迁移至应用级服务发现指南](../migration-service-discovery/)。
-> [参考示例](https://github.com/apache/dubbo-samples/blob/master/2-advanced/dubbo-samples-service-discovery/dubbo-servicediscovery-migration/dubbo-servicediscovery-migration-consumer/src/main/java/org/apache/dubbo/demo/consumer/UpgradeUtil.java)
-
-```java
-step: FORCE_INTERFACE
-```
diff --git a/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/2.x-to-3.x-compatibility-guide.md b/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/version/2.x-to-3.x-compatibility-guide.md
similarity index 99%
rename from content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/2.x-to-3.x-compatibility-guide.md
rename to content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/version/2.x-to-3.x-compatibility-guide.md
index 81f3bb5..7e57ec0 100644
--- a/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/2.x-to-3.x-compatibility-guide.md
+++ b/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/version/2.x-to-3.x-compatibility-guide.md
@@ -9,10 +9,6 @@
weight: 1
---
-
-
-
-
## 升级到 Dubbo 3.X 的收益
Dubbo3 依旧保持了 2.x 的经典架构，以解决微服务进程间通信为主要职责，通过丰富的服务治理（如地址发现、流量管理等）能力来更好的管控微服务集群；Dubbo3 对原有框架的升级是全面的，体现在核心 Dubbo 特性的几乎每个环节，通过升级实现了稳定性、性能、伸缩性、易用性的全面提升。
diff --git a/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/3.0-to-3.1-compatibility-guide.md b/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/version/3.0-to-3.1-compatibility-guide.md
similarity index 100%
rename from content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/3.0-to-3.1-compatibility-guide.md
rename to content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/version/3.0-to-3.1-compatibility-guide.md
diff --git a/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/3.1-to-3.2-compatibility-guide.md b/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/version/3.1-to-3.2-compatibility-guide.md
similarity index 100%
rename from content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/3.1-to-3.2-compatibility-guide.md
rename to content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/version/3.1-to-3.2-compatibility-guide.md
diff --git a/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/3.2-to-3.3-compatibility-guide.md b/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/version/3.2-to-3.3-compatibility-guide.md
similarity index 100%
rename from content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/3.2-to-3.3-compatibility-guide.md
rename to content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/version/3.2-to-3.3-compatibility-guide.md
diff --git a/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/version/_index.md b/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/version/_index.md
index d0d56ce..7ce0943 100755
--- a/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/version/_index.md
+++ b/content/zh-cn/overview/mannual/java-sdk/reference-manual/upgrades-and-compatibility/version/_index.md
@@ -3,40 +3,9 @@
- /zh/docs3-v2/java-sdk/version/
- /zh-cn/docs3-v2/java-sdk/version/
- /zh-cn/overview/mannual/java-sdk/version/
-description: 查看历史版本文档
-linkTitle: 查看历史版本文档
-title: 查看历史版本文档
+description: "Dubbo 各个版本变更记录（release note），跨版本升级兼容性说明。"
+linkTitle: 版本变更记录
+title: 版本变更记录
type: docs
weight: 100
---
-
-{{< blocks/section color="white" height="auto">}}
-<div class="td-content list-page">
- <div class="lead"></div><header class="article-meta">
- </header><div class="row">
- <div class="col-sm col-md-6 mb-4 mb-md-0">
- <div class="h-100 card shadow" href="#">
- <div class="card-body">
- <h4 class="card-title">
- <a target="_blank" href='{{< relref "../../../../../../docs/" >}}'>Early 3.0 Version</a>
- </h4>
- <p>早期 3.0 版本文档</p>
- </div>
- </div>
- </div>
- <div class="col-sm col-md-6 mb-4 mb-md-0">
- <div class="h-100 card shadow">
- <div class="card-body">
- <h4 class="card-title">
- <a target="_blank" href='{{< relref "../../../../../../docsv2.7/" >}}'>2.7.x Version</a>
- </h4>
- <p>2.7.x 版本文档</p>
- </div>
- </div>
- </div>
-
-</div>
-<hr>
-</div>
-
-{{< /blocks/section >}}
\ No newline at end of file
diff --git a/content/zh-cn/overview/mannual/java-sdk/tasks/deploy/deploy-on-kubernetes-service.md b/content/zh-cn/overview/mannual/java-sdk/tasks/deploy/deploy-on-kubernetes-service.md
index 15cba28..3435257 100644
--- a/content/zh-cn/overview/mannual/java-sdk/tasks/deploy/deploy-on-kubernetes-service.md
+++ b/content/zh-cn/overview/mannual/java-sdk/tasks/deploy/deploy-on-kubernetes-service.md
@@ -2,8 +2,8 @@
aliases:
- /zh/overview/tasks/deploy/deploy-on-vm/
- /zh-cn/overview/tasks/deploy/deploy-on-vm/
-description: ""
-linkTitle: Kubernetes Service
+description: "部署 Dubbo 应用到服务网格（Service Mesh），基于 Kubernetes Service 与控制面。"
+linkTitle: 服务网格
title: 部署 Dubbo 应用到虚拟机环境
type: docs
weight: 3
diff --git a/content/zh-cn/overview/mannual/java-sdk/tasks/deploy/deploy-on-kubernetes.md b/content/zh-cn/overview/mannual/java-sdk/tasks/deploy/deploy-on-kubernetes.md
index 28f7fca..56fe514 100644
--- a/content/zh-cn/overview/mannual/java-sdk/tasks/deploy/deploy-on-kubernetes.md
+++ b/content/zh-cn/overview/mannual/java-sdk/tasks/deploy/deploy-on-kubernetes.md
@@ -2,9 +2,9 @@
aliases:
- /zh/overview/tasks/deploy/deploy-on-vm/
- /zh-cn/overview/tasks/deploy/deploy-on-vm/
-description: ""
+description: "部署 Dubbo 应用到 Kubernetes 环境，使用 Nacos 或者 Zookeeper 等作为注册中心。"
linkTitle: Kubernetes
-title: 部署 Dubbo 应用到虚拟机环境
+title: 部署 Dubbo 应用到 Kubernetes 环境
type: docs
weight: 2
---
diff --git a/content/zh-cn/overview/mannual/java-sdk/tasks/deploy/deploy-on-vm.md b/content/zh-cn/overview/mannual/java-sdk/tasks/deploy/deploy-on-vm.md
index 60d53c2..695f099 100644
--- a/content/zh-cn/overview/mannual/java-sdk/tasks/deploy/deploy-on-vm.md
+++ b/content/zh-cn/overview/mannual/java-sdk/tasks/deploy/deploy-on-vm.md
@@ -2,7 +2,7 @@
aliases:
- /zh/overview/tasks/deploy/deploy-on-vm/
- /zh-cn/overview/tasks/deploy/deploy-on-vm/
-description: ""
+description: "传统基于 Zookeeper、Nacos 的注册中心部署架构，部署 Dubbo 应用到虚拟机环境"
linkTitle: 传统注册中心
title: 传统基于 Zookeeper、Nacos 的注册中心部署架构，部署 Dubbo 应用到虚拟机环境
type: docs
diff --git a/content/zh-cn/overview/mannual/java-sdk/tasks/gateway/dubbo.md b/content/zh-cn/overview/mannual/java-sdk/tasks/gateway/dubbo.md
index 38b8e3d..f3b3ed5 100644
--- a/content/zh-cn/overview/mannual/java-sdk/tasks/gateway/dubbo.md
+++ b/content/zh-cn/overview/mannual/java-sdk/tasks/gateway/dubbo.md
@@ -11,8 +11,8 @@
---
由于 dubbo 协议是基于 TCP 的二进制私有协议，因此更适合作为后端微服务间的高效 RPC 通信协议，这也导致 dubbo 协议对于前端流量接入不是很友好。在 Dubbo 框架中，有两种方式可以帮助开发者解决这个问题：
-* **多协议发布**，为 dubbo 协议服务暴露 rest 风格的 http 协议访问方式，这种模式架构上会变得非常简单，通用的网关产品即可支持。
-* **通过网关实现协议转换**，这种方式需要将 http 协议转换为后端服务能识别的 dubbo 协议，要求网关必须支持 dubbo 协议。
+* **多协议发布【推荐】**，为 dubbo 协议服务暴露 rest 风格的 http 协议访问方式，这种模式架构上会变得非常简单，通用的网关产品即可支持。
+* **通过网关实现 `http->dubbo` 协议转换**，这种方式需要将 http 协议转换为后端服务能识别的 dubbo 协议，要求网关必须支持 dubbo 协议。
## 同时发布 http、dubbo 协议
**如果我们能让一个服务同时发布 dubbo、http 协议，这样后端调用是基于高效的 dubbo 二进制协议，同时浏览器、web服务等前端设施也可以用 http 协议访问到相同的服务。** 好消息是，Dubbo 框架支持为同一个服务发布多个协议，并且支持客户端通过同一个端口以不同的协议访问服务，如下所示：
@@ -60,8 +60,11 @@
为 dubbo 协议服务增加了 http 访问方式之后，就可以很容易的将 dubbo 服务接入网关了，具体可以参见下一小节中的 [triple 协议网关接入](zh-cn/overview/mannual/java-sdk/tasks/gateway/triple/) 示例，那里有详细的说明。
## http 转 dubbo 协议
+{{% alert title="注意" color="warning" %}}
+如果您使用的是 Dubbo3 3.3.x 版本，在决定考虑此方案之前，我们强烈推荐您仔细评估本文前一节的 `多协议发布方案`。除非您因为某些特殊原因真的无法接受多协议发布带来的应用改造成本（实际上只是改一行配置而已），否则这个方案应该作为第二选择。
+{{% /alert %}}
-如果你不打算如上所述的方式改造应用进行多协议发布（实际上只是改一行配置），那么您如果要从网关接入后端 dubbo 服务，则前端的 HTTP 流量要经过一层 `http -> dubbo` 的协议转换才能实现正常调用
+如果要从网关接入后端 dubbo 服务，则前端的 HTTP 流量要经过一层 `http -> dubbo` 的协议转换才能实现正常调用
<img style="max-width:800px;height:auto;" src="/imgs/v3/tasks/gateway/http-to-dubbo.png"/>
@@ -74,3 +77,5 @@
* [使用 Higress 代理 Dubbo 流量]({{< relref "../../../../../../blog/integration/how-to-proxy-dubbo-in-higress" >}})
* [使用 Apache APISIX 代理 Dubbo 流量]({{< relref "../../../../../../blog/integration/how-to-proxy-dubbo-in-apache-apisix" >}})
* [使用 Apache Shenyu 代理 Dubbo 流量]({{< relref "../../../../../../blog/integration/how-to-proxy-dubbo-in-apache-shenyu" >}})
+
+如果您并没有使用现成的网关产品，而是使用自建的流量转换组件，您很有可能使用到了 Dubbo 框架中的 [**泛化调用**](/zh-cn/overview/mannual/java-sdk/tasks/framework/more/generic/) 机制，具体请参考相关文档了解详情。
diff --git a/content/zh-cn/overview/mannual/java-sdk/tasks/gateway/triple.md b/content/zh-cn/overview/mannual/java-sdk/tasks/gateway/triple.md
index e0a2103..b3eb132a 100644
--- a/content/zh-cn/overview/mannual/java-sdk/tasks/gateway/triple.md
+++ b/content/zh-cn/overview/mannual/java-sdk/tasks/gateway/triple.md
@@ -180,12 +180,12 @@
"Hello HigressTriple"
```
-`/org.apache.dubbo.samples.gateway.api.DemoService/sayHello/` 这种根据 Java 路径名与方法直接暴露的访问路径，虽然可以很容易调通，但对于前端来说并不友好。接下来我们一起看一下如何发布 REST 风格的 HTTP 服务。
-
-{{% alert title="注意" color="warning" %}}
+{{% alert title="注意" color="info" %}}
这里要运行 `kubectl port-forward service/higress-gateway -n higress-system 80:80 443:443` 将集群内的 Higress 暴露出来才可访问。
{{% /alert %}}
+`/org.apache.dubbo.samples.gateway.api.DemoService/sayHello/` 这种根据 Java 路径名与方法直接暴露的访问路径，虽然可以很容易调通，但对于前端来说并不友好。接下来我们一起看一下如何发布 REST 风格的 HTTP 服务。
+
## REST 风格接口
在前面的示例中，如类似 `http://127.0.0.1:9080/triple/demo/hello` 会是更符合前端使用的访问方式，要做到这一点，我们可以通过在 Higress 等网关配置 uri rewrite 重写，实现前端 `/triple/demo/hello` 到后端 `/org.apache.dubbo.samples.gateway.api.DemoService/sayHello/` 的映射。
@@ -252,4 +252,4 @@
## 参考连接
* [使用 Apache APISIX 代理 triple 协议流量](/zh-cn/blog/2024/04/22/使用-apache-apisix-代理-dubbo-服务triple协议/)
-* [Higress 实现 Spring Cloud 服务发现与路由配置(http协议)](https://higress.io/zh-cn/docs/user/spring-cloud)
+* [Higress 实现基于 http 协议微服务发现与路由配置](https://higress.io/zh-cn/docs/user/spring-cloud)
\ No newline at end of file
diff --git a/content/zh-cn/overview/mannual/java-sdk/tasks/rate-limit/adaptive-concurrency-control.md b/content/zh-cn/overview/mannual/java-sdk/tasks/rate-limit/adaptive-concurrency-control.md
index f26ca09..ebb6020 100644
--- a/content/zh-cn/overview/mannual/java-sdk/tasks/rate-limit/adaptive-concurrency-control.md
+++ b/content/zh-cn/overview/mannual/java-sdk/tasks/rate-limit/adaptive-concurrency-control.md
@@ -1,5 +1,5 @@
---
-description: "自适应限流，区别于普通限流策略，其具备自动调整限流策略是否生效、限流阈值的能力。"
+description: "自适应限流，区别于普通限流策略，其具备自动调整限流策略是否生效、限流阈值的能力，heuristic flow control。"
linkTitle: 自适应限流
title: 自适应限流
type: docs
diff --git a/content/zh-cn/overview/mannual/java-sdk/tasks/rate-limit/concurrency-control.md b/content/zh-cn/overview/mannual/java-sdk/tasks/rate-limit/concurrency-control.md
index fd1c5a2..46b9c13 100644
--- a/content/zh-cn/overview/mannual/java-sdk/tasks/rate-limit/concurrency-control.md
+++ b/content/zh-cn/overview/mannual/java-sdk/tasks/rate-limit/concurrency-control.md
@@ -2,7 +2,7 @@
aliases:
- /zh/docs3-v2/java-sdk/advanced-features-and-usage/performance/concurrency-control/
- /zh-cn/docs3-v2/java-sdk/advanced-features-and-usage/performance/concurrency-control/
-description: "Dubbo 框架内置的并发控制策略，通过限制从同一客户端到同一服务的并发请求数，防止恶意请求使服务器过载，确保服务的稳定性，并防止使用过多资源。"
+description: "Dubbo 框架内置的并发控制或者限流策略，通过限制从同一客户端到同一服务的并发请求数，防止恶意请求使服务器过载，确保服务的稳定性，并防止使用过多资源。"
linkTitle: 框架内置限流
title: Dubbo 框架内置的并发控制策略
type: docs
diff --git a/content/zh-cn/overview/mannual/java-sdk/tasks/rate-limit/sentinel.md b/content/zh-cn/overview/mannual/java-sdk/tasks/rate-limit/sentinel.md
index 8615cce..c375214 100644
--- a/content/zh-cn/overview/mannual/java-sdk/tasks/rate-limit/sentinel.md
+++ b/content/zh-cn/overview/mannual/java-sdk/tasks/rate-limit/sentinel.md
@@ -5,7 +5,7 @@
- /zh-cn/overview/what/ecosystem/rate-limit/sentinel/
- /zh/overview/tasks/rate-limit/sentinel/
- /zh-cn/overview/tasks/rate-limit/sentinel/
-description: "使用 Sentinel 保护您的应用，防止应用因个别服务的突发流量过载而出现稳定性问题。"
+description: "使用 Sentinel 保护您的 Dubbo 应用，防止应用因个别服务的突发流量过载而出现稳定性问题。"
linkTitle: Sentinel限流
title: 使用 Sentinel 应对突发流量，保护您的应用
type: docs
diff --git a/content/zh-cn/overview/mannual/java-sdk/tasks/service-discovery/nacos.md b/content/zh-cn/overview/mannual/java-sdk/tasks/service-discovery/nacos.md
index 4e5c624..c6e01bd 100644
--- a/content/zh-cn/overview/mannual/java-sdk/tasks/service-discovery/nacos.md
+++ b/content/zh-cn/overview/mannual/java-sdk/tasks/service-discovery/nacos.md
@@ -70,10 +70,11 @@
```properties
# dubbo.properties
dubbo.registry.address=nacos://localhost:8848
+dubbo.registry.register-mode=instance
```
或
```xml
-<dubbo:registry address="nacos://localhost:8848" />
+<dubbo:registry address="nacos://localhost:8848" register-mode="instance"/>
```
## 2 高级配置
@@ -85,6 +86,7 @@
dubbo
registry
address: nacos://localhost:8848?username=nacos&password=nacos
+ register-mode: instance
```
或
@@ -103,6 +105,7 @@
dubbo:
registry:
address: nacos://localhost:8848?namespace=5cbb70a5-xxx-xxx-xxx-d43479ae0932
+ register-mode: instance # 新用户请设置此值，表示启用应用级服务发现，可选值 interface、instance、all
```
或者
@@ -112,6 +115,7 @@
dubbo:
registry:
address: nacos://localhost:8848
+ register-mode: instance # 新用户请设置此值，表示启用应用级服务发现，可选值 interface、instance、all
parameters.namespace: 5cbb70a5-xxx-xxx-xxx-d43479ae0932
```
@@ -122,6 +126,7 @@
dubbo:
registry:
address: nacos://localhost:8848
+ register-mode: instance # 新用户请设置此值，表示启用应用级服务发现，可选值 interface、instance、all
group: dubbo
```
@@ -133,6 +138,7 @@
# application.yml
dubbo:
registry:
+ register-mode: instance # 新用户请设置此值，表示启用应用级服务发现，可选值 interface、instance、all
address: nacos://localhost:8848?register-consumer-url=true
```
或者
@@ -141,6 +147,7 @@
dubbo:
registry:
address: nacos://localhost:8848
+ register-mode: instance # 新用户请设置此值，表示启用应用级服务发现，可选值 interface、instance、all
parameters.register-consumer-url: true
```
diff --git a/content/zh-cn/overview/mannual/java-sdk/tasks/service-discovery/registry.md b/content/zh-cn/overview/mannual/java-sdk/tasks/service-discovery/registry.md
index bfcccce..95b99ca 100644
--- a/content/zh-cn/overview/mannual/java-sdk/tasks/service-discovery/registry.md
+++ b/content/zh-cn/overview/mannual/java-sdk/tasks/service-discovery/registry.md
@@ -89,8 +89,10 @@
dubbo
registries
beijingRegistry
+ register-mode: instance #新用户建议使用，老用户如继续使用老服务发现模型则删除此配置
address: zookeeper://localhost:2181
shanghaiRegistry
+ register-mode: instance #新用户建议使用，老用户如继续使用老服务发现模型则删除此配置
address: zookeeper://localhost:2182
```
@@ -259,12 +261,13 @@
enableEmptyProtection: true
```
+## 直连提供者
+如果你的项目开启了服务发现，但在测试中想调用某个特定的 ip，可通过设置对端 ip 地址的 [直连模式]() 绕过服务发现机制进行调用。
+
## 问题排查
相比于 client 到 server 的 RPC 直连调用，开启服务发现后，常常会遇到各种个样奇怪的调用失败问题，以下是一些常见的问题与排查方法。
-如果你的项目开启了服务发现，但在测试中想调用某个特定的 ip，可通过设置对端 ip 地址的 [直连模式]() 绕过服务发现机制进行调用。
-
1. **消费方找不到可用地址 (No Provider available)**，这里有详细的 [具体原因排查步骤]()。
-2. **忘记配置注册中心**，从 3.3.0 开始，不配置注册中心应用也是能够正常启动的，只是应用的任何服务都不会注册到注册中心，或者从注册中心订阅地址列表。
+2. **忘记配置注册中心**，从 3.3.0 开始，不配置注册中心地址的情况下，应用也是能够正常启动的，只是应用的任何服务都不会注册到注册中心，或者从注册中心订阅地址列表。
3. **注册中心连不上**，如果配置了 `check=false`，虽然进程启动成功，可能服务注册、订阅并没有成功。
4. **消费方因没有有效的地址而启动报错**，可以通过配置ReferenceConfig跳过可用地址列表检查，注解示例为 `@DubboRerefence(check=false)`。
diff --git a/content/zh-cn/overview/mannual/java-sdk/tasks/service-discovery/zookeeper.md b/content/zh-cn/overview/mannual/java-sdk/tasks/service-discovery/zookeeper.md
index 0144572..1d512ed 100644
--- a/content/zh-cn/overview/mannual/java-sdk/tasks/service-discovery/zookeeper.md
+++ b/content/zh-cn/overview/mannual/java-sdk/tasks/service-discovery/zookeeper.md
@@ -114,7 +114,7 @@
```
或
```xml
-<dubbo:registry address="zookeeper://localhost:2181" />
+<dubbo:registry address="zookeeper://localhost:2181" register-mode="instance" />
```
`address` 是启用 zookeeper 注册中心唯一必须指定的属性，而在生产环境下，`address` 通常被指定为集群地址，如
@@ -135,6 +135,7 @@
dubbo
registry
address: zookeeper://localhost:2181
+ register-mode: instance # 新用户请设置此值，表示启用应用级服务发现，可选值 interface、instance、all
username: hello
password: 1234
```
@@ -149,6 +150,7 @@
dubbo
registry
address: zookeeper://localhost:2181
+ register-mode: instance # 新用户请设置此值，表示启用应用级服务发现，可选值 interface、instance、all
group: daily1
```
@@ -159,6 +161,7 @@
dubbo
registry
address: zookeeper://localhost:2181
+ register-mode: instance # 新用户请设置此值，表示启用应用级服务发现，可选值 interface、instance、all
timeout: 30 * 1000* # 连接超时时间，默认 30s
session: 60 * 1000* # 会话超时时间，默认 60s
```
diff --git a/static/imgs/v3/manual/java/migration/dubbo-to-triple.png b/static/imgs/v3/manual/java/migration/dubbo-to-triple.png
new file mode 100644
index 0000000..5decd4c
--- /dev/null
+++ b/static/imgs/v3/manual/java/migration/dubbo-to-triple.png
Binary files differ
