Merge pull request #150 from bilibili/config-docs

fix doc

doc/wiki-cn/README.md

@@ -27,7 +27,11 @@ Kratos是bilibili开源的一套Go微服务框架，包含大量微服务相关
 * Trace: 组件化的trace支持（gRPC/HTTP/MySQL/Redis/Memcached）
 * Kratos Tool: 快速生成标准化项目，友好的Protobuf支持，非常方便生成gRPC、HTTP、swagger标准化代码和文档；
 
-# 
+
+<br>  
+
+-------------
+
 > 名字来源于:《战神》游戏以希腊神话为背景，讲述由凡人成为战神的奎托斯（Kratos）成为战神并展开弑神屠杀的冒险历程。
 
 -------------

doc/wiki-cn/blademaster-mid.md

@@ -131,7 +131,9 @@ func Example() {
 
 # 扩展阅读
 
-[bm快速开始](blademaster-quickstart.md) [bm模块说明](blademaster-mod.md)  [bm基于pb生成](blademaster-pb.md)
+[bm快速开始](blademaster-quickstart.md)   
+[bm模块说明](blademaster-mod.md)  
+[bm基于pb生成](blademaster-pb.md)  
 
 -------------
 

doc/wiki-cn/blademaster-mod.md

@@ -81,7 +81,9 @@ func (c *Context) Protobuf(data proto.Message, err error)
 
 # 扩展阅读
 
-[bm快速开始](blademaster-quickstart.md) [bm中间件](blademaster-mid.md)  [bm基于pb生成](blademaster-pb.md)
+[bm快速开始](blademaster-quickstart.md)  
+[bm中间件](blademaster-mid.md)  
+[bm基于pb生成](blademaster-pb.md)  
 
 -------------
 

doc/wiki-cn/blademaster-pb.md

@@ -77,7 +77,9 @@ kratos tool swagger serve api/api.swagger.json
 
 # 扩展阅读
 
-[bm快速开始](blademaster-quickstart.md) [bm模块说明](blademaster-mod.md) [bm中间件](blademaster-mid.md)
+[bm快速开始](blademaster-quickstart.md)  
+[bm模块说明](blademaster-mod.md)  
+[bm中间件](blademaster-mid.md)  
 
 -------------
 

doc/wiki-cn/blademaster-quickstart.md

@@ -123,7 +123,9 @@ go tool pprof http://127.0.0.1:8000/debug/pprof/profile
 
 # 扩展阅读
 
-[bm模块说明](blademaster-mod.md) [bm中间件](blademaster-mid.md)  [bm基于pb生成](blademaster-pb.md)
+[bm模块说明](blademaster-mod.md)  
+[bm中间件](blademaster-mid.md)  
+[bm基于pb生成](blademaster-pb.md)  
 
 -------------
 

doc/wiki-cn/blademaster.md

@@ -36,10 +36,10 @@
 
 # 扩展阅读
 
-[bm快速开始](blademaster-quickstart.md)    
-[bm模块说明](blademaster-mod.md)    
-[bm中间件](blademaster-mid.md)      
-[bm基于pb生成](blademaster-pb.md) 
+[bm快速开始](blademaster-quickstart.md)  
+[bm模块说明](blademaster-mod.md)  
+[bm中间件](blademaster-mid.md)  
+[bm基于pb生成](blademaster-pb.md)  
 
 -------------
 

doc/wiki-cn/cache-mc.md

@@ -231,5 +231,9 @@ func (d *Dao) DelCacheDemo(c context.Context, id int64) (err error) {
 
 # 扩展阅读
 
-[memcache代码生成器](kratos-genmc.md)
-[redis模块说明](cache-redis.md)
+[memcache代码生成器](kratos-genmc.md)  
+[redis模块说明](cache-redis.md)  
+
+-------------
+
+[文档目录树](summary.md)

doc/wiki-cn/cache-redis.md

@@ -219,4 +219,8 @@ func (d *Dao) HGETALLDemo(c context.Context, pid int64) (res map[string]int64, e
 
 # 扩展阅读
 
-[memcache模块说明](cache-mc.md)
+[memcache模块说明](cache-mc.md)  
+
+-------------
+
+[文档目录树](summary.md)

doc/wiki-cn/config-paladin.md

@@ -0,0 +1,111 @@
+# Paladin SDK
+
+## 配置模块化
+进行配置的模块化是为了更好地管理配置，尽可能避免由修改配置带来的失误。  
+在配置种类里，可以看到其实 环境配置 和 应用配置 已经由平台进行管理化。  
+我们通常业务里只用配置 业务配置 和 在线配置 就可以了，之前我们大部分都是单个文件配置，而为了更好管理我们需要按类型进行拆分配置文件。  
+
+例如：
+
+| 名称 | 说明 |
+|:------|:------|
+| application.toml | 在线配置 |
+| mysql.toml | 业务db配置 |
+| hbase.toml | 业务hbase配置 |
+| memcache.toml | 业务mc配置 |
+| redis.toml | 业务redis配置 |
+| http.toml | 业务http client/server/auth配置 |
+| grpc.toml | 业务grpc client/server配置 |
+
+## 使用方式
+
+paladin 是一个config SDK客户端，包括了remote、file、mock几个抽象功能，方便使用本地文件或者远程配置中心，并且集成了对象自动reload功能。
+
+### 远程配置中心
+可以通过环境变量注入，例如：APP_ID/DEPLOY_ENV/ZONE/HOSTNAME，然后通过paladin实现远程配置中心SDK进行配合使用。
+
+### 指定本地文件：
+```shell
+./cmd -conf=/data/conf/app/demo.toml
+# or multi file
+./cmd -conf=/data/conf/app/
+```
+
+### mock配置文件
+```go
+func TestMain(t *testing.M) {
+    mock := make(map[string]string])
+    mock["application.toml"] = `
+        demoSwitch = false
+        demoNum = 100
+        demoAPI = "xxx"
+    `
+    paladin.DefaultClient = paladin.NewMock(mock)
+}
+```
+
+### example main
+```go
+# main.go
+func main() {
+    # 初始化paladin
+    if err := paladin.Init(); err != nil {
+        panic(err)
+    }
+    log.Init(nil) // debug flag: log.dir={path}
+    defer log.Close()
+}
+```
+
+### example HTTP/gRPC
+```go
+# http.toml
+[server]
+    addr = "0.0.0.0:9000"
+    timeout = "1s"
+
+# server.go
+func NewServer() {
+    # 默认配置用nil
+    engine := bm.DefaultServer(nil)
+
+    # 除非自己要替换了配置，用http.toml
+    var bc struct {
+        Server *bm.ServerConfig
+    }
+    if err = paladin.Get("http.toml").UnmarshalTOML("server", &bc); err != nil {
+        // 不存在时，将会为nil使用默认配置
+        if err ！= paladin.ErrNotExist {
+            panic(err)
+        }
+    } 
+    engine := bm.DefaultServer(conf)
+}
+```
+
+### example Service（在线配置热加载配置）
+```go
+# service.go
+type Service struct {
+    ac *paladin.Map
+}
+func New() *Service {
+    # paladin.Map 通过atomic.Value支持自动热加载
+    var ac = new(paladin.TOML)
+    if err := paladin.Watch("application.toml", ac); err != nil {
+        panic(err)
+    }
+    s := &Service{
+        ac : ac;
+    }
+    return s
+}
+func (s *Service) Test() {
+    switch, err := s.ac.Bool("switch")
+    if err != nil {
+        // TODO
+    }
+    # or use default value
+    switch := paladin.Bool(s.ac.Value("switch"), false)
+}
+```

doc/wiki-cn/config.md

@@ -0,0 +1,51 @@
+# config
+
+## 介绍
+初看起来，配置管理可能很简单，但是这其实是不稳定的一个重要来源。  
+即变更管理导致的故障，我们目前基于配置中心（config-service）的部署方式，二级制文件的发布与配置文件的修改是异步进行的，每次变更配置，需要重新构建发版。  
+由此，我们整体对配置文件进行梳理，对配置进行模块化，以及方便易用的paladin config sdk。
+
+## 环境配置
+
+| flag   | env   | remark |
+|:----------|:----------|:------|
+| region | REGION | 部署地区，sh-上海、gz-广州、bj-北京 |
+| zone | ZONE | 分布区域，sh001-上海核心、sh004-上海嘉定 |
+| deploy.env | DEPLOY_ENV | dev-开发、fat1-功能、uat-集成、pre-预发、prod-生产 |
+| deploy.color | DEPLOY_COLOR | 服务颜色，blue（测试feature染色请求） |
+| - | HOSTNAME | 主机名，xxx-hostname |
+
+全局公用环境变量，通常为部署环境配置，由系统、发布系统或supervisor进行环境变量注入，并不用进行例外配置，如果开发过程中可以通过flag注入进行运行测试。
+
+## 应用配置
+
+| flag   | env   |      default      |  remark |
+|:----------|:----------|:-------------|:------|
+| appid | APP_ID | - | 应用ID |
+| http | HTTP | tcp://0.0.0.0:8000/?timeout=1s | http 监听端口 |
+| http.perf | HTTP_PERF | tcp://0.0.0.0:2233/?timeout=1s | http perf 监听端口 |
+| grpc | GRPC | tcp://0.0.0.0:9000/?timeout=1s&idle_timeout=60s | grpc 监听端口 |
+| grpc.target | - | - | 指定服务运行：<br>-grpc.target=demo.service=127.0.0.1:9000 <br>-grpc.target=demo.service=127.0.0.2:9000 |
+| discovery.nodes | DISCOVERY_NODES | - | 服务发现节点：127.0.0.1:7171,127.0.0.2:7171 |
+| log.v | LOG_V |  0 | 日志级别：<br>DEBUG:0 INFO:1 WARN:2 ERROR:3 FATAL:4 |
+| log.stdout | LOG_STDOUT | false | 是否标准输出：true、false|
+| log.dir | LOG_DIR | - | 日志文件目录，如果配置会输出日志到文件，否则不输出日志文件 |
+| log.agent | LOG_AGENT | - | 日志采集agent：<br>unixpacket:///var/run/lancer/collector_tcp.sock?timeout=100ms&chan=1024 |
+| log.module | LOG_MODULE | - | 指定field信息 format: file=1,file2=2. |
+| log.filter | LOG_FILTER | - | 过虑敏感信息 format: field1,field2. |
+
+基本为一些应用相关的配置信息，通常发布系统和supervisor都有对应的部署环境进行配置注入，并不用进行例外配置，如果开发过程中可以通过flag进行注入运行测试。
+
+## 业务配置
+Redis、MySQL等业务组件，可以使用静态的配置文件来初始化，根据应用业务集群进行配置。
+
+## 在线配置
+需要在线读取、变更的配置信息，比如某个业务开关，可以实现配置reload实时更新。
+
+## 扩展阅读
+
+[paladin配置sdk](config-paladin.md)  
+
+-------------
+
+[文档目录树](summary.md)

doc/wiki-cn/database-hbase.md

@@ -48,3 +48,7 @@ func main() {
     fmt.Printf("%v", result)
 }
 ```
+
+-------------
+
+[文档目录树](summary.md)

doc/wiki-cn/database-mysql.md

@@ -227,4 +227,8 @@ if err = tx.Rollback().Error; err!=nil{
 # 扩展阅读
 
 [tidb模块说明](database-tidb.md)
-[hbase模块说明](database-hbase.md)
+[hbase模块说明](database-hbase.md)
+
+-------------
+
+[文档目录树](summary.md)

doc/wiki-cn/database.md

@@ -15,3 +15,7 @@ HBase客户端，支持trace、slowlog和统计功能。
 ## TiDB
 TiDB客户端，支持服务发现和熔断功能。  
 [tidb client](database-tidb.md)
+
+-------------
+
+[文档目录树](summary.md)

doc/wiki-cn/protoc.md

@@ -23,3 +23,7 @@ protoc -I$GOPATH/src:$KRATOS_HOME/tool/protobuf/pkg/extensions:$KRATOS_DEMO/api
 ```
 
 请注意替换`/Users/felix/work/go/src`目录为你本地开发环境对应GOPATH目录，其中`--gogofast_out`意味着告诉`protoc`工具需要使用`gogo protobuf`的工具生成代码。
+
+-------------
+
+[文档目录树](summary.md)

doc/wiki-cn/ratelimit.md

@@ -55,3 +55,6 @@ windows 表示一秒内采样窗口的数量，默认配置中是 5s 50 个采
 
 [Sentinel 系统自适应限流](https://github.com/alibaba/Sentinel/wiki/%E7%B3%BB%E7%BB%9F%E8%87%AA%E9%80%82%E5%BA%94%E9%99%90%E6%B5%81)
 
+-------------
+
+[文档目录树](summary.md)

doc/wiki-cn/summary.md

@@ -14,6 +14,8 @@
   * [warden resolver](warden-resolver.md) 
   * [warden balancer](warden-balancer.md) 
   * [warden protobuf](warden-pb.md) 
+* [config](config.md)
+  * [paladin](config-paladin.md)
 * [dapper trace](dapper.md)
 * [log](logger.md)
   * [log-agent](log-agent.md)

doc/wiki-cn/warden-balancer.md

@@ -37,3 +37,7 @@ func NewClient(conf *ClientConfig, opt ...grpc.DialOption) *Client {
 	return c
 }
 ```
+
+-------------
+
+[文档目录树](summary.md)