diff --git a/doc/wiki-cn/README.md b/doc/wiki-cn/README.md index 7bffe30ba..0d3775d62 100644 --- a/doc/wiki-cn/README.md +++ b/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标准化代码和文档; -# + +
+ +------------- + > 名字来源于:《战神》游戏以希腊神话为背景,讲述由凡人成为战神的奎托斯(Kratos)成为战神并展开弑神屠杀的冒险历程。 ------------- diff --git a/doc/wiki-cn/blademaster-mid.md b/doc/wiki-cn/blademaster-mid.md index 892d12046..5e0a4c3c4 100644 --- a/doc/wiki-cn/blademaster-mid.md +++ b/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) ------------- diff --git a/doc/wiki-cn/blademaster-mod.md b/doc/wiki-cn/blademaster-mod.md index 7a022e310..8e90c466b 100644 --- a/doc/wiki-cn/blademaster-mod.md +++ b/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) ------------- diff --git a/doc/wiki-cn/blademaster-pb.md b/doc/wiki-cn/blademaster-pb.md index 7f953c2c9..c9cbe683f 100644 --- a/doc/wiki-cn/blademaster-pb.md +++ b/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) ------------- diff --git a/doc/wiki-cn/blademaster-quickstart.md b/doc/wiki-cn/blademaster-quickstart.md index 8e55a01c5..ce1f7ef05 100644 --- a/doc/wiki-cn/blademaster-quickstart.md +++ b/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) ------------- diff --git a/doc/wiki-cn/blademaster.md b/doc/wiki-cn/blademaster.md index d09b26fcd..3ac7de262 100644 --- a/doc/wiki-cn/blademaster.md +++ b/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) ------------- diff --git a/doc/wiki-cn/cache-mc.md b/doc/wiki-cn/cache-mc.md index fb27af51f..4c8efcff3 100644 --- a/doc/wiki-cn/cache-mc.md +++ b/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) \ No newline at end of file +[memcache代码生成器](kratos-genmc.md) +[redis模块说明](cache-redis.md) + +------------- + +[文档目录树](summary.md) diff --git a/doc/wiki-cn/cache-redis.md b/doc/wiki-cn/cache-redis.md index 179cefcfb..a6c08e052 100644 --- a/doc/wiki-cn/cache-redis.md +++ b/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) \ No newline at end of file +[memcache模块说明](cache-mc.md) + +------------- + +[文档目录树](summary.md) diff --git a/doc/wiki-cn/config-paladin.md b/doc/wiki-cn/config-paladin.md new file mode 100644 index 000000000..c39423c9f --- /dev/null +++ b/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) +} +``` diff --git a/doc/wiki-cn/config.md b/doc/wiki-cn/config.md new file mode 100644 index 000000000..81d0d90b7 --- /dev/null +++ b/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 | - | - | 指定服务运行:
-grpc.target=demo.service=127.0.0.1:9000
-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 | 日志级别:
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:
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) diff --git a/doc/wiki-cn/database-hbase.md b/doc/wiki-cn/database-hbase.md index 56ff268e7..ab9932951 100644 --- a/doc/wiki-cn/database-hbase.md +++ b/doc/wiki-cn/database-hbase.md @@ -48,3 +48,7 @@ func main() { fmt.Printf("%v", result) } ``` + +------------- + +[文档目录树](summary.md) diff --git a/doc/wiki-cn/database-mysql.md b/doc/wiki-cn/database-mysql.md index 08f9e7fcc..3614c4e3f 100644 --- a/doc/wiki-cn/database-mysql.md +++ b/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) \ No newline at end of file +[hbase模块说明](database-hbase.md) + +------------- + +[文档目录树](summary.md) diff --git a/doc/wiki-cn/database.md b/doc/wiki-cn/database.md index 5f7149963..1939bccaa 100644 --- a/doc/wiki-cn/database.md +++ b/doc/wiki-cn/database.md @@ -15,3 +15,7 @@ HBase客户端,支持trace、slowlog和统计功能。 ## TiDB TiDB客户端,支持服务发现和熔断功能。 [tidb client](database-tidb.md) + +------------- + +[文档目录树](summary.md) diff --git a/doc/wiki-cn/protoc.md b/doc/wiki-cn/protoc.md index c050c796a..1d9ff92d5 100644 --- a/doc/wiki-cn/protoc.md +++ b/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) diff --git a/doc/wiki-cn/ratelimit.md b/doc/wiki-cn/ratelimit.md index 9b343d729..d6a875537 100644 --- a/doc/wiki-cn/ratelimit.md +++ b/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) diff --git a/doc/wiki-cn/summary.md b/doc/wiki-cn/summary.md index ec45417ab..a20baa790 100644 --- a/doc/wiki-cn/summary.md +++ b/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) diff --git a/doc/wiki-cn/warden-balancer.md b/doc/wiki-cn/warden-balancer.md index 9ae5e9e6e..48f9e5a09 100644 --- a/doc/wiki-cn/warden-balancer.md +++ b/doc/wiki-cn/warden-balancer.md @@ -37,3 +37,7 @@ func NewClient(conf *ClientConfig, opt ...grpc.DialOption) *Client { return c } ``` + +------------- + +[文档目录树](summary.md)