Submit 3.2 upgrade docs (#2515)

content/en/docs3-v2/java-sdk/upgrades-and-compatibility/3.1-to-3.2-compatibility-guide.md

@@ -1,28 +1,58 @@
 ---
+description: Dubbo 3.2 Upgrade and Compatibility Guide
+linkTitle: 3.1 upgrade to 3.2
+title: 3.1 upgrade to 3.2
 type: docs
-title: "3.1 Upgrade to 3.2 Operation Guide"
-linkTitle: "3.1 Upgrade to 3.2 Operation Guide"
-weight: 1001
-description: "Quickly understand the upgrade steps and compatibility of Dubbo 3.2"
+weight: 3
 ---
 
-# Function modification points
+For the vast majority of users, upgrading to Dubbo 3.2.0 is completely smooth, and only needs to modify the version of the dependent package.
 
-## 1. Transitive dependency changes
+```xml
+<dependency>
+    <groupId>org.apache.dubbo</groupId>
+    <artifactId>dubbo</artifactId>
+    <version>3.2.0</version>
+</dependency>
+```
 
-* Dubbo version 3.2.0 no longer shade `hessian-lite` code in `dubbo-all` by default, but use transitive dependency transfer instead. If you don't need to use `hessian-lite` in your application, you can remove `hessian-lite` from dependencies.
-* From version 3.2.0 of Dubbo, `gson`, `fastjson` dependencies are no longer passed in `dubbo-all`, if you need to use `gson`, `fastjson` in your application, please manually install `gson`, `fastjson` ` Dependencies are added to the application.
-* Dubbo 3.2.0 version passes `fastjson2` dependency in `dubbo-all`.
+or
 
-## 2. Default serialization switch
+```xml
+<dependency>
+    <groupId>org.apache.dubbo</groupId>
+    <artifactId>dubbo-spring-boot-starter</artifactId>
+    <version>3.2.0</version>
+</dependency>
+```
+
+# Compatibility CheckList
+
+## 1. Serialization check mode (important!!!)
+
+In Dubbo 3.2.0 version, Dubbo will enable the strong verification of the serialized whitelist by default to improve the security of Dubbo and avoid the problem of remote command execution.
+For some users who use generics and may have incomplete scanning or **large service scale**, we recommend that you add `-Ddubbo.application.serialize-check-status=WARN` configuration.
+After observing for a period of time (via logs and QoS commands), if no security alarm is triggered, you can configure the strong check mode.
 
-* Starting from version 3.2.0 of Dubbo, the default serialization method is switched from `hessian2` to `fastjson2`. For applications upgraded to 3.2.0, Dubbo will automatically try to use `fastjson2` for serialization.
+For the configuration of the custom whitelist, please refer to [Documentation/SDK Manual/Java SDK/Advanced Features and Usage/Improve Security/Class Inspection Mechanism](/en/docs3-v2/java-sdk/advanced-features-and-usage/security/class-check/) article to configure.
 
-#### FAQ
+#### Q1: Why do you need to enable strong verification of the serialization whitelist?
+
+Due to the problem of Java's own mechanism, the non-IDL serialization supported by Dubbo naturally allows access to arbitrary classes, which may lead to remote command execution (RCE) risks.
+
+#### Q2: What are the best practices for upgrading to 3.2?
+
+We recommend **all users** to add `-Ddubbo.application.serialize-check-status=WARN` configuration before upgrading Dubbo 3.2.0 to ensure the best compatibility. Otherwise, it may lead to abnormal online data!
+
+---
+
+## 2. Default serialization switch
+
+Starting from Dubbo version 3.2.0, the default serialization method is switched from `hessian2` to `fastjson2`. For applications upgraded to 3.2.0, Dubbo will automatically try to use `fastjson2` for serialization.
 
 #### Q1: Will it affect the intercommunication with lower versions of Dubbo?
 
-Won't. Interoperability with lower versions still uses `hessian-lite`. For the principle, please refer to [Serialization Protocol Upgrade Guide](/en/docs3-v2/java-sdk/upgrades-and-compatibility/serialization-upgrade/).
+Won't. Interoperability with lower versions still uses `hessian-lite`. For the principle, please refer to [Serialization Protocol Upgrade Guide](/zh-cn/overview/mannual/java-sdk/upgrades-and-compatibility/serialization-upgrade/).
 
 #### Q2: Why switch the default serialization method?
 
@@ -38,11 +68,39 @@ For the specific protocol format, please refer to: [JSONB format](https://github
 
 If you don't want to use `fastjson2`, you can configure `prefer-serialization` to override the default configuration for `hessian2`. (such as `dubbo.provider.prefer-serialization=fastjson2,hessian2`) If there is no special requirement, we do not recommend continuing to use `hessian2`.
 
-## 3. Default internal serialization tool switch
+---
+
+## 3. Push short protection is disabled by default
+
+Since version 3.2.0 of Dubbo, the push protection is turned off by default. Even if the registration center pushes an empty address, Dubbo will not keep the last batch of provider information.
+If you need to enable empty protection, you can configure `dubbo.application.enable-empty-protection` to `true`.
+
+#### Q1: How does disabling push short protection affect me?
+
+In most scenarios it has no effect.
+The purpose of push empty protection is that when the registration center fails and actively pushes empty addresses, Dubbo keeps the last batch of provider information to ensure service availability.
+However, when most registration centers fail, the registration center will not push empty addresses, only in some special cases.
+However, if the push short protection is turned on, it will have a greater impact on Dubbo's Fallback logic, heartbeat logic, etc., and bring troubles to the development and use of Dubbo.
+
+#### Q2: I want to enable short push protection, what should I do?
+
+If you need to enable push empty protection for high availability in production, you can configure `dubbo.application.enable-empty-protection` to `true`.
+At present, it is known that turning on the push-out protection will cause the server-side application to upgrade from `2.6. In this scenario, the service call will fail.
+In addition, after the push-to-empty protection is turned on, when the server address is really empty, there will be more heartbeat exceptions and log exceptions.
+
+---
 
-* Starting from version 3.2.0 of Dubbo, the **internal** serialization tool is switched from `fastjson` to `fastjson2` by default.
+## 4. Transitive dependency changes
+
+* Dubbo version 3.2.0 no longer shade `hessian-lite` code in `dubbo-all` by default, but use transitive dependency transfer instead. If you don't need to use `hessian-lite` in your application, you can remove `hessian-lite` from dependencies.
+* From version 3.2.0 of Dubbo, `gson`, `fastjson` dependencies are no longer passed in `dubbo-all`, if you need to use `gson`, `fastjson` in your application, please manually install `gson`, `fastjson` ` Dependencies are added to the application.
+* Dubbo 3.2.0 version passes `fastjson2` dependency in `dubbo-all`.
+
+---
 
-#### FAQ
+## 5. Default internal serialization tool switch
+
+Since version 3.2.0 of Dubbo, the default **internal** serialization tool is switched from `fastjson` to `fastjson2`.
 
 #### Q1: Will it affect the RPC request traffic?
 
@@ -54,32 +112,29 @@ From version 3.2.0 of Dubbo, the default transitive dependencies no longer pass
 
 #### Q3: What if there is no `fastjson2` in my environment?
 
-Dubbo supports automatic switching of multiple serialization frameworks. If there is no `fastjson2` in your environment, Dubbo will automatically try to switch to `fastsjon` or `gson`.
+Dubbo supports automatic switching of various serialization frameworks. If there is no `fastjson2` in your environment, Dubbo will automatically try to switch to `fastsjon` or `gson`.
 
 #### Q4: I want to specify the internal serialization tool of Dubbo, what should I do?
 
 You can configure `dubbo.json-framework.prefer` parameters, such as `-Ddubbo.json-framework.prefer=gson`.
 
-## 4. Triple protocol supports passing custom exceptions
+---
 
-* Starting from Dubbo version 3.2.0, the Triple protocol supports returning custom exceptions instead of only returning `RpcException`. If the service interface throws an exception, after Dubbo 3.2.0, the custom exception object will be returned by default according to the Dubbo protocol.
+## 6. Triple protocol supports passing custom exceptions
 
-## 5. Push short protection is disabled by default
+Starting from Dubbo version 3.2.0, the Triple protocol supports returning custom exceptions instead of only returning `RpcException`. If the service interface throws an exception, after Dubbo 3.2.0, the custom exception object will be returned by default according to the Dubbo protocol.
 
-* Dubbo version 3.2.0 starts to disable push protection by default, even if the registration center pushes empty addresses, Dubbo will not keep the last batch of provider information.
-  If you need to enable empty protection, you can configure `dubbo.application.enable-empty-protection` to `true`.
+---
 
-#### FAQ
+## 7. Triple protocol version number alignment
 
-#### Q1: How does disabling push short protection affect me?
+Starting from Dubbo version 3.2.0, the communication of the Triple protocol requires the version number and grouping of the client and server to be consistent, otherwise the service will not be found. When interoperating with the native gRPC SDK, the Dubbo side cannot configure groups and version numbers.
 
-In most scenarios it has no effect.
-The purpose of push empty protection is that when the registration center fails and actively pushes empty addresses, Dubbo keeps the last batch of provider information to ensure service availability.
-However, when most registration centers fail, the registration center will not push empty addresses, only in some special cases.
-However, if the push short protection is turned on, it will have a greater impact on Dubbo's Fallback logic, heartbeat logic, etc., and bring troubles to the development and use of Dubbo.
+#### Q1: How was Dubbo before 3.2.0?
 
-#### Q2: I want to enable short push protection, what should I do?
+1) Triple will think that the empty version number is consistent with the 1.0.0 version number. If your server and client version numbers are inconsistent, but they are both empty version numbers or 1.0.0 version numbers, they can communicate normally.
+2) For a service that does not match a version number, Triple will try to match a service with any version number. If it matches a service with any version number, it can also communicate normally.
 
-If you need to enable push empty protection for high availability in production, you can configure `dubbo.application.enable-empty-protection` to `true`.
-At present, it is known that turning on the push-out protection will cause the server-side application to upgrade from `2.6. In this scenario, the service call will fail.
-In addition, after the push-to-empty protection is turned on, when the server address is really empty, there will be more heartbeat exceptions and log exceptions.
+#### Q2: How to ensure that it is aligned with the original behavior?
+
+By configuring `-Ddubbo.rpc.tri.ignore-1.0.0-version=true -Ddubbo.rpc.tri.resolve-fallback-to-default=true`, the previous behavior of Dubbo 3.2.0 can be achieved.

content/zh-cn/overview/mannual/java-sdk/upgrades-and-compatibility/3.1-to-3.2-compatibility-guide.md

@@ -9,24 +9,49 @@ type: docs
 weight: 3
 ---
 
+对于绝大多数的用户，升级到 Dubbo 3.2.0 是完全平滑的，仅需要修改依赖包版本即可。
 
+```xml
+<dependency>
+    <groupId>org.apache.dubbo</groupId>
+    <artifactId>dubbo</artifactId>
+    <version>3.2.0</version>
+</dependency>
+```
 
+或者
 
+```xml
+<dependency>
+    <groupId>org.apache.dubbo</groupId>
+    <artifactId>dubbo-spring-boot-starter</artifactId>
+    <version>3.2.0</version>
+</dependency>
+```
 
+# 兼容性 CheckList
 
-# 功能修改点
+## 1. 序列化检查模式（重要！！！）
 
-## 1. 传递依赖变更
+在 Dubbo 3.2.0 版本中，Dubbo 将默认开启序列化白名单的强校验，以提升 Dubbo 的安全性，避免远程命令执行的问题。
+对于一些使用了泛型等可能存在扫描不全或者是**服务规模较大**的用户，我们建议您添加 `-Ddubbo.application.serialize-check-status=WARN` 配置。
+观察一段时间后（通过日志、QoS 命令），如果没有触发安全告警，则可以配置强校验模式。
 
-* Dubbo 3.2.0 版本开始默认不再在 `dubbo-all` 中 shade `hessian-lite` 的代码，而是使用传递依赖传递。如果你的应用中不需要使用 `hessian-lite`，可以将 `hessian-lite` 从依赖中移除。
-* Dubbo 3.2.0 版本开始在 `dubbo-all` 中不再传递 `gson`、`fastjson` 依赖，如果你的应用中需要使用 `gson`、`fastjson`，请手动将 `gson`、`fastjson` 依赖添加到应用中。
-* Dubbo 3.2.0 版本在 `dubbo-all` 中传递 `fastjson2` 依赖。
+关于自定义白名单的配置，可以参考官网的 [文档 / SDK 手册 / Java SDK / 高级特性和用法 / 提升安全性 / 类检查机制](/zh-cn/overview/mannual/java-sdk/advanced-features-and-usage/security/class-check/) 一文进行配置。
 
-## 2. 默认序列化切换
+#### Q1：为什么要开启序列化白名单的强校验？
+
+由于 Java 本身机制的问题，Dubbo 支持的非 IDL 序列化天然允许访问任意类，这将可能导致远程命令执行（RCE）风险。
+
+#### Q2：升级到 3.2 的最佳实践是什么？
 
-* Dubbo 3.2.0 版本开始默认序列化方式从 `hessian2` 切换为 `fastjson2`，对于升级到 3.2.0 的应用，Dubbo 会自动尝试采用 `fastjson2` 进行序列化。
+我们建议**所有用户**在升级 Dubbo 3.2.0 版本前添加 `-Ddubbo.application.serialize-check-status=WARN` 配置以保证最佳的兼容性。否则可能导致线上数据异常的情况！
 
-#### FAQ
+---
+
+## 2. 默认序列化切换
+
+Dubbo 3.2.0 版本开始默认序列化方式从 `hessian2` 切换为 `fastjson2`，对于升级到 3.2.0 的应用，Dubbo 会自动尝试采用 `fastjson2` 进行序列化。
 
 #### Q1：会不会影响和低版本的 Dubbo 互通？
 
@@ -46,11 +71,39 @@ Dubbo 中使用 `fastjson2` 的 JSONB 格式，而不是原生的 JSON 格式。
 
 如果你不想使用 `fastjson2`，可以配置 `prefer-serialization` 为 `hessian2` 覆盖默认配置。（如 `dubbo.provider.prefer-serialization=fastjson2,hessian2`） 如果没有特殊的需求，我们不建议仍继续使用 `hessian2`。
 
-## 3. 默认内部序列化工具切换
+---
+
+## 3. 默认关闭推空保护
 
-* Dubbo 3.2.0 版本开始默认**内部**序列化工具从 `fastjson` 切换为 `fastjson2`。
+Dubbo 3.2.0 版本开始默认关闭推空保护，即使注册中心推送空地址，Dubbo 也将不会保留最后一批 provider 信息。
+如果需要开启推空保护，可以配置 `dubbo.application.enable-empty-protection` 为 `true`。
+
+#### Q1：关闭推空保护对我有什么影响？
+
+在绝大部分场景下没有影响。
+推空保护的目的是在注册中心出现故障并且主动推送空地址的时候，Dubbo 保留最后一批 provider 信息，以保证服务可用。
+但是在大多数注册中心出现故障的时候，注册中心也不会推送空地址，只有一些特殊情况才会出现。
+但如果开启推空保护，将对 Dubbo 的 Fallback 逻辑、心跳逻辑等造成较大的影响，给开发使用 Dubbo 带来困扰。
+
+#### Q2：我想开启推空保护，怎么办？
 
-#### FAQ
+如果在生产上为了高可用，需要开启推空保护，可以配置 `dubbo.application.enable-empty-protection` 为 `true`。
+目前已知开启推空保护会导致服务端应用从 `2.6.x`、`2.7.x` 等仅支持接口级服务发现的版本升级到 `3.x` 之后回滚到原来版本出现异常，极端场景下会导致服务调用失败。
+此外，开启推空保护后在服务端地址真的为空的时候出现较多的心跳异常、日志异常等。
+
+---
+
+## 4. 传递依赖变更
+
+* Dubbo 3.2.0 版本开始默认不再在 `dubbo-all` 中 shade `hessian-lite` 的代码，而是使用传递依赖传递。如果你的应用中不需要使用 `hessian-lite`，可以将 `hessian-lite` 从依赖中移除。
+* Dubbo 3.2.0 版本开始在 `dubbo-all` 中不再传递 `gson`、`fastjson` 依赖，如果你的应用中需要使用 `gson`、`fastjson`，请手动将 `gson`、`fastjson` 依赖添加到应用中。
+* Dubbo 3.2.0 版本在 `dubbo-all` 中传递 `fastjson2` 依赖。
+
+---
+
+## 5. 默认内部序列化工具切换
+
+Dubbo 3.2.0 版本开始默认**内部**序列化工具从 `fastjson` 切换为 `fastjson2`。
 
 #### Q1：会不会影响 RPC 请求流量？
 
@@ -68,26 +121,23 @@ Dubbo 支持多种序列化框架自动切换，如果你的环境中没有 `fas
 
 可以配置 `dubbo.json-framework.prefer` 参数，如 `-Ddubbo.json-framework.prefer=gson`。
 
-## 4. Triple 协议支持传递自定义异常
+---
 
-* Dubbo 3.2.0 版本开始 Triple 协议支持回传自定义异常，而不是只能回传 `RpcException`。如果服务接口会抛出异常的，在 Dubbo 3.2.0 版本以后将默认按照 Dubbo 协议一样回传自定义异常对象。
+## 6. Triple 协议支持传递自定义异常
 
-## 5. 默认关闭推空保护
+Dubbo 3.2.0 版本开始 Triple 协议支持回传自定义异常，而不是只能回传 `RpcException`。如果服务接口会抛出异常的，在 Dubbo 3.2.0 版本以后将默认按照 Dubbo 协议一样回传自定义异常对象。
 
-* Dubbo 3.2.0 版本开始默认关闭推空保护，即使注册中心推送空地址，Dubbo 也将不会保留最后一批 provider 信息。
-如果需要开启推空保护，可以配置 `dubbo.application.enable-empty-protection` 为 `true`。
+---
 
-#### FAQ
+## 7. Triple 协议版本号对齐
 
-#### Q1：关闭推空保护对我有什么影响？
+Dubbo 3.2.0 版本开始，Triple 协议的通信要求客户端和服务端的版本号和分组一致，否则会找不到服务。与原生 gRPC SDK 互通时，Dubbo 侧不能配置分组和版本号。
 
-在绝大部分场景下没有影响。
-推空保护的目的是在注册中心出现故障并且主动推送空地址的时候，Dubbo 保留最后一批 provider 信息，以保证服务可用。
-但是在大多数注册中心出现故障的时候，注册中心也不会推送空地址，只有一些特殊情况才会出现。
-但如果开启推空保护，将对 Dubbo 的 Fallback 逻辑、心跳逻辑等造成较大的影响，给开发使用 Dubbo 带来困扰。
+#### Q1：Dubbo 3.2.0 以前是怎么样的？
 
-#### Q2：我想开启推空保护，怎么办？
+1）Triple 会认为空版本号和 1.0.0 版本号一致，如果您的服务端和客户端版本号不一致，但是都是空版本号或者都是 1.0.0 版本号，是可以正常通信的。
+2）对于没有匹配到版本号的服务，Triple 会尝试匹配任意版本号的服务，如果匹配到任意版本号的服务，也是可以正常通信的。
 
-如果在生产上为了高可用，需要开启推空保护，可以配置 `dubbo.application.enable-empty-protection` 为 `true`。
-目前已知开启推空保护会导致服务端应用从 `2.6.x`、`2.7.x` 等仅支持接口级服务发现的版本升级到 `3.x` 之后回滚到原来版本出现异常，极端场景下会导致服务调用失败。
-此外，开启推空保护后在服务端地址真的为空的时候出现较多的心跳异常、日志异常等。
+#### Q2：如何保证和原来行为是对齐的？
+
+通过配置 `-Ddubbo.rpc.tri.ignore-1.0.0-version=true -Ddubbo.rpc.tri.resolve-fallback-to-default=true` 可以实现和 Dubbo 3.2.0 以前的行为。