misc change

d82086b2 · Jason Song · 3f3c4edc · d82086b2 · d82086b2 · d82086b2
14 changed file
--- a/apollo-adminservice/src/main/resources/application-nacosDiscovery.properties
+++ b/apollo-adminservice/src/main/resources/application-nacosDiscovery.properties
--- a/apollo-portal/src/main/java/com/ctrip/framework/apollo/portal/component/ConfigReleaseWebhookNotifier.java
+++ b/apollo-portal/src/main/java/com/ctrip/framework/apollo/portal/component/ConfigReleaseWebhookNotifier.java
@@ -50,7 +50,7 @@ public class ConfigReleaseWebhookNotifier {
      try {
        restTemplate.postForObject(url, entity, String.class, env);
      } catch (Exception e) {
-        logger.error("Notify webHook server failed. webHook server url:{}", env, url, e);
+        logger.error("Notify webHook server failed, env: {}, webHook server url:{}", env, url, e);
      }
    }
  }

--- a/docs/zh/README.md
+++ b/docs/zh/README.md
@@ -77,7 +77,7 @@ Java客户端不依赖任何框架，能够运行于所有Java运行时环境，
  - [Apollo配置中心设计](zh/design/apollo-design.md)
  - [Apollo配置中心介绍](zh/design/apollo-introduction.md)
  - [Apollo核心概念之“Namespace”](zh/design/apollo-core-concept-namespace.md)
