Update README.md

README.md

@@ -1,7 +1,14 @@
+* [一、准备工作](#%E4%B8%80%E5%87%86%E5%A4%87%E5%B7%A5%E4%BD%9C)
+* [二、安装步骤](#%E4%BA%8C%E5%AE%89%E8%A3%85%E6%AD%A5%E9%AA%A4)
+* [三、启动Apollo配置中心](#%E4%B8%89%E5%90%AF%E5%8A%A8apollo%E9%85%8D%E7%BD%AE%E4%B8%AD%E5%BF%83)
+* [四、使用Apollo配置中心](#%E5%9B%9B%E4%BD%BF%E7%94%A8apollo%E9%85%8D%E7%BD%AE%E4%B8%AD%E5%BF%83)
+
 为了让大家更快的上手了解Apollo配置中心，我们这里准备了一个Quick Start，能够在几分钟内在本地环境部署、启动Apollo配置中心。
 
 不过这里需要注意的是，Quick Start只针对本地测试使用，如果要部署到生产环境，还请另行参考[分布式部署指南](https://github.com/ctripcorp/apollo/wiki/%E5%88%86%E5%B8%83%E5%BC%8F%E9%83%A8%E7%BD%B2%E6%8C%87%E5%8D%97)。
 
+> 注：Quick Start需要有bash环境，Windows用户建议安装[Git Bash](https://git-for-windows.github.io/)，或者也可以直接通过IDE环境启动，详见[Apollo开发指南](https://github.com/ctripcorp/apollo/wiki/Apollo%E5%BC%80%E5%8F%91%E6%8C%87%E5%8D%97)。
+
 # 一、准备工作
 ## 1.1 Java
 
@@ -11,12 +18,12 @@
 由于Quick Start会在本地同时启动服务端和客户端，所以需要在本地安装Java 1.8+。
 
 在配置好后，可以通过如下命令检查：
-```
+```sh
 java -version
 ```
 
 样例输出：
-```
+```sh
 java version "1.8.0_74"
 Java(TM) SE Runtime Environment (build 1.8.0_74-b02)
 Java HotSpot(TM) 64-Bit Server VM (build 25.74-b02, mixed mode)
@@ -26,10 +33,10 @@ Java HotSpot(TM) 64-Bit Server VM (build 25.74-b02, mixed mode)
 
 * 版本要求：5.6.5+
 
-Apollo的表结构使用了多个on update语句，所以需要5.6.5以上版本。
+Apollo的表结构对`timestamp`使用了多个default声明，所以需要5.6.5以上版本。
 
 连接上MySQL后，可以通过如下命令检查：
-```
+```sql
 SHOW VARIABLES WHERE Variable_name = 'version';
 ```
 
@@ -40,14 +47,16 @@ SHOW VARIABLES WHERE Variable_name = 'version';
 ## 1.3 下载Quick Start安装包
 我们准备好了一个Quick Start安装包，大家只需要下载到本地，就可以直接使用，免去了编译、打包过程。
 
-安装包共64M，如果访问github网速不给力的话，可以从百度网盘下载。
+安装包共50M，如果访问github网速不给力的话，可以从百度网盘下载。
 
 1. 从Github下载
     * checkout或下载[apollo-build-scripts项目](https://github.com/nobodyiam/apollo-build-scripts)
+    * **由于Quick Start项目比较大，所以放在了另外的repository，请注意项目地址**
+        * https://github.com/nobodyiam/apollo-build-scripts
 2. 从百度网盘下载
-    * 通过[网盘链接](https://pan.baidu.com/s/1pKCE9C3)下载
+    * 通过[网盘链接](https://pan.baidu.com/s/1i5xAGmT)下载
     * 下载到本地后，在本地解压apollo-build-scripts.zip
-3. 为啥安装包要64M这么大？
+3. 为啥安装包要50M这么大？
     * 因为这是一个可以自启动的jar包，里面包含了所有依赖jar包以及一个内置的tomcat容器
 
 # 二、安装步骤
@@ -60,13 +69,13 @@ Apollo服务端共需要两个数据库：`ApolloPortalDB`和`ApolloConfigDB`，
 通过各种MySQL客户端导入[sql/apolloportaldb.sql](https://github.com/nobodyiam/apollo-build-scripts/blob/master/sql/apolloportaldb.sql)即可。
 
 下面以MySQL原生客户端为例：
-```
+```sql
 source /your_local_path/sql/apolloportaldb.sql
 ```
 
 导入成功后，可以通过执行以下sql语句来验证：
-```
-select Id, AppId, Name from ApolloPortalDB.App;
+```sql
+select `Id`, `AppId`, `Name` from ApolloPortalDB.App;
 ```
 
 | Id | AppId     | Name       |
@@ -77,12 +86,12 @@ select Id, AppId, Name from ApolloPortalDB.App;
 通过各种MySQL客户端导入[sql/apolloconfigdb.sql](https://github.com/nobodyiam/apollo-build-scripts/blob/master/sql/apolloconfigdb.sql)即可。
 
 下面以MySQL原生客户端为例：
-```
+```sql
 source /your_local_path/sql/apolloconfigdb.sql
 ```
 
 导入成功后，可以通过执行以下sql语句来验证：
-```
+```sql
 select `NamespaceId`, `Key`, `Value`, `Comment` from ApolloConfigDB.Item;
 ```
 | NamespaceId | Key     | Value | Comment            |
@@ -94,7 +103,7 @@ Apollo服务端需要知道如何连接到你前面创建的数据库，所以
 
 > 注意：填入的用户需要具备对ApolloPortalDB和ApolloConfigDB数据的读写权限。
 
-```
+```sh
 #apollo config db info
 apollo_config_db_url=jdbc:mysql://localhost:3306/ApolloConfigDB?characterEncoding=utf8
 apollo_config_db_username=用户名
@@ -113,32 +122,36 @@ apollo_portal_db_password=密码（如果没有密码，留空即可）
 Quick Start脚本会在本地启动3个服务，分别使用8070, 8080, 8090端口，请确保这3个端口当前没有被使用。
 
 例如，在Linux/Mac下，可以通过如下命令检查：
-```
+```sh
 lsof -i:8080
 ```
 
 ## 3.2 执行启动脚本
-```
+```sh
 ./build.sh start
 ```
 
 当看到如下输出后，就说明启动成功了！
-```
+```sh
 ==== starting service ====
-Started [14309]
-Waiting for config service startup......
+Service logging file is ./service/apollo-service.log
+Started [10768]
+Waiting for config service startup.......
 Config service started. You may visit http://localhost:8080 for service status now!
-Waiting for admin service startup...
+Waiting for admin service startup....
 Admin service started
 ==== starting portal ====
-Started [14370]
-Waiting for portal startup.......
+Portal logging file is ./portal/apollo-portal.log
+Started [10846]
+Waiting for portal startup......
 Portal started. You can visit http://localhost:8070 now!
 ```
 
 ## 3.3 异常排查
 如果启动遇到了异常，可以分别查看service和portal目录下的log文件排查问题。
 
+> 注：在启动apollo-configservice的过程中会在日志中输出eureka注册失败的信息，如`com.sun.jersey.api.client.ClientHandlerException: java.net.ConnectException: Connection refused`。需要注意的是，这个是预期的情况，因为apollo-configservice需要向Meta Server（它自己）注册服务，但是因为在启动过程中，自己还没起来，所以会报这个错。后面会进行重试的动作，所以等自己服务起来后就会注册正常了。
+
 # 四、使用Apollo配置中心
 ## 4.1 使用样例项目
 
@@ -149,8 +162,10 @@ Portal started. You can visit http://localhost:8070 now!
 2. 点击SampleApp进入配置界面，可以看到当前有一个配置timeout=100
 ![配置界面](https://github.com/nobodyiam/apollo-build-scripts/blob/master/images/sample-app-config.png)
 
+> 如果提示`系统出错，请重试或联系系统负责人`，请稍后几秒钟重试一下，因为通过Eureka注册的服务有一个刷新的延时。
+
 ### 4.1.2 运行客户端程序
-我们准备了一个简单的Demo客户端来演示从Apollo配置中心获取配置。
+我们准备了一个简单的[Demo客户端](https://github.com/ctripcorp/apollo/blob/master/apollo-demo/src/main/java/SimpleApolloConfigDemo.java)来演示从Apollo配置中心获取配置。
 
 程序很简单，就是用户输入一个key的名字，程序会输出这个key对应的值。
 
@@ -159,16 +174,23 @@ Portal started. You can visit http://localhost:8070 now!
 同时，客户端还会监听配置变化事件，一旦有变化就会输出变化的配置信息。
 
 运行`./build.sh client`启动Demo客户端，忽略前面的调试信息，可以看到如下提示：
-```
+```sh
 Apollo Config Demo. Please input key to get the value. Input quit to exit.
 >
 ```
 输入`timeout`，会看到如下信息：
-```
+```sh
 > timeout
 > [SimpleApolloConfigDemo] Loading key : timeout with value: 100
 ```
 
+> 如果运行客户端遇到问题，可以通过修改`client/log4j2.xml`中的level为DEBUG来查看更详细日志信息
+> ```xml
+> <logger name="com.ctrip.framework.apollo" additivity="false" level="trace">
+>     <AppenderRef ref="Async" level="DEBUG"/>
+> </logger>
+> ```
+
 ### 4.1.3 修改配置并发布
 
 1. 在配置界面点击timeout这一项的编辑按钮
@@ -184,13 +206,13 @@ Apollo Config Demo. Please input key to get the value. Input quit to exit.
 
 ### 4.1.4 客户端查看修改后的值
 如果客户端一直在运行的话，在配置发布后就会监听到配置变化，并输出修改的配置信息：
-```
+```sh
 [SimpleApolloConfigDemo] Changes for namespace application
 [SimpleApolloConfigDemo] Change - key: timeout, oldValue: 100, newValue: 200, changeType: MODIFIED
 ```
 
 再次输入`timeout`查看对应的值，会看到如下信息：
-```
+```sh
 > timeout
 > [SimpleApolloConfigDemo] Loading key : timeout with value: 200
 ```
@@ -203,7 +225,7 @@ Apollo Config Demo. Please input key to get the value. Input quit to exit.
 由于使用了新的项目，所以客户端需要修改appId信息。
 
 编辑`client/META-INF/app.properties`，修改app.id为你新创建的app id。
-```
+```properties
 app.id=你的appId
 ```
 运行`./build.sh client`启动Demo客户端即可。