This is an automated email from the ASF dual-hosted git repository.
liujun pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/dubbo-website.git
The following commit(s) were added to refs/heads/master by this push:
new 12893d4 Refactor and improve config doc of Dubbo 3 (#883)
12893d4 is described below
commit 12893d464852a5ab4b47458a261367b5d69e3a84
Author: Gong Dewei <[email protected]>
AuthorDate: Mon Aug 2 16:00:43 2021 +0800
Refactor and improve config doc of Dubbo 3 (#883)
---
content/zh/docs/concepts/configuration.md | 65 ++++-
content/zh/docs/references/config-center.md | 80 +++++
.../zh/docs/references/configuration/annotation.md | 2 +-
content/zh/docs/references/configuration/api.md | 324 ++++++++++++++++-----
.../configuration/configuration-load-process.md | 180 ------------
.../configuration/environment-variables.md | 2 +-
.../{config-center.md => external-config.md} | 108 ++-----
.../zh/docs/references/configuration/overview.md | 178 +++++++++++
.../zh/docs/references/configuration/properties.md | 259 ++++++++++++++--
content/zh/docs/references/configuration/xml.md | 6 +-
static/imgs/v3/config/config-load.svg | 1 +
static/imgs/v3/config/properties-override.svg | 1 +
12 files changed, 846 insertions(+), 360 deletions(-)
diff --git a/content/zh/docs/concepts/configuration.md
b/content/zh/docs/concepts/configuration.md
index c80f6cf..902971a 100644
--- a/content/zh/docs/concepts/configuration.md
+++ b/content/zh/docs/concepts/configuration.md
@@ -1,7 +1,60 @@
---
- type: docs
- title: "配置管理"
- linkTitle: "配置"
- weight: 4
- description: "描述 Dubbo 支持的配置，Dubbo 的动态配置能力。"
----
\ No newline at end of file
+type: docs
+title: "配置管理"
+linkTitle: "配置"
+weight: 4
+description: "描述 Dubbo 支持的配置，Dubbo 的动态配置能力。"
+---
+
+Dubbo配置主要分为几大类： 启动阶段配置项、服务治理规则、动态配置项。
+
+## 启动阶段配置项
+Dubbo启动时读取的配置项，用于初始化各个组件，不会监听这些配置项的变化。
+
+Dubbo的配置来源有多种，配置项划分为多个配置组件，详细请参考
[配置概述](../../references/configuration/overview)。
+
+### 配置方式
+按照编程方式可以分为四种方式：API配置、XML配置、Annotation配置、属性配置。
+
+#### API配置
+以Java编码的方式组织配置，包括Raw API和Bootstrap
API，具体请参考[API配置](../../references/configuration/api)。
+
+#### XML配置
+以XML方式配置各种组件，支持与Spring无缝集成，具体请参考[XML配置](../../references/configuration/xml)。
+
+#### Annotation配置
+以注解方式暴露服务和引用服务接口，支持与Spring无缝集成，具体请参考[Annotation配置](../../references/configuration/annotation)。
+
+#### 属性配置
+根据Key-value属性生成配置组件，类似SpringBoot的ConfigurationProperties，具体请参考[属性配置](../../references/configuration/properties)。
+
+属性配置的另外一个重要的功能特性是[属性覆盖](../../references/configuration/properties#属性覆盖)，使用外部属性的值覆盖已创建的配置组件属性。
+
+如果要将属性配置放到外部的配置中心，请参考[外部化配置](../../references/configuration/external-config)。
+
+
+## 服务治理规则
+服务治理规则主要作用是改变运行时服务的行为和选址逻辑，达到限流，权重配置等目的，包括覆盖规则、标签路由、条件路由、条件路由。
+
+Dubbo启动后监听服务治理相关的配置项，当配置发生变化时，会自动进行相应的处理。
+
+服务治理规则的用法介绍请参考 [服务治理和配置管理](../../references/governance)
+
+服务治理规则的存储方法请参考 [配置中心#服务治理](../../references/config-center#服务治理)
+
+## 动态配置项
+动态配置项一般用于控制动态开关。
+
+Dubbo启动后监听动态配置项，当配置发生变化时，会自动进行相应的处理。
+
+动态配置的存储方式请参考 [配置中心#动态配置](../../references/config-center#动态配置)
+
+常用的动态配置项如下：
+
+**[TODO 补充动态配置项说明]**
+
+| 名称 | 描述 | 默认值|
+| -----| ---- | ----|
+| dubbo.application.migration.threshold | | |
+| dubbo.application.service-discovery.migration | | |
+
diff --git a/content/zh/docs/references/config-center.md
b/content/zh/docs/references/config-center.md
new file mode 100644
index 0000000..efba74d
--- /dev/null
+++ b/content/zh/docs/references/config-center.md
@@ -0,0 +1,80 @@
+---
+type: docs
+title: "配置中心参考手册"
+linkTitle: "配置中心"
+weight: 2
+description: "Dubbo 配置中心参考手册"
+---
+
+配置中心在 Dubbo 中承担3个职责：
+
+1. 外部化配置：启动配置的集中式存储 （简单理解为 dubbo.properties 的外部化存储）。
+2. 服务治理：服务治理规则的存储与通知。
+3. 动态配置：控制动态开关或者动态变更属性值
+
+启用动态配置，以 Zookeeper 为例，可查看 [配置中心属性详解](../../references/xml/dubbo-config-center)
+
+```xml
+<dubbo:config-center address="zookeeper://127.0.0.1:2181"/>
+```
+
+或者
+
+```properties
+dubbo.config-center.address=zookeeper://127.0.0.1:2181
+```
+
+或者
+
+```java
+ConfigCenterConfig configCenter = new ConfigCenterConfig();
+configCenter.setAddress("zookeeper://127.0.0.1:2181");
+```
+
+> 为了兼容 2.6.x 版本配置，在使用 Zookeeper 作为注册中心，且没有显示配置配置中心的情况下，Dubbo 框架会默认将此 Zookeeper
用作配置中心，但将只作服务治理用途。
+
+## 外部化配置
+请参考文档 [外部化配置](../configuration/external-config)
+
+## 动态配置
+[TODO 待完善]
+
+## 服务治理
+
+#### Zookeeper
+
+默认节点结构：
+
+
+
+- namespace，用于不同配置的环境隔离。
+- config，Dubbo 约定的固定节点，不可更改，所有配置和服务治理规则都存储在此节点下。
+- dubbo，所有服务治理规则都是全局性的，dubbo 为默认节点
+- configurators/tag-router/condition-router/migration，不同的服务治理规则类型，node value
存储具体规则内容
+
+#### Apollo
+
+所有的服务治理规则都是全局性的，默认从公共命名空间 `dubbo` 读取和订阅：
+
+
+
+不同的规则以不同的 key 后缀区分：
+
+- configurators，[覆盖规则](../../examples/config-rule)
+- tag-router，[标签路由](../../examples/routing-rule)
+- condition-router，[条件路由](../../examples/condition-router)
+- migration, [迁移规则](../../examples/todo)
+
+#### Nacos
+
+所有的服务治理规则都是全局的，默认从 namespace: `public` 下进行读取， 通过 dataId: `interface name` 以及
group: `dubbo` 去读取和订阅：
+
+
+
+不同的规则以 dataId 的后缀区分：
+
+- configurators，[覆盖规则](../../examples/config-rule)
+- tag-router，[标签路由](../../examples/routing-rule)
+- condition-router，[条件路由](../../examples/condition-router)
+- migration, [迁移规则](../../examples/todo)
+
diff --git a/content/zh/docs/references/configuration/annotation.md
b/content/zh/docs/references/configuration/annotation.md
index 63a1469..1daf59a 100644
--- a/content/zh/docs/references/configuration/annotation.md
+++ b/content/zh/docs/references/configuration/annotation.md
@@ -2,7 +2,7 @@
type: docs
title: "注解配置"
linkTitle: "注解配置"
-weight: 4
+weight: 40
description: "以注解配置的方式来配置你的 Dubbo 应用"
---
diff --git a/content/zh/docs/references/configuration/api.md
b/content/zh/docs/references/configuration/api.md
index ba92508..3a805df 100644
--- a/content/zh/docs/references/configuration/api.md
+++ b/content/zh/docs/references/configuration/api.md
@@ -2,91 +2,279 @@
type: docs
title: "API 配置"
linkTitle: "API 配置"
-weight: 3
+weight: 20
description: "以API 配置的方式来配置你的 Dubbo 应用"
---
-API
属性与配置项一对一，各属性含义，请参见：[配置参考手册](../references/xml/)，比如：`ApplicationConfig.setName("xxx")`
对应 `<dubbo:application name="xxx" />` [^1]
+通过API编码方式组装配置，启动Dubbo，发布及订阅服务。此方式可以支持动态创建ReferenceConfig/ServiceConfig，结合泛化调用可以满足API
Gateway或测试平台的需要。
+
+> API
属性与XML配置项一一对应，各属性含义请参见：[XML配置参考手册](../../../references/xml/)，比如：`ApplicationConfig.setName("xxx")`
对应 `<dubbo:application name="xxx" />`
+
+> API使用范围说明：API 仅用于 OpenAPI, ESB, Test, Mock, Gateway
等系统集成，普通服务提供方或消费方，请采用[XML 配置](../xml) 或
+> [注解配置](../annotation) 或 [属性配置](../properties) 方式使用 Dubbo
+
+>
参考[API示例](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-api)
## 服务提供者
+通过ServiceConfig暴露服务接口，发布服务接口到注册中心。
+
+> 注意：为了更好支持Dubbo3的应用级服务发现，推荐使用新的DubboBootstrap API。
+
```java
import org.apache.dubbo.rpc.config.ApplicationConfig;
import org.apache.dubbo.rpc.config.RegistryConfig;
import org.apache.dubbo.rpc.config.ProviderConfig;
import org.apache.dubbo.rpc.config.ServiceConfig;
-import com.xxx.XxxService;
-import com.xxx.XxxServiceImpl;
-
-// 服务实现
-XxxService xxxService = new XxxServiceImpl();
-
-// 当前应用配置
-ApplicationConfig application = new ApplicationConfig();
-application.setName("xxx");
-
-// 连接注册中心配置
-RegistryConfig registry = new RegistryConfig();
-registry.setAddress("10.20.130.230:9090");
-registry.setUsername("aaa");
-registry.setPassword("bbb");
-
-// 服务提供者协议配置
-ProtocolConfig protocol = new ProtocolConfig();
-protocol.setName("dubbo");
-protocol.setPort(12345);
-protocol.setThreads(200);
-
-// 注意：ServiceConfig为重对象，内部封装了与注册中心的连接，以及开启服务端口
-
-// 服务提供者暴露服务配置
-ServiceConfig<XxxService> service = new ServiceConfig<XxxService>(); //
此实例很重，封装了与注册中心的连接，请自行缓存，否则可能造成内存和连接泄漏
-service.setApplication(application);
-service.setRegistry(registry); // 多个注册中心可以用setRegistries()
-service.setProtocol(protocol); // 多个协议可以用setProtocols()
-service.setInterface(XxxService.class);
-service.setRef(xxxService);
-service.setVersion("1.0.0");
-
-// 暴露及注册服务
-service.export();
+import com.xxx.DemoService;
+import com.xxx.DemoServiceImpl;
+
+public class DemoProvider {
+ public static void main(String[] args) {
+ // 服务实现
+ DemoService demoService = new DemoServiceImpl();
+
+ // 当前应用配置
+ ApplicationConfig application = new ApplicationConfig();
+ application.setName("demo-provider");
+
+ // 连接注册中心配置
+ RegistryConfig registry = new RegistryConfig();
+ registry.setAddress("zookeeper://10.20.130.230:2181");
+
+ // 服务提供者协议配置
+ ProtocolConfig protocol = new ProtocolConfig();
+ protocol.setName("dubbo");
+ protocol.setPort(12345);
+ protocol.setThreads(200);
+
+ // 注意：ServiceConfig为重对象，内部封装了与注册中心的连接，以及开启服务端口
+ // 服务提供者暴露服务配置
+ ServiceConfig<DemoService> service = new ServiceConfig<DemoService>();
// 此实例很重，封装了与注册中心的连接，请自行缓存，否则可能造成内存和连接泄漏
+ service.setApplication(application);
+ service.setRegistry(registry); // 多个注册中心可以用setRegistries()
+ service.setProtocol(protocol); // 多个协议可以用setProtocols()
+ service.setInterface(DemoService.class);
+ service.setRef(demoService);
+ service.setVersion("1.0.0");
+
+ // 暴露及注册服务
+ service.export();
+
+ // 挂起等待(防止进程退出）
+ System.in.read();
+ }
+}
```
## 服务消费者
+通过ReferenceConfig引用远程服务，从注册中心订阅服务接口。
+
+> 注意：为了更好支持Dubbo3的应用级服务发现，推荐使用新的DubboBootstrap API。
+
```java
import org.apache.dubbo.rpc.config.ApplicationConfig;
import org.apache.dubbo.rpc.config.RegistryConfig;
import org.apache.dubbo.rpc.config.ConsumerConfig;
import org.apache.dubbo.rpc.config.ReferenceConfig;
-import com.xxx.XxxService;
-
-// 当前应用配置
-ApplicationConfig application = new ApplicationConfig();
-application.setName("yyy");
-
-// 连接注册中心配置
-RegistryConfig registry = new RegistryConfig();
-registry.setAddress("10.20.130.230:9090");
-registry.setUsername("aaa");
-registry.setPassword("bbb");
-
-// 注意：ReferenceConfig为重对象，内部封装了与注册中心的连接，以及与服务提供方的连接
-
-// 引用远程服务
-ReferenceConfig<XxxService> reference = new ReferenceConfig<XxxService>(); //
此实例很重，封装了与注册中心的连接以及与提供者的连接，请自行缓存，否则可能造成内存和连接泄漏
-reference.setApplication(application);
-reference.setRegistry(registry); // 多个注册中心可以用setRegistries()
-reference.setInterface(XxxService.class);
-reference.setVersion("1.0.0");
-
-// 和本地bean一样使用xxxService
-XxxService xxxService = reference.get(); // 注意：此代理对象内部封装了所有通讯细节，对象较重，请缓存复用
+import com.xxx.DemoService;
+
+public class DemoConsumer {
+ public static void main(String[] args) {
+ // 当前应用配置
+ ApplicationConfig application = new ApplicationConfig();
+ application.setName("demo-consumer");
+
+ // 连接注册中心配置
+ RegistryConfig registry = new RegistryConfig();
+ registry.setAddress("zookeeper://10.20.130.230:2181");
+
+ // 注意：ReferenceConfig为重对象，内部封装了与注册中心的连接，以及与服务提供方的连接
+ // 引用远程服务
+ ReferenceConfig<DemoService> reference = new
ReferenceConfig<DemoService>(); //
此实例很重，封装了与注册中心的连接以及与提供者的连接，请自行缓存，否则可能造成内存和连接泄漏
+ reference.setApplication(application);
+ reference.setRegistry(registry); // 多个注册中心可以用setRegistries()
+ reference.setInterface(DemoService.class);
+ reference.setVersion("1.0.0");
+
+ // 和本地bean一样使用demoService
+ // 注意：此代理对象内部封装了所有通讯细节，对象较重，请缓存复用
+ DemoService demoService = reference.get();
+ demoService.sayHello("Dubbo");
+ }
+}
```
-## 特殊场景
+## Bootstrap API
+
+通过DubboBootstrap API可以减少重复配置，更好控制启动过程，支持批量发布/订阅服务接口，还可以更好支持Dubbo3的应用级服务发现。
+
+```java
+import org.apache.dubbo.config.bootstrap.DubboBootstrap;
+import org.apache.dubbo.rpc.config.ApplicationConfig;
+import org.apache.dubbo.rpc.config.RegistryConfig;
+import org.apache.dubbo.rpc.config.ProviderConfig;
+import org.apache.dubbo.rpc.config.ServiceConfig;
+import com.xxx.DemoService;
+import com.xxx.DemoServiceImpl;
-下面只列出不同的地方，其它参见上面的写法
+public class DemoProvider {
+ public static void main(String[] args) {
+
+ ConfigCenterConfig configCenter = new ConfigCenterConfig();
+ configCenter.setAddress("zookeeper://127.0.0.1:2181");
+
+ // 服务提供者协议配置
+ ProtocolConfig protocol = new ProtocolConfig();
+ protocol.setName("dubbo");
+ protocol.setPort(12345);
+ protocol.setThreads(200);
+
+ // 注意：ServiceConfig为重对象，内部封装了与注册中心的连接，以及开启服务端口
+ // 服务提供者暴露服务配置
+ ServiceConfig<DemoService> demoServiceConfig = new ServiceConfig<>();
+ demoServiceConfig.setInterface(DemoService.class);
+ demoServiceConfig.setRef(new DemoServiceImpl());
+ demoServiceConfig.setVersion("1.0.0");
+
+ // 第二个服务配置
+ ServiceConfig<FooService> fooServiceConfig = new ServiceConfig<>();
+ fooServiceConfig.setInterface(FooService.class);
+ fooServiceConfig.setRef(new FooServiceImpl());
+ fooServiceConfig.setVersion("1.0.0");
+
+ ...
+
+ // 通过DubboBootstrap简化配置组装，控制启动过程
+ DubboBootstrap.getInstance()
+ .application("demo-provider") // 应用配置
+ .registry(new RegistryConfig("zookeeper://127.0.0.1:2181")) //
注册中心配置
+ .protocol(protocol) // 全局默认协议配置
+ .service(demoServiceConfig) // 添加ServiceConfig
+ .service(fooServiceConfig)
+ .start() // 启动Dubbo
+ .await(); // 挂起等待(防止进程退出）
+ }
+}
+```
+
+```java
+import org.apache.dubbo.config.bootstrap.DubboBootstrap;
+import org.apache.dubbo.rpc.config.ApplicationConfig;
+import org.apache.dubbo.rpc.config.RegistryConfig;
+import org.apache.dubbo.rpc.config.ProviderConfig;
+import org.apache.dubbo.rpc.config.ServiceConfig;
+import com.xxx.DemoService;
+import com.xxx.DemoServiceImpl;
+
+public class DemoConsumer {
+ public static void main(String[] args) {
+
+ // 引用远程服务
+ ReferenceConfig<DemoService> demoServiceReference = new
ReferenceConfig<DemoService>();
+ demoServiceReference.setInterface(DemoService.class);
+ demoServiceReference.setVersion("1.0.0");
+
+ ReferenceConfig<FooService> fooServiceReference = new
ReferenceConfig<FooService>();
+ fooServiceReference.setInterface(FooService.class);
+ fooServiceReference.setVersion("1.0.0");
+
+ // 通过DubboBootstrap简化配置组装，控制启动过程
+ DubboBootstrap bootstrap = DubboBootstrap.getInstance();
+ bootstrap.application("demo-consumer") // 应用配置
+ .registry(new RegistryConfig("zookeeper://127.0.0.1:2181")) //
注册中心配置
+ .reference(demoServiceReference) // 添加ReferenceConfig
+ .service(fooServiceReference)
+ .start(); // 启动Dubbo
+
+ ...
+
+ // 和本地bean一样使用demoService
+ // 通过Interface获取远程服务接口代理，不需要依赖ReferenceConfig对象
+ DemoService demoService =
DubboBootstrap.getInstance().getCache().get(DemoService.class);
+ demoService.sayHello("Dubbo");
+
+ FooService fooService =
DubboBootstrap.getInstance().getCache().get(FooService.class);
+ fooService.greeting("Dubbo");
+ }
+
+}
+
+```
+
+## 其它配置
+
+API配置能力与XML配置是等价的，其它的各种配置都可以用API设置。
+
+下面只列出不同的地方，其它参见上面的写法。
+
+### 基本配置
+
+可以在DubboBootstrap中设置全局基本配置，包括应用配置、协议配置、注册中心、配置中心、元数据中心、模块、监控、SSL、provider配置、consumer配置等。
+
+```java
+// 注册中心
+RegistryConfig registry = new RegistryConfig();
+registry.setAddress("zookeeper://192.168.10.1:2181");
+...
+
+// 服务提供者协议配置
+ProtocolConfig protocol = new ProtocolConfig();
+protocol.setName("dubbo");
+protocol.setPort(12345);
+protocol.setThreads(200);
+...
+
+// 配置中心
+ConfigCenterConfig configCenter = new ConfigCenterConfig();
+configCenter.setAddress("zookeeper://192.168.10.2:2181");
+...
+
+// 元数据中心
+MetadataReportConfig metadataReport = new MetadataReportConfig();
+metadataReport.setAddress("zookeeper://192.168.10.3:2181");
+...
+
+// Metrics
+MetricsConfig metrics = new MetricsConfig();
+metrics.setProtocol("dubbo");
+...
+
+// SSL
+SslConfig ssl = new SslConfig();
+ssl.setServerKeyCertChainPath("/path/ssl/server-key-cert-chain");
+ssl.setServerPrivateKeyPath("/path/ssl/server-private-key");
+...
+
+// Provider配置（ServiceConfig默认配置）
+ProviderConfig provider = new ProviderConfig();
+provider.setGroup("demo");
+provider.setVersion("1.0.0");
+...
+
+// Consumer配置（ReferenceConfig默认配置）
+ConsumerConfig consumer = new ConsumerConfig();
+consumer.setGroup("demo");
+consumer.setVersion("1.0.0");
+consumer.setTimeout(2000);
+...
+
+DubboBootstrap.getInstance()
+ .application("demo-app")
+ .registry(registry)
+ .protocol(protocol)
+ .configCenter(configCenter)
+ .metadataReport(metadataReport)
+ .module(new ModuleConfig("module"))
+ .metrics(metrics)
+ .ssl(ssl)
+ .provider(provider)
+ .consumer(consumer)
+ ...
+ .start();
+
+```
### 方法级设置
@@ -96,13 +284,13 @@ XxxService xxxService = reference.get(); // 注意：此代理对象内部封装
// 方法级配置
List<MethodConfig> methods = new ArrayList<MethodConfig>();
MethodConfig method = new MethodConfig();
-method.setName("createXxx");
+method.setName("sayHello");
method.setTimeout(10000);
method.setRetries(0);
methods.add(method);
// 引用远程服务
-ReferenceConfig<XxxService> reference = new ReferenceConfig<XxxService>(); //
此实例很重，封装了与注册中心的连接以及与提供者的连接，请自行缓存，否则可能造成内存和连接泄漏
+ReferenceConfig<DemoService> reference = new ReferenceConfig<DemoService>();
// 此实例很重，封装了与注册中心的连接以及与提供者的连接，请自行缓存，否则可能造成内存和连接泄漏
...
reference.setMethods(methods); // 设置方法级配置
@@ -114,14 +302,14 @@ reference.setMethods(methods); // 设置方法级配置
```java
...
-
-ReferenceConfig<XxxService> reference = new ReferenceConfig<XxxService>(); //
此实例很重，封装了与注册中心的连接以及与提供者的连接，请自行缓存，否则可能造成内存和连接泄漏
+
+// 此实例很重，封装了与注册中心的连接以及与提供者的连接，请自行缓存，否则可能造成内存和连接泄漏
+ReferenceConfig<DemoService> reference = new ReferenceConfig<DemoService>();
// 如果点对点直连，可以用reference.setUrl()指定目标地址，设置url后将绕过注册中心，
// 其中，协议对应provider.setProtocol()的值，端口对应provider.setPort()的值，
// 路径对应service.setPath()的值，如果未设置path，缺省path为接口名
-reference.setUrl("dubbo://10.20.130.230:20880/com.xxx.XxxService");
+reference.setUrl("dubbo://10.20.130.230:20880/com.xxx.DemoService");
...
```
-[^1]: API使用范围说明：API 仅用于 OpenAPI, ESB, Test, Mock 等系统集成，普通服务提供方或消费方，请采用[XML
配置](../xml)方式使用 Dubbo
diff --git
a/content/zh/docs/references/configuration/configuration-load-process.md
b/content/zh/docs/references/configuration/configuration-load-process.md
deleted file mode 100644
index 6398a70..0000000
--- a/content/zh/docs/references/configuration/configuration-load-process.md
+++ /dev/null
@@ -1,180 +0,0 @@
----
-type: docs
-title: "配置加载流程"
-linkTitle: "配置加载流程"
-weight: 5
-description: "Dubbo 中的配置加载流程介绍"
----
-
-此篇文档主要讲在**应用启动阶段，Dubbo框架如何将所需要的配置采集起来**（包括应用配置、注册中心配置、服务配置等），以完成服务的暴露和引用流程。
-
-根据驱动方式的不同（比如Spring或裸API编程）配置形式上肯定会有所差异，具体请参考[XML配置](../xml)、[Annotation配置](../annotation)、[API配置](../api)三篇文档。除了外围驱动方式上的差异，Dubbo的配置读取总体上遵循了以下几个原则：
-
-1. Dubbo 支持了多层级的配置，并按预定优先级自动实现配置间的覆盖，最终所有配置汇总到数据总线URL后驱动后续的服务暴露、引用等流程。
-2. ApplicationConfig、ServiceConfig、ReferenceConfig
可以被理解成配置来源的一种，是直接面向用户编程的配置采集方式。
-3. 配置格式以 Properties 为主，在配置内容上遵循约定的 `path-based` 的命名[规范](#配置格式)
-
-
-
-## 配置来源
-
-首先，从Dubbo支持的配置来源说起，默认有四种配置来源：
-
-- JVM System Properties，-D 参数
-- Externalized Configuration，外部化配置
-- ServiceConfig、ReferenceConfig 等编程接口采集的配置
-- 本地配置文件 dubbo.properties
-
-### 覆盖关系
-
-下图展示了配置覆盖关系的优先级，从上到下优先级依次降低：
-
-
-
-点此查看[外部化配置详情](../config-center)
-
-
-## 配置格式
-
-目前Dubbo支持的所有配置都是`.properties`格式的，包括`-D`、`Externalized
Configuration`等，`.properties`中的所有配置项遵循一种`path-based`的配置格式：
-
-```properties
-# 应用级别
-dubbo.{config-type}[.{config-id}].{config-item}={config-item-value}
-# 服务级别
-dubbo.service.{interface-name}[.{method-name}].{config-item}={config-item-value}
-dubbo.reference.{interface-name}[.{method-name}].{config-item}={config-item-value}
-# 多配置项
-dubbo.{config-type}s.{config-id}.{config-item}={config-item-value}
-```
-
-应用级别
-
-```properties
-dubbo.application.name=demo-provider
-dubbo.registry.address=zookeeper://127.0.0.1:2181
-dubbo.protocol.port=-1
-```
-
-服务级别
-
-```properties
-dubbo.service.org.apache.dubbo.samples.api.DemoService.timeout=5000
-dubbo.reference.org.apache.dubbo.samples.api.DemoService.timeout=6000
-dubbo.reference.org.apache.dubbo.samples.api.DemoService.sayHello.timeout=7000
-```
-
-多配置项
-
-```properties
-dubbo.registries.unit1.address=zookeeper://127.0.0.1:2181
-dubbo.registries.unit2.address=zookeeper://127.0.0.1:2182
-
-dubbo.protocols.dubbo.name=dubbo
-dubbo.protocols.dubbo.port=20880
-dubbo.protocols.hessian.name=hessian
-dubbo.protocols.hessian.port=8089
-```
-
-扩展配置
-
-```properties
-dubbo.application.parameters.item1=value1
-dubbo.application.parameters.item2=value2
-dubbo.registry.parameters.item3=value3
-dubbo.reference.org.apache.dubbo.samples.api.DemoService.parameters.item4=value4
-```
-
-## 几种编程配置方式
-
-接下来，我们看一下选择不同的开发方式时，对应到 ServiceConfig、ReferenceConfig 等编程接口采集的配置的变化。
-
-#### Spring XML
-
->
参见[示例](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-basic)
-
-```xml
- <!-- dubbo-provier.xml -->
-
- <dubbo:application name="demo-provider"/>
- <dubbo:config-center address="zookeeper://127.0.0.1:2181"/>
-
- <dubbo:registry address="zookeeper://127.0.0.1:2181" simplified="true"/>
- <dubbo:metadata-report address="redis://127.0.0.1:6379"/>
- <dubbo:protocol name="dubbo" port="20880"/>
-
- <bean id="demoService"
class="org.apache.dubbo.samples.basic.impl.DemoServiceImpl"/>
- <dubbo:service interface="org.apache.dubbo.samples.basic.api.DemoService"
ref="demoService"/>
- ```
-
-#### Spring Annotation
-
->
参见[示例](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-annotation)
-
-```java
- // AnnotationService服务实现
-
- @Service
- public class AnnotationServiceImpl implements AnnotationService {
- @Override
- public String sayHello(String name) {
- System.out.println("async provider received: " + name);
- return "annotation: hello, " + name;
- }
- }
- ```
-
-```properties
- ## dubbo.properties
-
- dubbo.application.name=annotation-provider
- dubbo.registry.address=zookeeper://127.0.0.1:2181
- dubbo.protocol.name=dubbo
- dubbo.protocol.port=20880
-```
-
-#### Spring Boot
-
->
参见[示例](https://github.com/apache/dubbo-spring-boot-project/tree/master/dubbo-spring-boot-samples)
-
-```properties
- ## application.properties
-
- # Spring boot application
- spring.application.name=dubbo-externalized-configuration-provider-sample
-
- # Base packages to scan Dubbo Component:
@com.alibaba.dubbo.config.annotation.Service
- dubbo.scan.base-packages=com.alibaba.boot.dubbo.demo.provider.service
-
- # Dubbo Application
- ## The default value of dubbo.application.name is ${spring.application.name}
- ## dubbo.application.name=${spring.application.name}
-
- # Dubbo Protocol
- dubbo.protocol.name=dubbo
- dubbo.protocol.port=12345
-
- ## Dubbo Registry
- dubbo.registry.address=N/A
-
- ## DemoService version
- demo.service.version=1.0.0
-```
-
-#### API
-
-> 参考[示例](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-api)
-
-```java
-public static void main(String[] args) throws IOException {
- ServiceConfig<GreetingsService> service = new ServiceConfig<>();
- service.setApplication(new ApplicationConfig("first-dubbo-provider"));
- service.setRegistry(new RegistryConfig("multicast://224.5.6.7:1234"));
- service.setInterface(GreetingsService.class);
- service.setRef(new GreetingsServiceImpl());
- service.export();
- System.out.println("first-dubbo-provider is running.");
- System.in.read();
-}
-```
-
diff --git a/content/zh/docs/references/configuration/environment-variables.md
b/content/zh/docs/references/configuration/environment-variables.md
index dbc0201..b98714a 100644
--- a/content/zh/docs/references/configuration/environment-variables.md
+++ b/content/zh/docs/references/configuration/environment-variables.md
@@ -2,7 +2,7 @@
type: docs
title: "自动加载环境变量"
linkTitle: "自动加载环境变量"
-weight: 2
+weight: 70
description: "在 Dubbo 中自动加载环境变量"
---
diff --git a/content/zh/docs/references/configuration/config-center.md
b/content/zh/docs/references/configuration/external-config.md
similarity index 63%
rename from content/zh/docs/references/configuration/config-center.md
rename to content/zh/docs/references/configuration/external-config.md
index df387cb..09c586a 100644
--- a/content/zh/docs/references/configuration/config-center.md
+++ b/content/zh/docs/references/configuration/external-config.md
@@ -1,38 +1,12 @@
---
type: docs
-title: "动态配置中心"
-linkTitle: "动态配置中心"
-weight: 2
-description: "Dubbo 2.7 中的动态配置中心"
+title: "外部化配置"
+linkTitle: "外部化配置"
+weight: 60
+description: "将Dubbo应用的配置放到外部集中管理"
---
-配置中心（v2.7.0）在 Dubbo 中承担两个职责：
-
-1. 外部化配置。启动配置的集中式存储 （简单理解为 dubbo.properties 的外部化存储）。
-2. 服务治理。服务治理规则的存储与通知。
-
-启用动态配置，以 Zookeeper 为例，可查看 [动态配置配置项详解](../../references/xml/dubbo-config-center)
-
-```xml
-<dubbo:config-center address="zookeeper://127.0.0.1:2181"/>
-```
-
-或者
-
-```properties
-dubbo.config-center.address=zookeeper://127.0.0.1:2181
-```
-
-或者
-
-```java
-ConfigCenterConfig configCenter = new ConfigCenterConfig();
-configCenter.setAddress("zookeeper://127.0.0.1:2181");
-```
-
-> 为了兼容 2.6.x 版本配置，在使用 Zookeeper 作为注册中心，且没有显示配置配置中心的情况下，Dubbo 框架会默认将此 Zookeeper
用作配置中心，但将只作服务治理用途。
-
-## 外部化配置
+### 外部化配置
外部化配置目的之一是实现配置的集中式管理，这部分业界已经有很多成熟的专业配置系统如 Apollo, Nacos 等，Dubbo
所做的主要是保证能配合这些系统正常工作。
@@ -53,16 +27,32 @@ dubbo.application.qos.port=33333
- 优先级
- 外部化配置默认较本地配置有更高的优先级，因此这里配置的内容会覆盖本地配置值，关于
[各配置形式间的覆盖关系](../configuration-load-process) 有单独一章说明，你也可通过以下选项调整配置中心的优先级：
-
- ```properties
- -Ddubbo.config-center.highest-priority=false
- ```
+ 外部化配置默认较本地配置有更高的优先级，因此这里配置的内容会覆盖本地配置值，关于 各配置形式间的[覆盖关系](../overview#覆盖关系)
有单独一章说明。
- 作用域
-
外部化配置有全局和应用两个级别，全局配置是所有应用共享的，应用级配置是由每个应用自己维护且只对自身可见的。当前已支持的扩展实现有Zookeeper、Apollo、Nacos。
+
外部化配置有全局和应用两个级别，全局配置是所有应用共享的，应用级配置是由每个应用自己维护且只对自身可见的。当前已支持的扩展实现有Zookeeper、Apollo、Nacos。
+
+### 配置中心
+
+从配置中心读取外部化配置，可以按照下面的方法指定配置中心：
+
+```xml
+<dubbo:config-center address="zookeeper://127.0.0.1:2181"/>
+```
+
+或者
+
+```properties
+dubbo.config-center.address=zookeeper://127.0.0.1:2181
+```
+
+或者
+```java
+ConfigCenterConfig configCenter = new ConfigCenterConfig();
+configCenter.setAddress("zookeeper://127.0.0.1:2181");
+```
#### Zookeeper
@@ -120,7 +110,7 @@ Nacos虽然也存在命名空间 - namespace 的概念，但在 namespace 之下
-#### 自己加载外部化配置
+### 自己加载外部化配置
所谓 Dubbo 对配置中心的支持，本质上就是把 `.properties` 从远程拉取到本地，然后和本地的配置做一次融合。理论上只要 Dubbo
框架能拿到需要的配置就可以正常的启动，它并不关心这些配置是自己加载到的还是应用直接塞给它的，所以Dubbo还提供了以下API，让用户将自己组织好的配置塞给
Dubbo 框架（配置加载的过程是用户要完成的），这样 Dubbo 框架就不再直接和 Apollo 或 Zookeeper 做读取配置交互。
@@ -134,45 +124,3 @@ dubboConfigurations.put("dubbo.registry.simplified",
"true");
ConfigCenterConfig configCenter = new ConfigCenterConfig();
configCenter.setExternalConfig(dubboConfigurations);
```
-
-
-## 服务治理
-
-#### Zookeeper
-
-默认节点结构：
-
-
-
-- namespace，用于不同配置的环境隔离。
-- config，Dubbo 约定的固定节点，不可更改，所有配置和服务治理规则都存储在此节点下。
-- dubbo，所有服务治理规则都是全局性的，dubbo 为默认节点
-- configurators/tag-router/condition-router/migration，不同的服务治理规则类型，node value
存储具体规则内容
-
-#### Apollo
-
-所有的服务治理规则都是全局性的，默认从公共命名空间 `dubbo` 读取和订阅：
-
-
-
-不同的规则以不同的 key 后缀区分：
-
-- configurators，[覆盖规则](../../examples/config-rule)
-- tag-router，[标签路由](../../examples/routing-rule)
-- condition-router，[条件路由](../../examples/condition-router)
-- migration, [迁移规则](../../examples/todo)
-
-#### Nacos
-
-所有的服务治理规则都是全局的，默认从 namespace: `public` 下进行读取， 通过 dataId: `interface name` 以及
group: `dubbo` 去读取和订阅：
-
-
-
-不同的规则以 dataId 的后缀区分：
-
-- configurators，[覆盖规则](../../examples/config-rule)
-- tag-router，[标签路由](../../examples/routing-rule)
-- condition-router，[条件路由](../../examples/condition-router)
-- migration, [迁移规则](../../examples/todo)
-
-
diff --git a/content/zh/docs/references/configuration/overview.md
b/content/zh/docs/references/configuration/overview.md
new file mode 100644
index 0000000..2cf7f0f
--- /dev/null
+++ b/content/zh/docs/references/configuration/overview.md
@@ -0,0 +1,178 @@
+---
+type: docs
+title: "配置概述"
+linkTitle: "概述"
+weight: 10
+description: "Dubbo配置介绍"
+---
+
+本文主要介绍Dubbo配置概况，包括配置组件、配置来源、配置方式及配置加载流程。
+
+## 配置组件
+
+Dubbo框架的配置项比较繁多，为了更好地管理各种配置，将其按照用途划分为不同的组件，最终所有配置项都会汇聚到URL中，传递给后续处理模块。
+
+常用配置组件如下：
+- application: Dubbo应用配置
+- registry: 注册中心
+- protocol: 服务提供者RPC协议
+- config-center: 配置中心
+- metadata-report: 元数据中心
+- service: 服务提供者配置
+- reference: 远程服务引用配置
+- provider: service的默认配置或分组配置
+- consumer: reference的默认配置或分组配置
+- module: 模块配置
+- monitor: 监控配置
+- metrics: 指标配置
+- ssl: SSL/TLS配置
+
+
+## 配置来源
+
+从Dubbo支持的配置来源说起，默认有6种配置来源：
+
+- JVM System Properties，JVM -D 参数
+- System environment，JVM进程的环境变量
+- Externalized Configuration，外部化配置，从配置中心读取
+- Application Configuration，应用的属性配置，从Spring应用的Environment中提取"dubbo"打头的属性集
+- API / XML /注解等编程接口采集的配置可以被理解成配置来源的一种，是直接面向用户编程的配置采集方式
+- 从classpath读取配置文件 dubbo.properties
+
+### 覆盖关系
+
+下图展示了配置覆盖关系的优先级，从上到下优先级依次降低：
+
+
+
+请参考相关内容：[属性覆盖](../properties#属性覆盖)。
+
+## 配置方式
+
+按照驱动方式可以分为以下四种方式：
+
+### API配置
+以Java编码的方式组织配置，包括Raw API和Bootstrap API，具体请参考[API配置](../api)。
+
+### XML配置
+以XML方式配置各种组件，支持与Spring无缝集成，具体请参考[XML配置](../xml)。
+
+### Annotation配置
+以注解方式暴露服务和引用服务接口，支持与Spring无缝集成，具体请参考[Annotation配置](../annotation)。
+
+### 属性配置
+根据属性Key-value生成配置组件，类似SpringBoot的ConfigurationProperties，具体请参考[属性配置](../properties)。
+
+属性配置的另外一个重要的功能特性是[属性覆盖](../properties#属性覆盖)，使用外部属性的值覆盖已创建的配置组件属性。
+
+如果要将属性配置放到外部的配置中心，请参考[外部化配置](../external-config)。
+
+除了外围驱动方式上的差异，Dubbo的配置读取总体上遵循了以下几个原则：
+
+1. Dubbo 支持了多层级的配置，并按预定优先级自动实现配置间的覆盖，最终所有配置汇总到数据总线URL后驱动后续的服务暴露、引用等流程。
+2. 配置格式以 Properties 为主，在配置内容上遵循约定的 `path-based` 的[命名规范](../properties#配置格式)
+
+
+## 配置加载流程
+
+
+
+从上图可以看出，配置加载大概分为两个阶段：
+
+* 第一阶段为DubboBootstrap初始化之前，在Spring context启动时解析处理XML配置/注解配置/Java-config
或者是执行API配置代码，创建config bean并且加入到ConfigManager中。
+*
第二阶段为DubboBootstrap初始化过程，从配置中心读取外部配置，依次处理实例级属性配置和应用级属性配置，最后刷新所有配置实例的属性，也就是[属性覆盖](../properties#属性覆盖)。
+
+
+## 几种编程配置方式
+
+接下来，我们看一下选择不同的开发方式时，对应到 ServiceConfig、ReferenceConfig 等编程接口采集的配置的变化。
+
+#### Spring XML
+
+>
参见[示例](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-basic)
+
+```xml
+ <!-- dubbo-provier.xml -->
+
+ <dubbo:application name="demo-provider"/>
+ <dubbo:config-center address="zookeeper://127.0.0.1:2181"/>
+
+ <dubbo:registry address="zookeeper://127.0.0.1:2181" simplified="true"/>
+ <dubbo:metadata-report address="redis://127.0.0.1:6379"/>
+ <dubbo:protocol name="dubbo" port="20880"/>
+
+ <bean id="demoService"
class="org.apache.dubbo.samples.basic.impl.DemoServiceImpl"/>
+ <dubbo:service interface="org.apache.dubbo.samples.basic.api.DemoService"
ref="demoService"/>
+```
+
+#### Spring Annotation
+
+>
参见[示例](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-annotation)
+
+```java
+ // AnnotationService服务实现
+
+ @Service
+ public class AnnotationServiceImpl implements AnnotationService {
+ @Override
+ public String sayHello(String name) {
+ System.out.println("async provider received: " + name);
+ return "annotation: hello, " + name;
+ }
+ }
+```
+
+```properties
+ ## dubbo.properties
+
+dubbo.application.name=annotation-provider
+dubbo.registry.address=zookeeper://127.0.0.1:2181
+dubbo.protocol.name=dubbo
+dubbo.protocol.port=20880
+```
+
+#### Spring Boot
+
+>
参见[示例](https://github.com/apache/dubbo-spring-boot-project/tree/master/dubbo-spring-boot-samples)
+
+```properties
+ ## application.properties
+
+# Spring boot application
+spring.application.name=dubbo-externalized-configuration-provider-sample
+
+# Base packages to scan Dubbo Component:
@com.alibaba.dubbo.config.annotation.Service
+dubbo.scan.base-packages=com.alibaba.boot.dubbo.demo.provider.service
+
+# Dubbo Application
+## The default value of dubbo.application.name is ${spring.application.name}
+## dubbo.application.name=${spring.application.name}
+
+# Dubbo Protocol
+dubbo.protocol.name=dubbo
+dubbo.protocol.port=12345
+
+## Dubbo Registry
+dubbo.registry.address=N/A
+
+## DemoService version
+demo.service.version=1.0.0
+```
+
+#### API
+
+> 参考[示例](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-api)
+
+```java
+public static void main(String[] args) throws IOException {
+ ServiceConfig<GreetingsService> service = new ServiceConfig<>();
+ service.setApplication(new ApplicationConfig("first-dubbo-provider"));
+ service.setRegistry(new RegistryConfig("multicast://224.5.6.7:1234"));
+ service.setInterface(GreetingsService.class);
+ service.setRef(new GreetingsServiceImpl());
+ service.export();
+ System.out.println("first-dubbo-provider is running.");
+ System.in.read();
+ }
+```
+
diff --git a/content/zh/docs/references/configuration/properties.md
b/content/zh/docs/references/configuration/properties.md
index 1d5da56..1607ff9 100644
--- a/content/zh/docs/references/configuration/properties.md
+++ b/content/zh/docs/references/configuration/properties.md
@@ -2,43 +2,260 @@
type: docs
title: "属性配置"
linkTitle: "属性配置"
-weight: 2
+weight: 50
description: "以属性配置的方式来配置你的 Dubbo 应用"
---
-如果你的应用足够简单，例如，不需要多注册中心或多协议，并且需要在spring容器中共享配置，那么，我们可以直接使用 `dubbo.properties`
作为默认配置。
+Dubbo属性配置有两个职责：
-Dubbo 可以自动加载 classpath 根目录下的 dubbo.properties，但是你同样可以使用 JVM
参数来指定路径：`-Ddubbo.properties.file=xxx.properties`。
+1. 定义配置：根据属性创建配置组件实例，类似SpringBoot的`@ConfigurationProperties`的作用。
+2. 属性覆盖：覆盖已存在的配置组件实例的属性值，类似Spring `PropertyOverrideConfigurer` 的作用。
-# 映射规则
+
+> 一个属性配置的例子
[dubbo-spring-boot-samples](https://github.com/apache/dubbo-spring-boot-project/tree/master/dubbo-spring-boot-samples)
+
+```properties
+ ## application.properties
+
+ # Spring boot application
+ spring.application.name=dubbo-externalized-configuration-provider-sample
+
+ # Base packages to scan Dubbo Component:
@com.alibaba.dubbo.config.annotation.Service
+ dubbo.scan.base-packages=com.alibaba.boot.dubbo.demo.provider.service
+
+ # Dubbo Application
+ ## The default value of dubbo.application.name is ${spring.application.name}
+ ## dubbo.application.name=${spring.application.name}
+
+ # Dubbo Protocol
+ dubbo.protocol.name=dubbo
+ dubbo.protocol.port=12345
+
+ ## Dubbo Registry
+ dubbo.registry.address=N/A
+
+ ## service default version
+ dubbo.provider.version=1.0.0
+```
+
+## 配置来源
+
+从Dubbo支持的配置来源说起，默认有6种配置来源：
+
+- JVM System Properties，JVM -D 参数
+- System environment，JVM进程的环境变量
+- Externalized Configuration，外部化配置，从配置中心读取
+- Application Configuration，应用的属性配置，从Spring应用的Environment中提取"dubbo"打头的属性集
+- API / XML /注解等编程接口采集的配置可以被理解成配置来源的一种，是直接面向用户编程的配置采集方式
+- 从classpath读取配置文件 dubbo.properties
+
+关于dubbo.properties属性：
+
+1. 如果在 classpath 下有超过一个 dubbo.properties 文件，比如，两个 jar 包都各自包含了
dubbo.properties，dubbo 将随机选择一个加载，并且打印错误日志。
+2. Dubbo 可以自动加载 classpath 根目录下的 dubbo.properties，但是你同样可以使用 JVM
参数来指定路径：`-Ddubbo.properties.file=xxx.properties`。
+
+### 覆盖关系
+
+下图展示了配置覆盖关系的优先级，从上到下优先级依次降低：
+
+
+
+请参考相关内容：[属性覆盖](../properties#属性覆盖)。
+
+## 处理流程
+
+属性配置处理流程请查看 [配置加载流程](../overview#配置加载流程)。
+
+
+## 配置格式
+
+目前Dubbo支持的所有配置都是`.properties`格式的，包括`-D`、`Externalized
Configuration`等，`.properties`中的所有配置项遵循一种`path-based`的配置格式。
+
+在Spring应用中也可以将属性配置放到`application.yml`中，其树层次结构的方式可读性更好一些。
+
+```properties
+# 应用级配置（无id）
+dubbo.{config-type}.{config-item}={config-item-value}
+
+# 实例级配置（指定id或name）
+dubbo.{config-type}s.{config-id}.{config-item}={config-item-value}
+dubbo.{config-type}s.{config-name}.{config-item}={config-item-value}
+
+# 服务接口配置
+dubbo.service.{interface-name}.{config-item}={config-item-value}
+dubbo.reference.{interface-name}.{config-item}={config-item-value}
+
+# 方法配置
+dubbo.service.{interface-name}.{method-name}.{config-item}={config-item-value}
+dubbo.reference.{interface-name}.{method-name}.{config-item}={config-item-value}
+
+# 方法argument配置
+dubbo.reference.{interface-name}.{method-name}.{argument-index}.{config-item}={config-item-value}
+
+```
+
+### 应用级配置（无id）
+
+应用级配置的格式为：配置类型单数前缀，无id/name。
+```properties
+# 应用级配置（无id）
+dubbo.{config-type}.{config-item}={config-item-value}
+```
+
+* 如果该类型的配置不存在任何实例时，则将使用应用级配置的属性创建默认实例。
+*
如果该类型的配置存在一个或多个实例，且没有找到配置实例对应的配置时，则将应用级配置的属性用于属性覆盖。详细请参考[属性覆盖](../properties#属性覆盖)。
+
+```properties
+dubbo.application.name=demo-provider
+dubbo.application.qos-enable=false
+
+dubbo.registry.address=zookeeper://127.0.0.1:2181
+
+dubbo.protocol.name=dubbo
+dubbo.protocol.port=-1
+```
+
+### 实例级配置（指定id或name）
+
+针对某个实例的属性配置需要指定id或者name，其前缀格式为：配置类型复数前缀 + id/name。
+
+```properties
+# 实例级配置（指定id或name）
+dubbo.{config-type}s.{config-id}.{config-item}={config-item-value}
+dubbo.{config-type}s.{config-name}.{config-item}={config-item-value}
+
+```
+
+* 如果不存在该id或者name的实例，则根据属性创建配置组件实例。
+* 如果已存在相同id或name的实例，则提取该前缀的属性集合用于属性覆盖。详细请参考[属性覆盖](../properties#属性覆盖)。
+* 具体的配置复数形式请参考[单复数配置对照表](../properties#单复数配置对照表)
+
+```properties
+dubbo.registries.unit1.address=zookeeper://127.0.0.1:2181
+dubbo.registries.unit2.address=zookeeper://127.0.0.1:2182
+
+dubbo.protocols.dubbo.name=dubbo
+dubbo.protocols.dubbo.port=20880
+
+dubbo.protocols.hessian.name=hessian
+dubbo.protocols.hessian.port=8089
+```
+
+### 服务接口配置
+
+```properties
+dubbo.service.org.apache.dubbo.samples.api.DemoService.timeout=5000
+dubbo.reference.org.apache.dubbo.samples.api.DemoService.timeout=6000
+```
+
+### 方法配置
+
+方法配置格式:
+
+```properties
+# 方法配置
+dubbo.service.{interface-name}.{method-name}.{config-item}={config-item-value}
+dubbo.reference.{interface-name}.{method-name}.{config-item}={config-item-value}
+
+# 方法argument配置
+dubbo.reference.{interface-name}.{method-name}.{argument-index}.{config-item}={config-item-value}
+```
+
+方法配置示例：
+```properties
+dubbo.reference.org.apache.dubbo.samples.api.DemoService.sayHello.timeout=7000
+dubbo.reference.org.apache.dubbo.samples.api.DemoService.sayHello.oninvoke=notifyService.onInvoke
+dubbo.reference.org.apache.dubbo.samples.api.DemoService.sayHello.onreturn=notifyService.onReturn
+dubbo.reference.org.apache.dubbo.samples.api.DemoService.sayHello.onthrow=notifyService.onThrow
+dubbo.reference.org.apache.dubbo.samples.api.DemoService.sayHello.0.callback=true
+```
+
+等价于XML配置：
+
+```xml
+<dubbo:reference interface="org.apache.dubbo.samples.api.DemoService" >
+ <dubbo:method name="sayHello" timeout="7000"
oninvoke="notifyService.onInvoke"
+ onreturn="notifyService.onReturn"
onthrow="notifyService.onThrow">
+ <dubbo:argument index="0" callback="true" />
+ </dubbo:method>
+</dubbo:reference>
+```
+
+### 参数配置
+
+parameters参数为map对象，支持xxx.parameters.key=value方式进行配置。
+```properties
+dubbo.application.parameters.item1=value1
+dubbo.application.parameters.item2=value2
+dubbo.registry.parameters.item3=value3
+dubbo.reference.org.apache.dubbo.samples.api.DemoService.parameters.item4=value4
+```
+
+### 属性与XML配置映射规则
可以将 xml 的 tag 名和属性名组合起来，用 ‘.’ 分隔。每行一个属性。
-* `dubbo.application.name=foo` 相当于 `<dubbo:application name="foo" />`
-* `dubbo.registry.address=10.20.153.10:9090` 相当于 `<dubbo:registry
address="10.20.153.10:9090" /> `
+* `dubbo.application.name=foo` 相当于 `<dubbo:application name="foo" />`
+* `dubbo.registry.address=10.20.153.10:9090` 相当于 `<dubbo:registry
address="10.20.153.10:9090" /> `
+
+如果在 xml 配置中有超过一个的 tag，那么你可以使用 ‘id’ 进行区分。如果你不指定id，它将作用于所有 tag。
-如果在 xml 配置中有超过一个的 tag，那么你可以使用 ‘id’ 进行区分。如果你不指定 id，它将作用于所有 tag。
+* `dubbo.protocols.rmi.port=1099` 相当于 `<dubbo:protocol id="rmi" name="rmi"
port="1099" /> `
+* `dubbo.registries.china.address=10.20.153.10:9090` 相当于 `<dubbo:registry
id="china" address="10.20.153.10:9090" />`
-* `dubbo.protocol.rmi.port=1099` 相当于 `<dubbo:protocol id="rmi" name="rmi"
port="1099" /> `
-* `dubbo.registry.china.address=10.20.153.10:9090` 相当于 `<dubbo:registry
id="china" address="10.20.153.10:9090" />`
-如下，是一个典型的 dubbo.properties 配置样例。
+## 属性覆盖
+
+属性覆盖是指用配置的属性值覆盖config bean实例的属性，类似Spring
[PropertyOverrideConfigurer](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/beans/factory/config/PropertyOverrideConfigurer.html)
的作用。
+
+> Property resource configurer that overrides bean property values in an
application context definition. It pushes values from a properties file into
bean definitions.
+Configuration lines are expected to be of the following form:
+>
+> beanName.property=value
+
+但与`PropertyOverrideConfigurer`的不同之处是，Dubbo的属性覆盖有多个匹配格式，优先级从高到低依次是：
```properties
-dubbo.application.name=foo
-dubbo.application.owner=bar
-dubbo.registry.address=10.20.153.10:9090
+#1. 指定id的实例级配置
+dubbo.{config-type}s.{config-id}.{config-item}={config-item-value}
+
+#2. 指定name的实例级配置
+dubbo.{config-type}s.{config-name}.{config-item}={config-item-value}
+
+#3. 应用级配置（单数配置）
+dubbo.{config-type}.{config-item}={config-item-value}
```
-## 重写与优先级
+属性覆盖处理流程：
-
+按照优先级从高到低依次查找，如果找到此前缀开头的属性，则选定使用这个前缀提取属性，忽略后面的配置。
-优先级从高到低：
+
-* JVM -D 参数：当你部署或者启动应用时，它可以轻易地重写配置，比如，改变 dubbo 协议端口；
-* XML：XML 中的当前配置会重写 dubbo.properties 中的；
-* Properties：默认配置，仅仅作用于以上两者没有配置时。
-1. 如果在 classpath 下有超过一个 dubbo.properties 文件，比如，两个 jar 包都各自包含了
dubbo.properties，dubbo 将随机选择一个加载，并且打印错误日志。
-2. 如果 `id` 没有在 `protocol` 中配置，将使用 `name` 作为默认属性。
+## 单复数配置对照表
+
+复数配置的命名与普通单词变复数的规则相同：
+
+1. 字母y结尾时，去掉y，改为ies
+2. 字母s结尾时，加es
+3. 其它加s
+
+| Config Type | 单数配置
| 复数配置 |
+| --------------------------------- |
------------------------------------------------------------ |
----------------------------------- |
+| application | dubbo.application.xxx=xxx
| dubbo.applications.{id}.xxx=xxx <br/>
dubbo.applications.{name}.xxx=xxx |
+| protocol | dubbo.protocol.xxx=xxx
| dubbo.protocols.{id}.xxx=xxx <br/>
dubbo.protocols.{name}.xxx=xxx |
+| module | dubbo.module.xxx=xxx
| dubbo.modules.{id}.xxx=xxx <br/>
dubbo.modules.{name}.xxx=xxx |
+| registry | dubbo.registry.xxx=xxx
| dubbo.registries.{id}.xxx=xxx |
+| monitor | dubbo.monitor.xxx=xxx
| dubbo.monitors.{id}.xxx=xxx |
+| config-center | dubbo.config-center.xxx=xxx
| dubbo.config-centers.{id}.xxx=xxx |
+| metadata-report | dubbo.metadata-report.xxx=xxx
| dubbo.metadata-reports.{id}.xxx=xxx |
+| ssl | dubbo.ssl.xxx=xxx
| dubbo.ssls.{id}.xxx=xxx |
+| metrics | dubbo.metrics.xxx=xxx
| dubbo.metricses.{id}.xxx=xxx |
+| provider | dubbo.provider.xxx=xxx
| dubbo.providers.{id}.xxx=xxx |
+| consumer | dubbo.consumer.xxx=xxx
| dubbo.consumers.{id}.xxx=xxx |
+| service | dubbo.service.{interfaceName}.xxx=xxx
| 无 |
+| reference | dubbo.reference.{interfaceName}.xxx=xxx
| 无 |
+| method |
dubbo.service.{interfaceName}.{methodName}.xxx=xxx <br/>
dubbo.reference.{interfaceName}.{methodName}.xxx=xxx | 无
|
+| argument |
dubbo.service.{interfaceName}.{methodName}.{arg-index}.xxx=xxx | 无
|
+
diff --git a/content/zh/docs/references/configuration/xml.md
b/content/zh/docs/references/configuration/xml.md
index e2bbbe8..4a43149 100644
--- a/content/zh/docs/references/configuration/xml.md
+++ b/content/zh/docs/references/configuration/xml.md
@@ -2,11 +2,11 @@
type: docs
title: "XML 配置"
linkTitle: "XML 配置"
-weight: 1
+weight: 30
description: "以 XML 配置的方式来配置你的 Dubbo 应用"
---
-有关 XML 的详细配置项，请参见：[配置参考手册](../../references/xml)。如果不想使用 Spring 配置，而希望通过 API
的方式进行调用，请参见：[API配置](../api)。想知道如何使用配置，请参见：[快速启动](../../quick-start)。
+有关 XML 的详细配置项，请参见：[XML配置参考手册](../../../references/xml)。如果不想使用 Spring 配置，而希望通过
API 的方式进行调用，请参见：[API配置](../api)。想知道如何使用配置，请参见：[快速启动](../../quick-start)。
请在此查看文档描述的[完整示例](https://github.com/apache/dubbo-samples/tree/master/java/dubbo-samples-basic)
@@ -61,7 +61,7 @@ description: "以 XML 配置的方式来配置你的 Dubbo 应用"
```
## 配置之间的关系
-
+
标签 | 用途 | 解释
diff --git a/static/imgs/v3/config/config-load.svg
b/static/imgs/v3/config/config-load.svg
new file mode 100644
index 0000000..6caebcc
--- /dev/null
+++ b/static/imgs/v3/config/config-load.svg
@@ -0,0 +1 @@
+<svg id="SvgjsSvg1006" width="606.4375" height="820"
xmlns="http://www.w3.org/2000/svg"; version="1.1"
xmlns:xlink="http://www.w3.org/1999/xlink";
xmlns:svgjs="http://svgjs.com/svgjs";><defs id="SvgjsDefs1007"><marker
id="SvgjsMarker1060" markerWidth="16" markerHeight="12" refX="16" refY="6"
viewBox="0 0 16 12" orient="auto" markerUnits="userSpaceOnUse"
stroke-dasharray="0,0"><path id="SvgjsPath1061" d="M0,2 L14,6 L0,11 L0,2"
fill="#323232" stroke="#323232" stroke-width="2"></path></marker> [...]
\ No newline at end of file
diff --git a/static/imgs/v3/config/properties-override.svg
b/static/imgs/v3/config/properties-override.svg
new file mode 100644
index 0000000..99f7584
--- /dev/null
+++ b/static/imgs/v3/config/properties-override.svg
@@ -0,0 +1 @@
+<svg id="SvgjsSvg1178" width="457" height="775.5"
xmlns="http://www.w3.org/2000/svg"; version="1.1"
xmlns:xlink="http://www.w3.org/1999/xlink";
xmlns:svgjs="http://svgjs.com/svgjs";><defs id="SvgjsDefs1179"><marker
id="SvgjsMarker1210" markerWidth="16" markerHeight="12" refX="16" refY="6"
viewBox="0 0 16 12" orient="auto" markerUnits="userSpaceOnUse"
stroke-dasharray="0,0"><path id="SvgjsPath1211" d="M0,2 L14,6 L0,11 L0,2"
fill="#323232" stroke="#323232" stroke-width="2"></path></marker><ma [...]
\ No newline at end of file
