[SCB-1175] refactor the instructions for the configuration mechanism
diff --git a/java-chassis-reference/en_US/SUMMARY.md b/java-chassis-reference/en_US/SUMMARY.md
index c1cad40..8ec9234 100644
--- a/java-chassis-reference/en_US/SUMMARY.md
+++ b/java-chassis-reference/en_US/SUMMARY.md
@@ -44,7 +44,6 @@
* [HTTP2](transports/http2.md)
* [General Development](catalog/general-develop.md)
* [Access Service Center](general-development/visit-sc.md)
- * [Using Dynamic Configuration](general-development/config.md)
* [Metrics](general-development/metrics.md)
* [Microservice invocation chain](general-development/microservice-invocation-chain.md)
* [Customized-Tracing](general-development/customized-tracing.md)
@@ -66,6 +65,8 @@
* [Handling exceptions](general-development/error-handling.md)
* [Multi-environment isolation between microservice instances](general-development/multienvironment.md)
* [Thread Model](general-development/thread-model.md)
+* [Configuration](catalog/config.md)
+ * [General config](config/general-config.md)
* [Service Capability Open](edge/open-service.md)
* [Using Edge Service](edge/by-servicecomb-sdk.md)
* [Using confd and Nginx as edge services](edge/nginx.md)
diff --git a/java-chassis-reference/en_US/catalog/config.md b/java-chassis-reference/en_US/catalog/config.md
new file mode 100644
index 0000000..4fb5af5
--- /dev/null
+++ b/java-chassis-reference/en_US/catalog/config.md
@@ -0,0 +1,2 @@
+## General configuration instructions
+Introduce the configuration hierarchy relationship and the usage of the configuration mechanism of ServiceComb-Java-Chassis.
diff --git a/java-chassis-reference/en_US/catalog/general-develop.md b/java-chassis-reference/en_US/catalog/general-develop.md
index ed109dd..2ce54fa 100644
--- a/java-chassis-reference/en_US/catalog/general-develop.md
+++ b/java-chassis-reference/en_US/catalog/general-develop.md
@@ -1,14 +1,6 @@
## Access Service Center
The system realizes the discovery between services through the service center. During the service startup process, the service center is registered. When calling other services, the service center will query the instance information of other services, such as the access address, the protocol used, and other parameters. The service center supports the use of PULL and PUSH modes to notify instance changes.
-
-## Using dynamic configuration
-ServiceComb provides a hierarchical configuration mechanism. According to the priority, it is divided into:
-• Configuration Center (dynamic configuration)
-• Java System Property (-D parameter)
-• Environmental variables
-• Configuration file, microservice.yaml. The microservice.yaml file is scanned from the classpath and can be allowed to exist in many copies. Specify the priority by servicecomb-config-order.
-
## Application Performance Monitoring
1. The introduction of Metrics
2. The summary of statistical items
@@ -35,11 +27,11 @@
In some scenarios, the service uses http instead of https as the network transmission channel. In order to prevent the falsification or tampering request, the signature function of the http code stream between the consumer and the producer needs to be provided.
-## File Upload
+## File Upload
File upload, currently supported in vertx rest channel and servlet rest.
File uploads use the standard http form format, which interfaces directly with the browser's upload.
-## Download Document
+## Download Document
File downloads are currently available in the vertx rest channel and servlet rest.
@@ -78,4 +70,4 @@
## Obtaining the fuse and instance isolation alarm event information
-When the microservice is running or the instance isolation status changes, you need to listen to related events, get relevant information and process it.
\ No newline at end of file
+When the microservice is running or the instance isolation status changes, you need to listen to related events, get relevant information and process it.
diff --git a/java-chassis-reference/en_US/config/general-config.md b/java-chassis-reference/en_US/config/general-config.md
new file mode 100644
index 0000000..c75ae3a
--- /dev/null
+++ b/java-chassis-reference/en_US/config/general-config.md
@@ -0,0 +1,77 @@
+# General configuration instructions
+
+## Configuration source hierarchical relationship
+
+ServiceComb provides a hierarchical configuration mechanism. According to the priority, it is divided as below(the former is higher):
+* Configuration Center (dynamic configuration)
+* Java System Property (-D parameter)
+* Environmental variables
+* Configuration file
+
+### Configuration file
+
+The configuration file is the microservice.yaml file on classpath by default. When the ServiceComb-Java-Chassis is booting up, the microservice.yaml files are loaded from the jar files and the directories on the hard disks. All of the configuration files are merged into a set of valid configurations. The configuration files on the hard disks has higher priority than those in the jar files. The priority can also be specified by the `servicecomb-config-order` item in the configuration files.
+
+> Tips: Since the microservice.yaml file on the hard disk has a higher priority, the `.` directory can be added into the classpath of the executable jar package, so that a microservice.yaml file can be placed in the directory where the service jar package is located, to overwrite the configuration files in the jar package.
+
+The default name of the configuration files is "microservice.yaml". The additional configuration files can be added by specifying Java System Property, and the name of the configuration files can be changed in this way, too:
+
+|Java System Property Variable Name|Description|
+|---|---|
+|servicecomb.configurationSource.additionalUrls|List of configuration files, multiple full file names can be specified with the ',' as separator|
+|servicecomb.configurationSource.defaultFileName|Default configuration file name|
+
+### Environmental variables
+
+On Linux, the `.` charactor cannot be contained into environment variable name. As a result, some configuration items cannot be specified into environment variables directly. As a solution, the `.` charactor can be replaced by `_`, and the converted configuration item can be specified as environment variable. ServiceComb-Java-Chassis can map those converted configuration items to the original configuration items.
+
+For example, for the configration in microservice.yaml file:
+```yaml
+servicecomb:
+ rest:
+ address: 0.0.0.0:8080
+```
+We can specify `servicecomb_rest_address=0.0.0.0:9090` in the environment variable to overwrite the server port as 9090. This mapping mechanism can also applied to other configuration levels.
+
+###Configuration Center (dynamic configuration)
+
+The default implementation of the dynamic configuration is the config-cc client, which is connected to the configuration center. The configuration items are as follows:
+
+|Variable|Description|
+|---|---|
+|servicecomb.config.client.refreshMode|Application configuration refresh mode, `0` is config-center active push, `1` is client cycle pull, default is `0`|
+|servicecomb.config.client.refreshPort|config-center push configured port|
+|servicecomb.config.client.tenantName|Application tenant name|
+|servicecomb.config.client.serverUri|config-center access address, the format is `http(s)://{ip}:{port}`, to separate multiple addresses with comma (optional, when cse.config.client.regUri is configured as This configuration item will take effect when empty))|
+|servicecomb.config.client.refresh_interval|the configuration refresh interval, the unit is millisecond, default value is 30000|
+
+## Get configuration information in the program
+
+Developers use a consistent API to get the configuration, regardless of the configured storage path:
+```java
+DynamicDoubleProperty myprop = DynamicPropertyFactory.getInstance().getDoubleProperty("trace.handler.sampler.percent", 0.1);
+```
+The instance above shows a configuration item whose key is `trace.handler.sampler.percent`, with default value 0.1. Developers can specify the value of this item in the microservice.yaml file, environment variable, Java System Property or Configuration center. **There is no need for the developers to consider where to get the configuration values, Java-Chassis will load the configurations from everywhere, and merge them into one set of configurations according to the priority rule mentioned above.**
+
+For details, please refer to [API DOC] (https://netflix.github.io/archaius/archaius-core-javadoc/com/netflix/config/DynamicPropertyFactory.html)
+
+You can register for a callback to handle configuration changes:
+```java
+ myprop.addCallback(new Runnable() {
+ public void run() {
+ // this method is invoked when the value of this configuration item is modified
+ System.out.println("trace.handler.sampler.percent is changed!");
+ }
+ });
+```
+
+## Performing configuration item mapping
+In some cases, we want to block the configuration of some of the open source components we use and provide our users with their own configuration items. In this case, you can define the mapping through config.yaml under the classpath:
+```
+registry:
+ client:
+ serviceUrl:
+ defaultZone: eureka.client.serviceUrl.defaultZone
+```
+
+After the mapping is defined, the framework maps by default when the configuration is loaded, and the configuration items defined by us are mapped to the configuration items that the open source component can recognize.
diff --git a/java-chassis-reference/en_US/general-development/config.md b/java-chassis-reference/en_US/general-development/config.md
deleted file mode 100755
index d925904..0000000
--- a/java-chassis-reference/en_US/general-development/config.md
+++ /dev/null
@@ -1,53 +0,0 @@
-# Using dynamic configuration
-
-ServiceComb provides a hierarchical configuration mechanism. According to the priority, it is divided into:
-* Configuration Center (dynamic configuration)
-* Java System Property (-D parameter)
-* Environmental variables
-* Configuration file, microservice.yaml. The microservice.yaml file is scanned from the classpath and can be allowed to exist in many copies. Specify the priority by servicecomb-config-order.
-
-The configuration file defaults to microservice.yaml under the classpath, but can be passed to other files through environment variables. The environment variables that can be set are:
-
-|Variable|Description|
-|---|---|
-|servicecomb.configurationSource.additionalUrls|List of configuration files, separated by multiple full file names containing specific locations |
-|servicecomb.configurationSource.defaultFileName|Default configuration file name|
-
-The default implementation of the dynamic configuration is the config-cc client, which is connected to the configuration center. The configuration items are as follows:
-
-|Variable|Description|
-|---|---|
-|servicecomb.config.client.refreshMode|Application configuration refresh mode, 0 is config-center active push, 1 is client cycle pull, default is 0|
-|servicecomb.config.client.refreshPort|config-center push configured port|
-|servicecomb.config.client.tenantName|Application tenant name|
-|servicecomb.config.client.serverUri|config-center access address, http(s)://{ip}:{port}, to separate multiple addresses (optional, when cse.config.client.regUri is configured as This configuration item will take effect when empty))|
-
-## Get configuration information in the program
-
-Developers use a consistent API to get the configuration, regardless of the configured storage path:
-```
-DynamicDoubleProperty myprop = DynamicPropertyFactory.getInstance().getDoubleProperty("trace.handler.sampler.percent", 0.1);
-```
-
-For details, please refer to [API DOC] (https://netflix.github.io/archaius/archaius-core-javadoc/com/netflix/config/DynamicPropertyFactory.html)
-
-## Handling configuration changes
-You can register for a callback to handle configuration changes:
-```
- myprop.addCallback(new Runnable() {
- public void run() {
- // Handle configuration changes
- }
- });
-```
-
-## Performing configuration item mapping
-In some cases, we want to block the configuration of some of the open source components we use and provide our users with their own configuration items. In this case, you can define the mapping through config.yaml under the classpath:
-```
-registry:
- client:
- serviceUrl:
- defaultZone: eureka.client.serviceUrl.defaultZone
-```
-
-After the mapping is defined, the framework maps by default when the configuration is loaded, and the configuration items defined by us are mapped to the configuration items that the open source component can recognize.
diff --git a/java-chassis-reference/zh_CN/SUMMARY.md b/java-chassis-reference/zh_CN/SUMMARY.md
index 13aebd8..6890f24 100644
--- a/java-chassis-reference/zh_CN/SUMMARY.md
+++ b/java-chassis-reference/zh_CN/SUMMARY.md
@@ -44,7 +44,6 @@
* [HTTP2](transports/http2.md)
* [通用开发](catalog/general-develop.md)
* [访问服务中心](general-development/visit-sc.md)
- * [使用动态配置](general-development/config.md)
* [应用性能监控](general-development/metrics.md)
* [微服务调用链](general-development/microservice-invocation-chain.md)
* [自定义调用链打点](general-development/customized-tracing.md)
@@ -66,6 +65,8 @@
* [异常处理](general-development/error-handling.md)
* [微服务实例间多环境隔离](general-development/multienvironment.md)
* [线程模型](general-development/thread-model.md)
+* [配置](catalog/config.md)
+ * [通用配置说明](config/general-config.md)
* [服务能力开放](edge/open-service.md)
* [使用Edge Service做边缘服务](edge/by-servicecomb-sdk.md)
* [使用confd和Nginx做边缘服务](edge/nginx.md)
diff --git a/java-chassis-reference/zh_CN/catalog/config.md b/java-chassis-reference/zh_CN/catalog/config.md
new file mode 100644
index 0000000..247d86b
--- /dev/null
+++ b/java-chassis-reference/zh_CN/catalog/config.md
@@ -0,0 +1,2 @@
+## 通用配置说明
+说明ServiceComb-Java-Chassis的配置项层级关系、配置读取方法。
diff --git a/java-chassis-reference/zh_CN/catalog/general-develop.md b/java-chassis-reference/zh_CN/catalog/general-develop.md
index 4c95230..8044bc0 100644
--- a/java-chassis-reference/zh_CN/catalog/general-develop.md
+++ b/java-chassis-reference/zh_CN/catalog/general-develop.md
@@ -2,13 +2,6 @@
系统通过服务中心实现服务之间的发现。服务启动过程中，会向服务中心进行注册。在调用其他服务的时候，会从服务中心查询其他服务的实例信息，比如访问地址、使用的协议以及其他参数。服务中心支持使用PULL和PUSH两种模式通知实例变化。
-## 使用动态配置
-ServiceComb提供了分层次的配置机制。按照优先级，分为：
-• 配置中心（动态配置）
-• Java System Property（-D参数）
-• 环境变量
-• 配置文件，microservice.yaml。microservice.yaml文件从classpath扫描，可以允许存在很多份。通过servicecomb-config-order指定优先级。
-
## 应用性能监控
一、Metrics介绍
二、统计项汇总
@@ -26,15 +19,15 @@
## 自定义调用链打点
分布式调用链追踪提供了服务间调用的时序信息，但服务内部的链路调用信息对开发者同样重要，如果能将两者合二为一，就能提供更完整的调用链，更容易定位错误和潜在性能问题。
-
+
## 本地开发和测试
本小节介绍如何在开发者本地进行消费者/提供者应用的开发调试。开发服务提供者请参考3 开发服务提供者章节，开发服务消费者请参考4 开发服务消费者。服务提供者和消费提供者均需要连接到在远程的服务中心，为了本地微服务的开发和调试，本小节介绍了两种搭建本地服务中心的方法进行本地微服务调试：
-## Http Filter
+## Http Filter
某些场景中，业务使用http而不是https，作为网络传输通道，此时为了防止被伪造或篡改请求，需要提供consumer、producer之间对http码流的签名功能。
-
+
## 文件上传
文件上传，当前支持在vertx rest通道和servlet rest中使用。
文件上传使用标准的http form格式，可与浏览器的上传直接对接。
diff --git a/java-chassis-reference/zh_CN/config/general-config.md b/java-chassis-reference/zh_CN/config/general-config.md
new file mode 100644
index 0000000..5be60ae
--- /dev/null
+++ b/java-chassis-reference/zh_CN/config/general-config.md
@@ -0,0 +1,77 @@
+# 通用配置说明
+
+## 配置源层级
+
+ServiceComb提供了分层次的配置机制。按照优先级从高到低，分为：
+* 配置中心（动态配置）
+* Java System Property（-D参数）
+* 环境变量
+* 配置文件
+
+### 配置文件
+
+配置文件默认是classpath下的microservice.yaml文件。ServiceComb-Java-Chassis启动时会从classpath的各个jar包、磁盘目录中加载microservice.yaml文件，并将这些文件合并为一份microservice.yaml配置。位于磁盘上的microservice.yaml文件优先级高于jar包中的microservice.yaml文件，用户还可以通过在配置文件中指定`servicecomb-config-order`来指定优先级。
+
+> Tips：由于磁盘上的microservice.yaml文件优先级较高，我们可以在打包时在服务可执行jar包的classpath里加上`.`目录，这样就可以在服务jar包所在的目录里放置一份microservice.yaml来覆盖jar包内的配置文件。
+
+默认的配置文件名为microservice.yaml，但是我们可以通过设置Java System Property来增加其他的配置文件，或修改默认的配置文件名：
+
+|Java System Property变量名|描述|
+|---|---|
+|servicecomb.configurationSource.additionalUrls|配置文件的列表，以`,`分隔的多个包含具体位置的完整文件名|
+|servicecomb.configurationSource.defaultFileName|默认配置文件名|
+
+### 环境变量
+
+Linux的环境变量名不允许带`.`符号，因此某些配置项无法直接配置在环境变量里。可以将配置项key的`.`符号改为下划线`_`，将转换后的配置项配在环境变量里，ServiceComb-Java-Chassis可以自动将环境变量匹配到原配置项上。
+
+例如：对于microservice.yaml中配置的
+```yaml
+servicecomb:
+ rest:
+ address: 0.0.0.0:8080
+```
+可以在环境变量中设置`servicecomb_rest_address=0.0.0.0:9090`来将服务监听的端口覆写为9090。这种下划线转点号的机制也适用于其他的配置层级。
+
+### 配置中心（动态配置）
+
+动态配置的默认实现是config-cc客户端，对接配置中心，配置项如下：
+
+|配置项名|描述|
+|---|---|
+|servicecomb.config.client.refreshMode|应用配置的刷新方式，`0`为config-center主动push，`1`为client周期pull，默认为`0`|
+|servicecomb.config.client.refreshPort|config-center推送配置的端口|
+|servicecomb.config.client.tenantName|应用的租户名称|
+|servicecomb.config.client.serverUri|config-center访问地址，格式为`http(s)://{ip}:{port}`，以`,`分隔多个地址(可选，当`cse.config.client.regUri`配置为空时该配置项才会生效)|
+|servicecomb.config.client.refresh_interval|pull模式下刷新配置项的时间间隔，单位为毫秒，默认值为30000|
+
+## 在程序中读取配置信息
+
+Java-Chassis支持使用一致的API获取配置，不必关注配置的来源位置：
+```java
+DynamicDoubleProperty myprop = DynamicPropertyFactory.getInstance().getDoubleProperty("trace.handler.sampler.percent", 0.1);
+```
+以上例子表示声明了一个key为`trace.handler.sampler.percent`的动态配置对象，默认值为`0.1`。用户可以选择在microservice.yaml文件、环境变量、Java System Property或配置中心里配置`trace.handler.sampler.percent`来修改配置项的值。**用户不需要关注从哪里读取配置项的值，Java-Chassis会自动从各处读取配置，并按照上文的优先级顺序进行合并以保证用户取到的是优先级最高的配置值。**
+
+关于配置项API的具体方法可参考[API DOC](https://netflix.github.io/archaius/archaius-core-javadoc/com/netflix/config/DynamicPropertyFactory.html)。
+
+开发者可以注册callback处理配置变更：
+```java
+ myprop.addCallback(new Runnable() {
+ public void run() {
+ // 当配置项的值变化时，该回调方法会被调用
+ System.out.println("trace.handler.sampler.percent is changed!");
+ }
+ });
+```
+
+## 进行配置项映射
+有些情况下，我们要屏蔽我们使用的一些开源组件的配置并给用户提供我们自己的配置项。在这种情况下，可以通过classpath下的config.yaml进行映射定义：
+```yaml
+registry:
+ client:
+ serviceUrl:
+ defaultZone: eureka.client.serviceUrl.defaultZone
+```
+
+定义映射后，在配置装载的时候框架会默认进行映射，把我们定义的配置项映射为开源组件可以认的配置项。
diff --git a/java-chassis-reference/zh_CN/general-development/config.md b/java-chassis-reference/zh_CN/general-development/config.md
deleted file mode 100644
index 279297f..0000000
--- a/java-chassis-reference/zh_CN/general-development/config.md
+++ /dev/null
@@ -1,53 +0,0 @@
-# 使用动态配置
-
-ServiceComb提供了分层次的配置机制。按照优先级，分为：
-* 配置中心（动态配置）
-* Java System Property（-D参数）
-* 环境变量
-* 配置文件，microservice.yaml。microservice.yaml文件从classpath扫描，可以允许存在很多份。通过servicecomb-config-order指定优先级。
-
-配置文件默认是classpath下的microservice.yaml, 但是可以通过环境变量传入其他文件，可以设置的环境变量为：
-
-|变量|描述|
-|---|---|
-|servicecomb.configurationSource.additionalUrls|配置文件的列表，以,分隔的多个包含具体位置的完整文件名|
-|servicecomb.configurationSource.defaultFileName|默认配置文件名|
-
-动态配置的默认实现是config-cc客户端，对接配置中心，配置项如下：
-
-|变量|描述|
-|---|---|
-|servicecomb.config.client.refreshMode|应用配置的刷新方式，0为config-center主动push，1为client周期pull，默认为0|
-|servicecomb.config.client.refreshPort|config-center推送配置的端口|
-|servicecomb.config.client.tenantName|应用的租户名称|
-|servicecomb.config.client.serverUri|config-center访问地址，http(s)://{ip}:{port}，以,分隔多个地址(可选，当cse.config.client.regUri配置为空时该配置项才会生效)|
-
-## 在程序中获取配置信息
-
-开发者使用一致的API获取配置，不区分配置的存储路径：
-```
-DynamicDoubleProperty myprop = DynamicPropertyFactory.getInstance().getDoubleProperty("trace.handler.sampler.percent", 0.1);
-```
-
-具体方法可参考[API DOC](https://netflix.github.io/archaius/archaius-core-javadoc/com/netflix/config/DynamicPropertyFactory.html)
-
-## 处理配置变更
-可以注册callback处理配置变更：
-```
- myprop.addCallback(new Runnable() {
- public void run() {
- // Handle configuration changes
- }
- });
-```
-
-## 进行配置项映射
-有些情况下，我们要屏蔽我们使用的一些开源组件的配置并给用户提供我们自己的配置项。在这种情况下，可以通过classpath下的config.yaml进行映射定义：
-```
-registry:
- client:
- serviceUrl:
- defaultZone: eureka.client.serviceUrl.defaultZone
-```
-
-定义映射后，在配置装载的时候框架会默认进行映射，把以我们定义的配置项映射为开源组件可以认的配置项。
