github.com/vicanso/pike@v1.0.1-0.20210630235453-9099e041f6ec/docs/start.md (about)

     1  ---
     2  description: 如何开始使用pike
     3  ---
     4  
     5  Pike是纯go的项目，可以使用各平台的执行文件启动或者已打包好的docker镜像(vicanso/pike)，配置信息支持保存在文件或etcd中，生产环境中建议使用etcd便于多实例部署。
     6  
     7  
     8  ## 启动参数
     9  
    10  ```bash
    11  Pike is a http cache server
    12  
    13  Usage:
    14    pike [flags]
    15  
    16  Flags:
    17        --admin string    The address of admin web page, e.g.: :9013
    18        --alarm string    The alarm request url, alarm will post to the url, e.g.: http://192.168.1.2:3000/alarms
    19        --config string   The config of pike, support etcd or file, etcd://user:pass@192.168.1.2:2379,192.168.1.3:2379/pike or /opt/pike.yml (default "pike.yml")
    20    -h, --help            help for pike
    21        --log string      The log path, e.g.: /var/pike.log or lumberjack:///tmp/pike.log?maxSize=100&maxAge=1&compress=true
    22  ```
    23  
    24  如上所示pike的启动参数如下：
    25  
    26  - admin 管理后台监听地址，用于启动管理后台，建议最少其中一个实例启用管理后台，方便使用WEB管理后台编辑配置
    27  - alarm 告警回调服务地址，当upstream的服务器检测失败或配置更新失败等时回调，用于告警通知
    28  - config 配置地址，可以用于etcd或者file的形式，建议在生产环境中使用etcd，如果不配置则直接使用文件形式，文件为pike.yml
    29  - log 日志目录配置，可以指定单一文件或使用lumberjack按时按文件大小分割日志并压缩
    30  
    31  
    32  首次启动指定管理后台监听地址为:9013，未指定配置地址（使用pike.yml)，启动成功后可以看到在执行目录下生成了一个空白的新文件pike.yml（如果该文件已存在则不新建），之后可以打开`http://127.0.0.1:9013/#/`进行配置。
    33  
    34  ```bash
    35  ./pike --admin=:9013
    36  ```
    37  
    38  ## 压缩参数配置
    39  
    40  - `Name` 压缩配置名称，用于区分每个压缩配置，可根据不同的应用场景配置不同的压缩参数，一般只使用一个通用配置则可
    41  - `Gzip Level` gzip的压缩级别，如果CPU较为紧张，则可以配置为默认的压缩级别6，如果CPU较为空闲，建议直接配置为最高压缩级别9，减少网络带宽的占用
    42  - `Br Level` brotli的压缩级别，由于br的压缩率较高，占用CPU较大，因此一般配置为6则可，具体根据CPU的使用状况可以选择更优的配置方式
    43  - `Remark` 备注
    44  
    45  <p align="center">
    46  <img src="./images/add-compress.png"/>
    47  </p>
    48  
    49  需要注意，对于缓存数据的压缩会直接使用默认的`bestCompression`的压缩配置，该配置的压缩级别为gzip:9, br:6，如果需要覆盖默认的配置，则直接新配置名为`bestCompression`的配置则可覆盖。缓存的数据只压缩一次而可使用多次，可以选择较高的压缩级别，对于常规的压缩配置，br的压缩级别配置为6则可，如果CPU占用较多，可以选择更小的值，具体各压缩级别耗时可查看模块-压缩模块的说明。
    50  
    51  ## 缓存参数配置
    52  
    53  - `Name` 缓存配置名称，用于区分每个缓存配置，对于请求量特别大的服务，可单独使用一个缓存，其它的服务则共用一个缓存则可
    54  - `Size` 缓存数量大小，指定LRU缓存的最大数量，可根据服务的缓存情况以及机器内存选择较为合适的值，一般设置为51200已能满足大部分应用的需求，如果内存较少则设置为更小的值
    55  - `HitForPass` 设置hit for pass的缓存时长，对于不可缓存的GET、HEAD请求，为了后续快速判断请求是否hit for pass，缓存中也有保存该请求的缓存状态(hitForPass)。
    56  - `Store` 设置缓存持久化存储的方式，暂只支持badger，如`badger:///tmp/badger`表示将缓存保存至`/tmp/badger`目录。如果内存较为空余，可设置LRU的Size为较大的值而不设置Store。
    57  - `Remark` 备注
    58  
    59  为什么会有需要hit for pass的场景？考虑一下以下场景，由于产品刚好被下架处理，因此请求产品详情信息时，该接口返回了出错（http status: 400，cache control: no-cache），因此访问该产品的接口缓存为hit for pass，而后续产品上架了，接口正常响应，缓存时长为cache-control: max-age=60，此时接口应该可缓存的。而由于hit for pass未过期，因此只能等hit for pass过期后接口才变为可缓存。
    60  
    61  因此在设置hit for pass的时候需要考虑应用的具体出错处理逻辑，Cache-Control是否无论怎样都不会变化（有一种处理是同样的参数，无论成功失败均使用同样的Cache-Control，这样保证无论成功还是失败，接口均是缓存，避免过多请求），如果是不变的，可以将hit for pass设置为较长的有效期，否则应该选择更短的有效期。
    62  
    63  <p align="center">
    64  <img src="./images/add-cache.png"/>
    65  </p>
    66  
    67  ### 缓存的Store配置
    68  
    69  - `badger`：使用badger缓存数据，配置格式为：`badger:///tmp/badger`，表示将数据缓存在`/tmp/badger`目录下。此模式下缓存会以文件的形式持久化，可减少LRU缓存的数据避免占用过多的内存。需要注意如果是启动多个实例，那么多实例间的缓存无法共享
    70  - `redis`：使用redis缓存数据，配置格式为：`redis://[:pwd@]host1:port1[,...hostN:portN]/[?timeout=3s&master=master]`。密码`pwd`为只选参数。对于`sentinel`还需要指定master参数。
    71  - `mongodb`：使用mongodb缓存数据，配置格式为mongodb的connection string形式，如：`mongodb://[username:password@]host1[:port1][,...hostN[:portN]][/[defaultauthdb][?options]]`，增加支持timeout参数指定请求超时。如`mongodb://localhost:27017/pike?timeout=5s`，连接localhost:27017并指定使用db:pike保存缓存数据
    72  
    73  ### redis配置
    74  
    75  - `普通模式`：`redis://:pwd@127.0.0.1:6379/?db=1&timeout=5s&prefix=test`，连接本地127.0.0.1:6379的redis，密码为pwd，使用db:1，并设置超时时间为5秒，key的前缀为test
    76  - `sentinel`：`redis://:pwd@127.0.0.1:6379,127.0.0.1:6380/?master=master&mode=sentinel&timeout=5s&prefix=test`，以sentinel的模式连接redis，密码为pwd，master name为master，并设置超时时间为5秒，key的前缀为test
    77  - `cluster`：`redis://:pwd@127.0.0.1:6379,127.0.0.1:6380/?mode=cluster&timeout=5s&prefix=test`，以cluster的模式连接redis，密码为pwd，并设置超时时间为5秒，key的前缀为test
    78  
    79  ## Upstream配置
    80  
    81  - `Name` upstream的配置名称，用于区分每个upstream配置
    82  - `Health Check` 健康检测的url路径，对于HTTP服务尽量使用特定的url的响应来检测upstream是否可用，如果未配置，则检测地址的端口是否有监听
    83  - `Policy` 服务器列表的选择策略，支持四种方式`roundRobin`，`random`， `first`与`leastConn`，一般选择`roundRobin`则可
    84  - `Enable H2C` 是否启用HTTP/2 over TCP，upstream的服务支持h2c模式，则可以启用此模式，pike与upstream的服务则使用h2c方式访问
    85  - `Accept Encoding` 设置可接受的编码，如果需要节约pike与upstream服务之间访问的网络带宽，可以添加此配置，pike支持编码：`gzip`，`br`，`lz4`，`zst`, 以及`snz`
    86  - `Servers.Addr` 服务地址，以http(s)://ip:port的形式配置
    87  - `Servers.Backup` 是否备用服务地址，如果设置为备用，则只要在主服务有一个可用时，均不会使用备用服务
    88  - `Remark` 备注
    89  
    90  <p align="center">
    91  <img src="./images/add-upstream.png"/>
    92  </p>
    93  
    94  ## Location配置
    95  
    96  - `Name` location的配置名称，用于区分每个location配置
    97  - `Upstream` 选择对应的upstream
    98  - `Prefixes` 配置对应的前缀，可配置多个，前缀的匹配优先级高于host
    99  - `Hosts` 配置对应的host，可配置多个
   100  - `Rewrites` 转发请求时，需要重写的URL的规则，配置格式为`key:value`的形式，以`:`分割
   101  - `QueryStrings` 转发请求时添加至url中querystring，配置格式为`key:value`的形式，以`:`分割
   102  - `RespHeaders` 响应头配置，将在所有的响应中添加响应头，配置格式为`key:value`的形式，以`:`分割
   103  - `ReqHeaders` 请求头配置，将在所有的请求中添加请求头，配置格式为`key:value`的形式，以`:`分割
   104  - `ProxyTimeout` 请求超时配置，用于控制请求转发至upstream的服务中的超时，根据实际场景配置，如：30s，1m等等
   105  - `Remark` 备注
   106  
   107  <p align="center">
   108  <img src="./images/add-location.png"/>
   109  </p>
   110  
   111  
   112  ### Rewrite规则
   113  
   114  重写的规则与nginx类似，支持使用正则匹配，如下面的例子：
   115  
   116  - `/api/*:/$1` $1表示*部分，最终的处理就是转发时将/api前缀删除
   117  - `/rest/*/user/*:/$1/$2` $1表示第一个*，$2表示第二个*，最终的处理就是转发的时候将/rest与/user替换
   118  
   119  虽然通过正则可以实现各类的重写，但是不建议使用过于复杂的正则，尽可能少用或只用重写来处理前缀，规范url减少重写。
   120  
   121  ### ENV获取配置
   122  
   123  `QueryStrings`，`RespHeaders`以及`ReqHeaders`均支持从ENV中获取值的处理方式，如：`DC:$DC`，$DC表示从ENV中获取DC对应的值。
   124  
   125  ## Server配置
   126  
   127  - `Addr` 监听地址
   128  - `Locations` 对应的location列表
   129  - `Cache` 缓存，根据应用访问量选择合适的缓存
   130  - `Compress` 压缩，根据带宽与CPU的考虑，选择合适的压缩
   131  - `Compress Min Length` 最小压缩长度，此值不要设置太少，因为压缩小数据效果并不明显，而且浪费CPU。一般建议设置为1kb，如果是内网间调用，建议此值可以调更大的值
   132  - `Compress Content Filter` 压缩数据类型筛选，指定针对哪些数据类型压缩，默认值为：`text|javascript|json|wasm|xml`，可按应用的需求自定义配置或不匹配。
   133  - `Log Format` 请求日志格式化配置，如`{remote} {when-iso} {:proxyTarget} {method} {uri} {proto} {status} {<x-status} {size-human} {referer} {userAgent}`，配置规则参考[elton logger](https://github.com/vicanso/elton/blob/master/docs/middlewares.md#logger)，日志的输出对于性能会有所影响
   134  - `Remark` 备注
   135  
   136  日志格式化配置中大部分都是通用的属性，需要注意以下的配置字段：
   137  
   138  - `:proxyTarget` 转发的目标地址
   139  - `<x-status` 接口响应的缓存状态
   140  
   141  <p align="center">
   142  <img src="./images/add-server.png"/>
   143  </p>
   144  
   145  当Server配置完成后，可以使用`curl http://addr/ping`来检测该Server是否启动成功，`/ping`默认由pike处理而不会转发至upstream
   146  
   147  ### Location匹配
   148  
   149  location列表中，按是否匹配prefix与host排序，其优先级是 prefix+host > prefix > host > 无配置，从列表中按顺序一个个location匹配，匹配则该请求由此location处理，如果所有均不匹配则出错。
   150  
   151  ## Admin配置
   152  
   153  - `Account` 登录账号
   154  - `Password` 登录密码
   155  
   156  设置配置成功后重启pike，之后每次使用都需要登录校验，建议在首次配置则设置。
   157  
   158  ## 缓存列表
   159  
   160  暂未支持查询当前缓存列表功能，仅可用于删除缓存
   161  
   162  <p align="center">
   163  <img src="./images/caches.png"/>
   164  </p>
   165  
   166  ## 非实时生效配置
   167  
   168  - `缓存配置` 由于缓存是多个LRU组成，因此如果调整缓存大小会导致缓存失败，而且锁的处理也比较麻烦，因此缓存更新非实时生效，只能重启应用
   169  - `Server配置的Log` 日志的输出是在Server创建时生成，如果后续有调整，只能重启应用
   170  - `Admin配置` admin配置非实时生效，因此在初始创建时建议配置