-  * [Apollo源码解析](http://www.iocoder.cn/categories/Apollo/)（据说Apollo非常适合作为初学者第一个通读源码学习的分布式中间件产品）
+  - [Apollo源码解析](http://www.iocoder.cn/categories/Apollo/)（据说Apollo非常适合作为初学者第一个通读源码学习的分布式中间件产品）

 # Development
  - [Apollo开发指南](zh/development/apollo-development-guide.md)
@@ -85,7 +85,8 @@ Java客户端不依赖任何框架，能够运行于所有Java运行时环境，
    - [Eclipse Code Style](https://github.com/ctripcorp/apollo/blob/master/apollo-buildtools/style/eclipse-java-google-style.xml)
    - [Intellij Code Style](https://github.com/ctripcorp/apollo/blob/master/apollo-buildtools/style/intellij-java-google-style.xml)
  - [Portal实现用户登录功能](zh/development/portal-how-to-implement-user-login-function.md)
-  - [邮件模板样例](zh/development/email-template-samples.md)
+  - [Portal接入邮件服务](zh/development/portal-how-to-enable-email-service.md)
+  - [Portal启用webhook通知](zh/development/portal-how-to-enable-webhook-notification.md)

 # Deployment
  - [Quick Start](zh/deployment/quick-start.md)

--- a/docs/zh/_sidebar.md
+++ b/docs/zh/_sidebar.md
@@ -17,7 +17,8 @@
    - [Eclipse Code Style](https://github.com/ctripcorp/apollo/blob/master/apollo-buildtools/style/eclipse-java-google-style.xml)
    - [Intellij Code Style](https://github.com/ctripcorp/apollo/blob/master/apollo-buildtools/style/intellij-java-google-style.xml)
  - [Portal实现用户登录功能](zh/development/portal-how-to-implement-user-login-function.md)
-  - [邮件模板样例](zh/development/email-template-samples.md)
+  - [Portal接入邮件服务](zh/development/portal-how-to-enable-email-service.md)
+  - [Portal启用webhook通知](zh/development/portal-how-to-enable-webhook-notification.md)

 - 使用文档
  - [Apollo使用指南](zh/usage/apollo-user-guide.md)

--- a/docs/zh/deployment/distributed-deployment-guide.md
+++ b/docs/zh/deployment/distributed-deployment-guide.md
--- a/docs/zh/design/apollo-design.md
+++ b/docs/zh/design/apollo-design.md
@@ -274,7 +274,7 @@ Spring从3.1版本开始增加了`ConfigurableEnvironment`和`PropertySource`：
 <tr>
 <td>数据库宕机</td>
 <td>客户端无影响，Portal无法更新配置</td>
-<td>Config Service开启<a href="/#/zh/deployment/distributed-deployment-guide?id=_3-config-servicecacheenabled-是否开启配置缓存">配置缓存</a>后，对配置的读取不受数据库宕机影响</td>
+<td>Config Service开启<a href="/#/zh/deployment/distributed-deployment-guide?id=_323-config-servicecacheenabled-是否开启配置缓存">配置缓存</a>后，对配置的读取不受数据库宕机影响</td>
 <td></td>
 </tr>
 </tbody>

--- a/docs/zh/development/apollo-development-guide.md
+++ b/docs/zh/development/apollo-development-guide.md
@@ -236,29 +236,6 @@ Apollo客户端针对不同的环境会从不同的服务器获取配置，所

 请参考[Portal 实现用户登录功能](zh/development/portal-how-to-implement-user-login-function)

-## 3.2 Portal接入邮件服务
-
-在配置发布时候，我们希望发布信息邮件通知到相关的负责人。现支持发送邮件的动作有：普通发布、灰度发布、全量发布、回滚，通知对象包括：具有namespace编辑和发布权限的人员以及App负责人。
-和SSO类似，每个公司也有自己的邮件服务实现，所以我们相应的定义了[EmailService](https://github.com/ctripcorp/apollo/blob/master/apollo-portal/src/main/java/com/ctrip/framework/apollo/portal/spi/EmailService.java)接口，现有两个实现类：
-1. CtripEmailService：携程实现的EmailService
-2. DefaultEmailService：空实现
-
-### 3.2.1 接入步骤
-1. 提供自己公司的[EmailService](https://github.com/ctripcorp/apollo/blob/master/apollo-portal/src/main/java/com/ctrip/framework/apollo/portal/spi/EmailService.java)实现，并在[EmailConfiguration](https://github.com/ctripcorp/apollo/blob/master/apollo-portal/src/main/java/com/ctrip/framework/apollo/portal/spi/configuration/EmailConfiguration.java)中注册。
-2. 构建邮件内容需要在PortalDB，serverconfig表内配置一些参数，如下：
-  * **apollo.portal.address** Apollo Portal的地址。方便用户从邮件点击跳转到Apollo Portal查看详细的发布信息。
-  * **email.supported.envs** 支持发送邮件的环境列表，英文逗号隔开。我们不希望发布邮件变成用户的垃圾邮件，只有某些环境下的发布动作才会发送邮件。
-  * **email.sender** 邮件的发送人。
-  * **email.template.framework** 邮件内容模板框架。将邮件内容模板化、可配置化，方便管理和变更邮件内容。
-  * **email.template.release.module.diff** 发布邮件的diff模块。
-  * **email.template.rollback.module.diff** 回滚邮件的diff模块。
-  * **email.template.release.module.rules** 灰度发布的灰度规则模块。
-   我们提供了以上[邮件模板样例](zh/development/email-template-samples)，方便大家使用。
-
->注：运行时使用不同的实现是通过[Profiles](http://docs.spring.io/autorepo/docs/spring-boot/current/reference/html/boot-features-profiles.html)实现的，比如你自己的Email实现是在`custom` profile中的话，在打包脚本中可以指定-Dapollo_profile=github,custom。其中`github`是Apollo必须的一个profile，用于数据库的配置，`custom`是你自己实现的profile。同时需要注意在[EmailConfiguration](https://github.com/ctripcorp/apollo/blob/master/apollo-portal/src/main/java/com/ctrip/framework/apollo/portal/spi/configuration/EmailConfiguration.java)中修改默认实现的条件`@Profile({"!custom"})`。
-
-### 3.2.2 相关代码
-1. [ConfigPublishListener](https://github.com/ctripcorp/apollo/blob/master/apollo-portal/src/main/java/com/ctrip/framework/apollo/portal/listener/ConfigPublishListener.java)监听发布事件，调用emailbuilder构建邮件内容，然后调用EmailService发送邮件
-2. [emailbuilder](https://github.com/ctripcorp/apollo/blob/master/apollo-portal/src/main/java/com/ctrip/framework/apollo/portal/components/emailbuilder)包是构建邮件内容的实现
-3. [EmailService](https://github.com/ctripcorp/apollo/blob/master/apollo-portal/src/main/java/com/ctrip/framework/apollo/portal/spi/EmailService.java) 邮件发送服务
-4. [EmailConfiguration](https://github.com/ctripcorp/apollo/blob/master/apollo-portal/src/main/java/com/ctrip/framework/apollo/portal/spi/configuration/EmailConfiguration.java) 邮件服务注册类
+## 3.2 Portal 接入邮件服务
+
+请参考[Portal 接入邮件服务](zh/development/portal-how-to-enable-email-service)
--- a/docs/zh/development/email-template-samples.md
+++ b/docs/zh/development/email-template-samples.md
-在配置发布时候，可以发布信息邮件通知到相关的负责人，具体接入方式请参考[Apollo开发指南-3.2 Portal接入邮件服务](zh/development/apollo-development-guide#_32-portal接入邮件服务)。
+在配置发布时候，我们希望发布信息邮件通知到相关的负责人。现支持发送邮件的动作有：普通发布、灰度发布、全量发布、回滚，通知对象包括：具有namespace编辑和发布权限的人员以及App负责人。

+由于各公司的邮件服务往往有不同的实现，所以Apollo定义了一些SPI用来解耦，Apollo接入邮件服务的关键就是实现这些SPI。
+
+## 一、实现方式一：使用Apollo提供的smtp邮件服务
+
+### 1.1 接入步骤
+在ApolloPortalDB.ServerConfig表配置以下参数，也可以通过管理员工具 - 系统参数页面进行配置，修改完一分钟实时生效。如下：
+* **email.enabled** 设置为true即可启用默认的smtp邮件服务 
+* **email.config.host** smtp的服务地址，如`smtp.163.com`
+* **email.config.user** smtp帐号用户名
+* **email.config.password** smtp帐号密码
+* **email.supported.envs** 支持发送邮件的环境列表，英文逗号隔开。我们不希望发布邮件变成用户的垃圾邮件，只有某些环境下的发布动作才会发送邮件。
+* **email.sender** 邮件的发送人，可以不配置，默认为`email.config.user`。
+* **apollo.portal.address** Apollo Portal的地址。方便用户从邮件点击跳转到Apollo Portal查看详细的发布信息。
+* **email.template.framework** 邮件内容模板框架。将邮件内容模板化、可配置化，方便管理和变更邮件内容。
+* **email.template.release.module.diff** 发布邮件的diff模块。
+* **email.template.rollback.module.diff** 回滚邮件的diff模块。
+* **email.template.release.module.rules** 灰度发布的灰度规则模块。
+
+我们提供了[邮件模板样例](#三、邮件模板样例)，方便大家使用。
+
+## 二、实现方式二：接入公司的统一邮件服务
+
+和SSO类似，每个公司也有自己的邮件服务实现，所以我们相应的定义了[EmailService](https://github.com/ctripcorp/apollo/blob/master/apollo-portal/src/main/java/com/ctrip/framework/apollo/portal/spi/EmailService.java)接口，现有两个实现类：
+1. CtripEmailService：携程实现的EmailService
+2. DefaultEmailService：smtp实现
+
+### 2.1 接入步骤
+1. 提供自己公司的[EmailService](https://github.com/ctripcorp/apollo/blob/master/apollo-portal/src/main/java/com/ctrip/framework/apollo/portal/spi/EmailService.java)实现，并在[EmailConfiguration](https://github.com/ctripcorp/apollo/blob/master/apollo-portal/src/main/java/com/ctrip/framework/apollo/portal/spi/configuration/EmailConfiguration.java)中注册。
+2. 在ApolloPortalDB.ServerConfig表配置以下参数，也可以通过管理员工具 - 系统参数页面进行配置，修改完一分钟实时生效。如下：
+* **email.supported.envs** 支持发送邮件的环境列表，英文逗号隔开。我们不希望发布邮件变成用户的垃圾邮件，只有某些环境下的发布动作才会发送邮件。
+* **email.sender** 邮件的发送人。
+* **apollo.portal.address** Apollo Portal的地址。方便用户从邮件点击跳转到Apollo Portal查看详细的发布信息。
+* **email.template.framework** 邮件内容模板框架。将邮件内容模板化、可配置化，方便管理和变更邮件内容。
+* **email.template.release.module.diff** 发布邮件的diff模块。
+* **email.template.rollback.module.diff** 回滚邮件的diff模块。
+* **email.template.release.module.rules** 灰度发布的灰度规则模块。
+  
+我们提供了[邮件模板样例](#三、邮件模板样例)，方便大家使用。
+
+>注：运行时使用不同的实现是通过[Profiles](http://docs.spring.io/autorepo/docs/spring-boot/current/reference/html/boot-features-profiles.html)实现的，比如你自己的Email实现是在`custom` profile中的话，在打包脚本中可以指定-Dapollo_profile=github,custom。其中`github`是Apollo必须的一个profile，用于数据库的配置，`custom`是你自己实现的profile。同时需要注意在[EmailConfiguration](https://github.com/ctripcorp/apollo/blob/master/apollo-portal/src/main/java/com/ctrip/framework/apollo/portal/spi/configuration/EmailConfiguration.java)中修改默认实现的条件`@Profile({"!custom"})`。
+
+### 2.2 相关代码
+1. [ConfigPublishListener](https://github.com/ctripcorp/apollo/blob/master/apollo-portal/src/main/java/com/ctrip/framework/apollo/portal/listener/ConfigPublishListener.java)监听发布事件，调用emailbuilder构建邮件内容，然后调用EmailService发送邮件
+2. [emailbuilder](https://github.com/ctripcorp/apollo/blob/master/apollo-portal/src/main/java/com/ctrip/framework/apollo/portal/components/emailbuilder)包是构建邮件内容的实现
+3. [EmailService](https://github.com/ctripcorp/apollo/blob/master/apollo-portal/src/main/java/com/ctrip/framework/apollo/portal/spi/EmailService.java) 邮件发送服务
+4. [EmailConfiguration](https://github.com/ctripcorp/apollo/blob/master/apollo-portal/src/main/java/com/ctrip/framework/apollo/portal/spi/configuration/EmailConfiguration.java) 邮件服务注册类
+
+## 三、邮件模板样例
 以下为发布邮件和回滚邮件的模板内容样式，邮件模板为html格式，发送html格式的邮件时，可能需要做一些额外的处理，取决于每个公司的邮件服务实现。为了减少字符数，模板经过了压缩处理，可自行格式化提高可读性。

-## email.template.framework
+### 3.1 email.template.framework

 ```html
 <html><head><style type="text/css">.table{width:100%;max-width:100%;margin-bottom:20px;border-collapse:collapse;background-color:transparent}td{padding:8px;line-height:1.42857143;vertical-align:top;border:1px solid #ddd;border-top:1px solid #ddd}.table-bordered{border:1px solid #ddd}</style></head><body><h3>发布基本信息</h3><table class="table table-bordered"><tr><td width="10%"><b>AppId</b></td><td width="15%">#{appId}</td><td width="10%"><b>环境</b></td><td width="15%">#{env}</td><td width="10%"><b>集群</b></td><td width="15%">#{clusterName}</td><td width="10%"><b>Namespace</b></td><td width="15%">#{namespaceName}</td></tr><tr><td><b>发布者</b></td><td>#{operator}</td><td><b>发布时间</b></td><td>#{releaseTime}</td><td><b>发布标题</b></td><td>#{releaseTitle}</td><td><b>备注</b></td><td>#{releaseComment}</td></tr></table>#{diffModule}#{rulesModule}<br><a href="#{apollo.portal.address}/config/history.html?#/appid=#{appId}&env=#{env}&clusterName=#{clusterName}&namespaceName=#{namespaceName}&releaseHistoryId=#{releaseHistoryId}">点击查看详细的发布信息</a><br><br>如有Apollo使用问题请先查阅<a href="http://conf.ctripcorp.com/display/FRAM/Apollo">文档</a>，或直接回复本邮件咨询。</body></html>
@@ -10,7 +58,7 @@

 > 注：使用此模板需要在 portal 的系统参数中配置 apollo.portal.address，指向 apollo portal 的地址

-## email.template.release.module.diff
+### 3.2 email.template.release.module.diff

 ```html
 <h3>变更的配置</h3>
@@ -25,7 +73,7 @@
 </table>
 ```

-## email.template.rollback.module.diff
+### 3.3 email.template.rollback.module.diff
 ```html
 <div>
    <br><br>
@@ -43,7 +91,7 @@
 </div>
 ```

-## email.template.release.module.rules
+### 3.4 email.template.release.module.rules
 ```html
 <div>
    <br>
@@ -53,8 +101,8 @@
 </div>
 ```

-## 发布邮件样例
+### 3.5 发布邮件样例
 ![发布邮件模板](https://raw.githubusercontent.com/ctripcorp/apollo/master/doc/images/email-template-release.png)

-## 回滚邮件样例
+### 3.6 回滚邮件样例
 ![回滚邮件模板](https://raw.githubusercontent.com/ctripcorp/apollo/master/doc/images/email-template-rollback.png)
\ No newline at end of file
--- a/docs/zh/development/portal-how-to-enable-webhook-notification.md
+++ b/docs/zh/development/portal-how-to-enable-webhook-notification.md
+从 1.8.0 版本开始，apollo 增加了 webhook 支持，从而可以在配置发布时触发 webhook 并告知配置发布的信息。
+
+## 启用方式
+
+> 配置项统一存储在ApolloPortalDB.ServerConfig表中，也可以通过`管理员工具 - 系统参数`页面进行配置，修改完一分钟实时生效。
+
+1. webhook.supported.envs
+
+开启 webhook 的环境列表，多个环境以英文逗号分隔，如
+
+```
+DEV,FAT,UAT,PRO
+```
+
+2. config.release.webhook.service.url
+
+webhook 通知的 url 地址，需要接收 HTTP POST 请求。如有多个地址，以英文逗号分隔，如
+
+```
+http://www.xxx.com/webhook1,http://www.xxx.com/webhook2
+```
+
+## Webhook 接入方式
+
+1. URL 参数
+
+参数名 | 参数说明
+--- | ---
+env | 该次配置发布所在的环境
+
+2. Request body sample
+
+```json
+{
+    "appId": "",  // appId
+    "clusterName": "",  // 集群
+    "namespaceName": "", // namespace
+    "operator": "",  // 发布人
+    "releaseId": 2,  // releaseId
+    "releaseTitle": "",  // releaseTitle 
+    "releaseComment": "",  // releaseComment
+    "releaseTime": "",  // 发布时间  eg：2020-01-01T00:00:00.000+0800
+    "configuration": [ { // 发布后的全部配置，如果为灰度发布，则为灰度发布后的全部配置
+        "firstEntity": "",  // 配置的key
+        "secondEntity": ""  // 配置的value
+    } ],
+    "isReleaseAbandoned": false,
+    "previousReleaseId": 1,  // 上一次正式发布的releaseId
+    "operation":  // 0-正常发布 1-配置回滚 2-灰度发布 4-全量发布
+    "operationContext": {  // 操作设置的属性配置
+        "isEmergencyPublish": true/false,  // 是否紧急发布
+        "rules": [ {  // 灰度规则
+            "clientAppId": "",   // appId
+            "clientIpList": [ "10.0.0.2", "10.0.0.3" ]  // IP列表
+        } ],
+        "branchReleaseKeys": [ "", "" ]  // 灰度发布的key
+    }
+}
+```
\ No newline at end of file
--- a/docs/zh/development/portal-how-to-implement-user-login-function.md
+++ b/docs/zh/development/portal-how-to-implement-user-login-function.md
@@ -319,7 +319,6 @@ spring:
          # 必须是 https, jwt 的 issuer-uri
          # 例如 你的 issuer-uri 是 https://host:port/auth/realms/apollo/.well-known/openid-configuration, 那么此处只需要配置 https://host:port/auth/realms/apollo 即可, spring boot 处理的时候会自动加上 /.well-known/openid-configuration 的后缀
          issuer-uri: https://host:port/auth/realms/apollo
-
 ```

 ### 2. 配置 `startup.sh`
@@ -334,10 +333,8 @@ LOG_DIR=/opt/logs/100003173
 SERVER_PORT=8070

 export JAVA_OPTS="$JAVA_OPTS -Dspring.profiles.active=github,oidc"
-
 ```

-
 ## 实现方式四： 接入公司的统一登录认证系统

 这种实现方式的前提是公司已经有统一的登录认证系统，最常见的比如SSO、LDAP等。接入时，实现以下SPI。其中UserService和UserInfoHolder是必须要实现的。

--- a/docs/zh/faq/common-issues-in-deployment-and-development-phase.md
+++ b/docs/zh/faq/common-issues-in-deployment-and-development-phase.md
@@ -67,10 +67,10 @@ eureka:

 1.6.0版本增加了自定义环境的功能，可以在不修改代码的情况增加环境

-1. protaldb增加环境，参考[分布式部署指南 2.1.3.1一节](zh/deployment/distributed-deployment-guide?id=_2131-调整apolloportaldb配置)
+1. protaldb增加环境，参考[3.1 调整ApolloPortalDB配置](zh/deployment/distributed-deployment-guide?id=_31-调整apolloportaldb配置)
 2. 为apollo-portal添加新增环境对应的meta server地址，具体参考：[2.2.1.1.2.4 配置apollo-portal的meta service信息](zh/deployment/distributed-deployment-guide?id=_221124-配置apollo-portal的meta-service信息)。apollo-client在新的环境下使用时也需要做好相应的配置，具体参考：[1.2.2 Apollo Meta Server](zh/usage/java-sdk-user-guide?id=_122-apollo-meta-server)。

->注1：一套Portal可以管理多个环境，但是每个环境都需要独立部署一套Config Service、Admin Service和ApolloConfigDB，具体请参考：[2.1.2 创建ApolloConfigDB](zh/deployment/distributed-deployment-guide?id=_212-创建apolloconfigdb)，[2.1.3.2 调整ApolloConfigDB配置](zh/deployment/distributed-deployment-guide?id=_2132-调整apolloconfigdb配置)，[2.2.1.1.2 配置数据库连接信息](zh/deployment/distributed-deployment-guide?id=_22112-配置数据库连接信息)
+>注1：一套Portal可以管理多个环境，但是每个环境都需要独立部署一套Config Service、Admin Service和ApolloConfigDB，具体请参考：[2.1.2 创建ApolloConfigDB](zh/deployment/distributed-deployment-guide?id=_212-创建apolloconfigdb)，[3.2 调整ApolloConfigDB配置](zh/deployment/distributed-deployment-guide?id=_32-调整apolloconfigdb配置)，[2.2.1.1.2 配置数据库连接信息](zh/deployment/distributed-deployment-guide?id=_22112-配置数据库连接信息)

 > 注2：如果是为已经运行了一段时间的Apollo配置中心增加环境，别忘了参考[2.1.2.4 从别的环境导入ApolloConfigDB的项目数据](zh/deployment/distributed-deployment-guide?id=_2124-从别的环境导入apolloconfigdb的项目数据)对新的环境做初始化

@@ -78,10 +78,10 @@ eureka:
 ##### 4.2.1 添加Apollo预先定义好的环境

 如果需要添加的环境是Apollo预先定义的环境（DEV, FAT, UAT, PRO），需要两步操作：
-1. protaldb增加环境，参考[分布式部署指南 2.1.3.1一节](zh/deployment/distributed-deployment-guide?id=_2131-调整apolloportaldb配置)
+1. protaldb增加环境，参考[3.1 调整ApolloPortalDB配置](zh/deployment/distributed-deployment-guide?id=_31-调整apolloportaldb配置)
 2. 为apollo-portal添加新增环境对应的meta server地址，具体参考：[2.2.1.1.2.4 配置apollo-portal的meta service信息](zh/deployment/distributed-deployment-guide?id=_221124-配置apollo-portal的meta-service信息)。apollo-client在新的环境下使用时也需要做好相应的配置，具体参考：[1.2.2 Apollo Meta Server](zh/usage/java-sdk-user-guide?id=_122-apollo-meta-server)。

->注1：一套Portal可以管理多个环境，但是每个环境都需要独立部署一套Config Service、Admin Service和ApolloConfigDB，具体请参考：[2.1.2 创建ApolloConfigDB](zh/deployment/distributed-deployment-guide?id=_212-创建apolloconfigdb)，[2.1.3.2 调整ApolloConfigDB配置](zh/deployment/distributed-deployment-guide?id=_2132-调整apolloconfigdb配置)，[2.2.1.1.2 配置数据库连接信息](zh/deployment/distributed-deployment-guide?id=_22112-配置数据库连接信息)
+>注1：一套Portal可以管理多个环境，但是每个环境都需要独立部署一套Config Service、Admin Service和ApolloConfigDB，具体请参考：[2.1.2 创建ApolloConfigDB](zh/deployment/distributed-deployment-guide?id=_212-创建apolloconfigdb)，[3.2 调整ApolloConfigDB配置](zh/deployment/distributed-deployment-guide?id=_32-调整apolloconfigdb配置)，[2.2.1.1.2 配置数据库连接信息](zh/deployment/distributed-deployment-guide?id=_22112-配置数据库连接信息)

 > 注2：如果是为已经运行了一段时间的Apollo配置中心增加环境，别忘了参考[2.1.2.4 从别的环境导入ApolloConfigDB的项目数据](zh/deployment/distributed-deployment-guide?id=_2124-从别的环境导入apolloconfigdb的项目数据)对新的环境做初始化

@@ -134,10 +134,10 @@ public class LegacyMetaServerProvider {
    ...
 }
 ```
-6. protaldb增加`BETA`环境，参考[分布式部署指南 2.1.3.1一节](zh/deployment/distributed-deployment-guide?id=_2131-调整apolloportaldb配置)
+6. protaldb增加`BETA`环境，参考[3.1 调整ApolloPortalDB配置](zh/deployment/distributed-deployment-guide?id=_31-调整apolloportaldb配置)
 7. 为apollo-portal添加新增环境对应的meta server地址，具体参考：[2.2.1.1.2.4 配置apollo-portal的meta service信息](zh/deployment/distributed-deployment-guide?id=_221124-配置apollo-portal的meta-service信息)。apollo-client在新的环境下使用时也需要做好相应的配置，具体参考：[1.2.2 Apollo Meta Server](zh/usage/java-sdk-user-guide?id=_122-apollo-meta-server)。

->注1：一套Portal可以管理多个环境，但是每个环境都需要独立部署一套Config Service、Admin Service和ApolloConfigDB，具体请参考：[2.1.2 创建ApolloConfigDB](zh/deployment/distributed-deployment-guide?id=_212-创建apolloconfigdb)，[2.1.3.2 调整ApolloConfigDB配置](zh/deployment/distributed-deployment-guide?id=_2132-调整apolloconfigdb配置)，[2.2.1.1.2 配置数据库连接信息](zh/deployment/distributed-deployment-guide?id=_22112-配置数据库连接信息)
+>注1：一套Portal可以管理多个环境，但是每个环境都需要独立部署一套Config Service、Admin Service和ApolloConfigDB，具体请参考：[2.1.2 创建ApolloConfigDB](zh/deployment/distributed-deployment-guide?id=_212-创建apolloconfigdb)，[3.2 调整ApolloConfigDB配置](zh/deployment/distributed-deployment-guide?id=_32-调整apolloconfigdb配置)，[2.2.1.1.2 配置数据库连接信息](zh/deployment/distributed-deployment-guide?id=_22112-配置数据库连接信息)

 > 注2：如果是为已经运行了一段时间的Apollo配置中心增加环境，别忘了参考[2.1.2.4 从别的环境导入ApolloConfigDB的项目数据](zh/deployment/distributed-deployment-guide?id=_2124-从别的环境导入apolloconfigdb的项目数据)对新的环境做初始化


--- a/docs/zh/misc/apollo-benchmark.md
+++ b/docs/zh/misc/apollo-benchmark.md
@@ -34,7 +34,7 @@ QPS: 160

 999线响应时间: 2.5ms

->注：config service开启了配置缓存，更多信息可以参考[分布式部署指南中的缓存配置](zh/deployment/distributed-deployment-guide#_3-config-servicecacheenabled-是否开启配置缓存)
+>注：config service开启了配置缓存，更多信息可以参考[分布式部署指南中的缓存配置](zh/deployment/distributed-deployment-guide#_323-config-servicecacheenabled-是否开启配置缓存)

 #### 2.2 Config Server GC情况


--- a/docs/zh/usage/apollo-user-guide.md
+++ b/docs/zh/usage/apollo-user-guide.md
@@ -449,10 +449,10 @@ Apollo从1.6.0版本开始增加访问密钥机制，从而只有经过身份验

 Apollo 支持细粒度的权限控制，请务必根据实际情况做好权限控制：
 1. [项目管理员权限](#_121-项目管理员权限)
-    * Apollo 默认允许所有登录用户创建项目，如果只允许部分用户创建项目，可以开启[创建项目权限控制](zh/deployment/distributed-deployment-guide?id=_10-rolecreate-applicationenabled-是否开启创建项目权限控制)
+    * Apollo 默认允许所有登录用户创建项目，如果只允许部分用户创建项目，可以开启[创建项目权限控制](zh/deployment/distributed-deployment-guide?id=_3110-rolecreate-applicationenabled-是否开启创建项目权限控制)
 2. [配置编辑、发布权限](#_122-配置编辑、发布权限)
    * 配置编辑、发布权限支持按环境配置，比如开发环境开发人员可以自行完成配置编辑和发布的过程，但是生产环境发布权限交由测试或运维人员
-    * 生产环境建议同时开启[发布审核](zh/deployment/distributed-deployment-guide?id=_2-namespacelockswitch-一次发布只能有一个人修改开关，用于发布审核)，从而控制一次配置发布只能由一个人修改，另一个人发布，确保配置修改得到充分检查
+    * 生产环境建议同时开启[发布审核](zh/deployment/distributed-deployment-guide?id=_322-namespacelockswitch-一次发布只能有一个人修改开关，用于发布审核)，从而控制一次配置发布只能由一个人修改，另一个人发布，确保配置修改得到充分检查
 3. [配置查看权限](#_61-配置查看权限)
    * 可以指定某个环境只允许项目成员查看私有Namespace的配置，从而避免敏感配置泄露，如生产环境

@@ -462,4 +462,4 @@ Apollo 支持细粒度的权限控制，请务必根据实际情况做好权限

 1. `apollo-configservice`和`apollo-adminservice`是基于内网可信网络设计的，所以出于安全考虑，禁止`apollo-configservice`和`apollo-adminservice`直接暴露在公网
 2. 对敏感配置可以考虑开启[访问秘钥](#_62-%e9%85%8d%e7%bd%ae%e8%ae%bf%e9%97%ae%e5%af%86%e9%92%a5)，从而只有经过身份验证的客户端才能访问敏感配置
-3. 1.7.1及以上版本可以考虑为`apollo-adminservice`开启[访问控制](zh/deployment/distributed-deployment-guide?id=_6-admin-serviceaccesscontrolenabled-配置apollo-adminservice是否开启访问控制)，从而只有[受控的](zh/deployment/distributed-deployment-guide?id=_12-admin-serviceaccesstokens-%e8%ae%be%e7%bd%aeapollo-portal%e8%ae%bf%e9%97%ae%e5%90%84%e7%8e%af%e5%a2%83apollo-adminservice%e6%89%80%e9%9c%80%e7%9a%84access-token)`apollo-portal`才能访问对应接口，增强安全性
+3. 1.7.1及以上版本可以考虑为`apollo-adminservice`开启[访问控制](zh/deployment/distributed-deployment-guide?id=_326-admin-serviceaccesscontrolenabled-配置apollo-adminservice是否开启访问控制)，从而只有[受控的](zh/deployment/distributed-deployment-guide?id=_3112-admin-serviceaccesstokens-设置apollo-portal访问各环境apollo-adminservice所需的access-token)`apollo-portal`才能访问对应接口，增强安全性
--- a/docs/zh/usage/java-sdk-user-guide.md
+++ b/docs/zh/usage/java-sdk-user-guide.md
@@ -77,8 +77,8 @@ Apollo支持应用在不同的环境有不同的配置，所以需要在运行
    * 注意key为全大写，且中间是`_`分隔
 4. 通过`server.properties`配置文件
    * 可以在`server.properties`配置文件中指定`apollo.meta=http://config-service-url`
-    * 对于Mac/Linux，文件位置为`/opt/settings/server.properties`
-    * 对于Windows，文件位置为`C:\opt\settings\server.properties`
+    * 对于Mac/Linux，默认文件位置为`/opt/settings/server.properties`
+    * 对于Windows，默认文件位置为`C:\opt\settings\server.properties`
 5. 通过`app.properties`配置文件
    * 可以在`classpath:/META-INF/app.properties`指定`apollo.meta=http://config-service-url`
 6. 通过Java system property `${env}_meta`
@@ -137,8 +137,8 @@ MetaServerProvider的实现可以参考[LegacyMetaServerProvider](https://github
    * 注意key为全大写，且中间是`_`分隔
 4. 通过`server.properties`配置文件
    * 可以在`server.properties`配置文件中指定`apollo.configService=http://config-service-url:port`
-    * 对于Mac/Linux，文件位置为`/opt/settings/server.properties`
-    * 对于Windows，文件位置为`C:\opt\settings\server.properties`
+    * 对于Mac/Linux，默认文件位置为`/opt/settings/server.properties`
+    * 对于Windows，默认文件位置为`C:\opt\settings\server.properties`

 ### 1.2.3 本地缓存路径
 Apollo客户端会把从服务端获取到的配置在本地文件系统缓存一份，用于在遇到服务不可用，或网络不通的时候，依然能从本地恢复配置，不影响应用正常运行。
@@ -178,8 +178,8 @@ batch=2000
    * 注意key为全大写，且中间是`_`分隔
 4. 通过`server.properties`配置文件
    * 可以在`server.properties`配置文件中指定`apollo.cacheDir=/opt/data/some-cache-dir`
-    * 对于Mac/Linux，文件位置为`/opt/settings/server.properties`
-    * 对于Windows，文件位置为`C:\opt\settings\server.properties`
+    * 对于Mac/Linux，默认文件位置为`/opt/settings/server.properties`
+    * 对于Windows，默认文件位置为`C:\opt\settings\server.properties`

 > 注：本地缓存路径也可用于容灾目录，如果应用在所有config service都挂掉的情况下需要扩容，那么也可以先把配置从已有机器上的缓存路径复制到新机器上的相同缓存路径

@@ -201,8 +201,8 @@ Environment可以通过以下3种方式的任意一个配置：

 3. 通过配置文件
    * 最后一个推荐的方式是通过配置文件来指定`env=YOUR-ENVIRONMENT`
-    * 对于Mac/Linux，文件位置为`/opt/settings/server.properties`
-    * 对于Windows，文件位置为`C:\opt\settings\server.properties`
+    * 对于Mac/Linux，默认文件位置为`/opt/settings/server.properties`
+    * 对于Windows，默认文件位置为`C:\opt\settings\server.properties`

 文件内容形如：
 ```properties
@@ -244,8 +244,8 @@ Apollo支持配置按照集群划分，也就是说对于一个appId和一个环
    * 注意key为全大写
 5. 通过`server.properties`配置文件
    * 可以在`server.properties`配置文件中指定`idc=xxx`
-    * 对于Mac/Linux，文件位置为`/opt/settings/server.properties`
-    * 对于Windows，文件位置为`C:\opt\settings\server.properties`
+    * 对于Mac/Linux，默认文件位置为`/opt/settings/server.properties`
+    * 对于Windows，默认文件位置为`C:\opt\settings\server.properties`

 **Cluster Precedence**（集群顺序）

@@ -302,6 +302,21 @@ Apollo从1.6.0版本开始增加访问密钥机制，从而只有经过身份验
 4. 通过`app.properties`配置文件
    * 可以在`classpath:/META-INF/app.properties`指定`apollo.accesskey.secret=1cf998c4e2ad4704b45a98a509d15719`

+#### 1.2.4.5 自定义server.properties路径
+
+> 适用于1.8.0及以上版本
+
+1.8.0版本开始支持以下方式自定义server.properties路径，按照优先级从高到低分别为：
+
+1. 通过Java System Property `apollo.path.server.properties`
+   * 可以通过Java的System Property `apollo.path.server.properties`来指定
+   * 在Java程序启动脚本中，可以指定`-Dapollo.path.server.properties=/some-dir/some-file.properties`
+      * 如果是运行jar文件，需要注意格式是`java -Dapollo.path.server.properties=/some-dir/some-file.properties -jar xxx.jar`
+   * 也可以通过程序指定，如`System.setProperty("apollo.path.server.properties", "/some-dir/some-file.properties");`
+2. 通过操作系统的System Environment`APOLLO_PATH_SERVER_PROPERTIES`
+   * 可以通过操作系统的System Environment `APOLLO_PATH_SERVER_PROPERTIES`来指定
+   * 注意key为全大写，且中间是`_`分隔
+
 # 二、Maven Dependency
 Apollo的客户端jar包已经上传到中央仓库，应用在实际使用时只需要按照如下方式引入即可。
 ```xml