@colin4k1024/tsp 2.4.0

package/skills/goframe-v2/references/WEB/346/234/215/345/212/241/345/274/200/345/217/221//351/253/230/347/272/247/347/211/271/346/200/247/HOOK/344/272/213/344/273/266/345/233/236/350/260/203.md

@@ -0,0 +1,343 @@
+`ghttp.Server` 提供了事件回调注册功能，类似于其他框架的 `中间件` 功能，相比较于 `中间件`，事件回调的特性更加简单。
+
+`ghttp.Server` 支持用户对于某一事件进行自定义监听处理，按照 `pattern` 方式进行绑定注册( `pattern` 格式与路由注册一致)。 **支持多个方法对同一事件进行监听**， `ghttp.Server` 将会按照 `路由优先级` 及 `回调注册顺序` 进行回调方法调用。同一事件时先注册的HOOK回调函数优先级越高。 相关方法如下：
+
+```go
+func (s *Server) BindHookHandler(pattern string, hook string, handler HandlerFunc) error
+func (s *Server) BindHookHandlerByMap(pattern string, hookmap map[string]HandlerFunc) error
+```
+
+当然域名对象也支持事件回调注册：
+
+```go
+func (d *Domain) BindHookHandler(pattern string, hook string, handler HandlerFunc) error
+func (d *Domain) BindHookHandlerByMap(pattern string, hookmap map[string]HandlerFunc) error
+```
+
+支持的 `Hook` 事件列表：
+
+1. `ghttp.HookBeforeServe`
+
+在进入/初始化服务对象之前，该事件是最常用的事件，特别是针对于权限控制、跨域请求等处理。
+
+2. `ghttp.HookAfterServe`
+
+在完成服务执行流程之后。
+
+3. `ghttp.HookBeforeOutput`
+
+向客户端输出返回内容之前。
+
+4. `ghttp.HookAfterOutput`
+
+向客户端输出返回内容之后。
+
+具体调用时机请参考图例所示。
+
+## 回调优先级
+
+由于事件的绑定也是使用的路由规则，因此它的优先级和 [路由管理-路由规则](../路由管理/路由管理-路由规则.md) 章节介绍的优先级是一样的。
+
+但是事件调用时和路由注册调用时的机制不一样， **同一个路由规则下允许绑定多个事件回调方法**，该路由下的事件调用会 `按照优先级进行调用`，假如优先级相等的路由规则，将会按照事件注册的顺序进行调用。
+
+### 关于全局回调
+
+我们往往使用绑定 `/*` 这样的 `HOOK` 路由来实现全局的回调处理，这样是可以的。但是 `HOOK` 执行的优先是最低的，路由注册的越精确，优先级越高，越模糊的路由优先级越低， `/*` 就属于最模糊的路由。
+
+为降低不同的模块耦合性，所有的路由往往不是在同一个地方进行注册。例如用户模块注册的 `HOOK`( `/user/*`)，它将会被优先调用随后才可能是全局的 `HOOK`；如果仅仅依靠注册顺序来控制优先级，在模块多路由多的时候优先级便很难管理。
+
+### 业务函数调用顺序
+
+建议 相同的业务(同一业务模块) 的多个处理函数(例如: A、B、C)放到同一个 `HOOK` 回调函数中进行处理，在注册的回调函数中自行管理业务处理函数的调用顺序(函数调用顺序: A-B-C)。
+
+虽然同样的需求，注册多个相同 `HOOK` 的回调函数也可以实现，功能上不会有问题，但从设计的角度来讲，内聚性降低了，不便于业务函数管理。
+
+## `ExitHook` 方法
+
+当路由匹配到多个 `HOOK` 方法时，默认是按照路由匹配优先级顺序执行 `HOOK` 方法。当在 `HOOK` 方法中调用 `Request.ExitHook` 方法后，后续的 `HOOK` 方法将不会被继续执行，作用类似 `HOOK` 方法覆盖。
+
+## 接口鉴权控制
+
+事件回调注册比较常见的应用是在对调用的接口进行鉴权控制/权限控制。该操作需要绑定 `ghttp.HookBeforeServe` 事件，在该事件中会对所有匹配的接口请求(例如绑定 `/*` 事件回调路由)服务执行前进行回调处理。当鉴权不通过时，需要调用 `r.ExitAll()` 方法退出后续的服务执行(包括后续的事件回调执行)。
+
+此外，在权限校验的事件回调函数中执行 `r.Redirect*` 方法，又没有调用 `r.ExitAll()` 方法退出业务执行，往往会产生 `http multiple response writeheader calls` 错误提示。因为 `r.Redirect*` 方法会往返回的header中写入 `Location` 头；而随后的业务服务接口往往会往header写入 `Content-Type`/ `Content-Length` 头，这两者有冲突造成的。
+
+## 中间件与事件回调
+
+中间件（ `Middleware`）与事件回调（ `HOOK`）是 `GoFrame` 框架的两大流程控制特性，两者都可用于控制请求流程，并且也都支持绑定特定的路由规则。但两者区别也是非常明显的。
+
+1. 首先，中间件侧重于应用级的流程控制，而事件回调侧重于服务级流程控制；也就是说中间件的作用域仅限于应用，而事件回调的“权限”更强大，属于 `Server` 级别，并可处理静态文件的请求回调。
+2. 其次，中间件设计采用了“洋葱”设计模型；而事件回调采用的是特定事件的钩子触发设计。
+3. 最后，中间件相对来说灵活性更高，也是比较推荐的流程控制方式；而事件回调比较简单，但灵活性较差。
+
+### `Request.URL` 与 `Request.Router`
+
+`Request.Router` 是匹配到的路由对象，包含路由注册信息，一般来说开发者不会用到。 `Request.URL` 是底层请求的URL对象（继承自标准库 `http.Request`），包含请求的URL地址信息，特别是 `Request.URL.Path` 表示请求的URI地址。
+
+因此，假如在服务回调函数中使用的话， `Request.Router` 是有值的，因为只有匹配到了路由才会调用服务回调方法。但是在事件回调函数中，该对象可能为 `nil`（表示没有匹配到服务回调函数路由）。特别是在使用事件回调对请求接口鉴权的时候，应当使用 `Request.URL` 对象获取请求的URL信息，而不是 `Request.Router`。
+
+## 静态文件事件
+:::tip
+如果仅仅是提供API接口服务（包括前置静态文件服务代理如 `nginx`），不涉及到静态文件服务，那么可以忽略该小节。
+:::
+需要注意的是，事件回调同样能够匹配到符合路由规则的静态文件访问（ [静态文件](静态文件服务.md) 特性在 `gf` 框架中是默认关闭的，我们可以使用 `WebServer` 相关配置来手动开启，具体查看 [服务配置](../服务配置/服务配置.md) 章节）。
+
+例如，我们注册了一个 `/*` 的全局匹配事件回调路由，那么 `/static/js/index.js` 或者 `/upload/images/thumb.jpg` 等等静态文件访问也会被匹配到，会进入到注册的事件回调函数中进行处理。
+
+我们可以在事件回调函数中使用 `Request.IsFileRequest()` 方法来判断该请求是否是静态文件请求，如果业务逻辑不需要静态文件的请求事件回调，那么在事件回调函数中直接忽略即可，以便进行选择性地处理。
+
+## 事件回调示例
+
+### 示例1，基本使用
+
+```go
+package main
+
+import (
+    "github.com/gogf/gf/v2/frame/g"
+    "github.com/gogf/gf/v2/net/ghttp"
+    "github.com/gogf/gf/v2/os/glog"
+)
+
+func main() {
+    // 基本事件回调使用
+    p := "/:name/info/{uid}"
+    s := g.Server()
+    s.BindHookHandlerByMap(p, map[string]ghttp.HandlerFunc{
+        ghttp.HookBeforeServe:  func(r *ghttp.Request) { glog.Println(ghttp.HookBeforeServe) },
+        ghttp.HookAfterServe:   func(r *ghttp.Request) { glog.Println(ghttp.HookAfterServe) },
+        ghttp.HookBeforeOutput: func(r *ghttp.Request) { glog.Println(ghttp.HookBeforeOutput) },
+        ghttp.HookAfterOutput:  func(r *ghttp.Request) { glog.Println(ghttp.HookAfterOutput) },
+    })
+    s.BindHandler(p, func(r *ghttp.Request) {
+        r.Response.Write("用户:", r.Get("name"), ", uid:", r.Get("uid"))
+    })
+    s.SetPort(8199)
+    s.Run()
+}
+
+```
+
+当访问 [http://127.0.0.1:8199/john/info/10000](http://127.0.0.1:8199/john/info/10000) 时，运行WebServer进程的终端将会按照事件的执行流程打印出对应的事件名称。
+
+### 示例2，相同事件注册
+
+```go
+package main
+
+import (
+    "github.com/gogf/gf/v2/frame/g"
+    "github.com/gogf/gf/v2/net/ghttp"
+)
+
+// 优先调用的HOOK
+func beforeServeHook1(r *ghttp.Request) {
+    r.SetParam("name", "GoFrame")
+    r.Response.Writeln("set name")
+}
+
+// 随后调用的HOOK
+func beforeServeHook2(r *ghttp.Request) {
+    r.SetParam("site", "https://goframe.org")
+    r.Response.Writeln("set site")
+}
+
+// 允许对同一个路由同一个事件注册多个回调函数，按照注册顺序进行优先级调用。
+// 为便于在路由表中对比查看优先级，这里讲HOOK回调函数单独定义为了两个函数。
+func main() {
+    s := g.Server()
+    s.BindHandler("/", func(r *ghttp.Request) {
+        r.Response.Writeln(r.Get("name"))
+        r.Response.Writeln(r.Get("site"))
+    })
+    s.BindHookHandler("/", ghttp.HookBeforeServe, beforeServeHook1)
+    s.BindHookHandler("/", ghttp.HookBeforeServe, beforeServeHook2)
+    s.SetPort(8199)
+    s.Run()
+}
+```
+
+执行后，终端输出的路由表信息如下：
+
+```text
+SERVER | ADDRESS | DOMAIN  | METHOD | P | ROUTE |        HANDLER        |    MIDDLEWARE
+|---------|---------|---------|--------|---|-------|-----------------------|-------------------|
+  default |  :8199  | default | ALL    | 1 | /     | main.main.func1       |
+|---------|---------|---------|--------|---|-------|-----------------------|-------------------|
+  default |  :8199  | default | ALL    | 2 | /     | main.beforeServeHook1 | HOOK_BEFORE_SERVE
+|---------|---------|---------|--------|---|-------|-----------------------|-------------------|
+  default |  :8199  | default | ALL    | 1 | /     | main.beforeServeHook2 | HOOK_BEFORE_SERVE
+|---------|---------|---------|--------|---|-------|-----------------------|-------------------|
+```
+
+手动访问 [http://127.0.0.1:8199/](http://127.0.0.1:8199/) 后，页面输出内容为：
+
+```
+set name
+set site
+GoFrame
+https://goframe.org
+```
+
+### 示例3，改变业务逻辑
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/gogf/gf/v2/frame/g"
+    "github.com/gogf/gf/v2/net/ghttp"
+)
+
+func main() {
+    s := g.Server()
+    // 多事件回调示例，事件1
+    pattern1 := "/:name/info"
+    s.BindHookHandlerByMap(pattern1, map[string]ghttp.HandlerFunc{
+        ghttp.HookBeforeServe: func(r *ghttp.Request) {
+            r.SetParam("uid", 1000)
+        },
+    })
+    s.BindHandler(pattern1, func(r *ghttp.Request) {
+        r.Response.Write("用户:", r.Get("name"), ", uid:", r.Get("uid"))
+    })
+
+    // 多事件回调示例，事件2
+    pattern2 := "/{object}/list/{page}.java"
+    s.BindHookHandlerByMap(pattern2, map[string]ghttp.HandlerFunc{
+        ghttp.HookBeforeOutput: func(r *ghttp.Request) {
+            r.Response.SetBuffer([]byte(
+                fmt.Sprintf("通过事件修改输出内容, object:%s, page:%s", r.Get("object"), r.GetRouterString("page"))),
+            )
+        },
+    })
+    s.BindHandler(pattern2, func(r *ghttp.Request) {
+        r.Response.Write(r.Router.Uri)
+    })
+    s.SetPort(8199)
+    s.Run()
+}
+```
+
+通过事件1设置了访问 `/:name/info` 路由规则时的GET参数；通过事件2，改变了当访问的路径匹配路由 `/{object}/list/{page}.java` 时的输出结果。执行之后，访问以下URL查看效果：
+
+- [http://127.0.0.1:8199/user/info](http://127.0.0.1:8199/user/info)
+- [http://127.0.0.1:8199/user/list/1.java](http://127.0.0.1:8199/user/list/1.java)
+- [http://127.0.0.1:8199/user/list/2.java](http://127.0.0.1:8199/user/list/2.java)
+
+### 示例4，回调执行优先级
+
+```go
+package main
+
+import (
+    "github.com/gogf/gf/v2/frame/g"
+    "github.com/gogf/gf/v2/net/ghttp"
+)
+
+func main() {
+    s := g.Server()
+    s.BindHandler("/priority/show", func(r *ghttp.Request) {
+        r.Response.Writeln("priority service")
+    })
+
+    s.BindHookHandlerByMap("/priority/:name", map[string]ghttp.HandlerFunc{
+        ghttp.HookBeforeServe: func(r *ghttp.Request) {
+            r.Response.Writeln("/priority/:name")
+        },
+    })
+    s.BindHookHandlerByMap("/priority/*any", map[string]ghttp.HandlerFunc{
+        ghttp.HookBeforeServe: func(r *ghttp.Request) {
+            r.Response.Writeln("/priority/*any")
+        },
+    })
+    s.BindHookHandlerByMap("/priority/show", map[string]ghttp.HandlerFunc{
+        ghttp.HookBeforeServe: func(r *ghttp.Request) {
+            r.Response.Writeln("/priority/show")
+        },
+    })
+    s.SetPort(8199)
+    s.Run()
+}
+```
+
+在这个示例中，我们往注册了3个路由规则的事件回调，并且都能够匹配到路由注册的地址 `/priority/show`，这样我们便可以通过访问这个地址来看看路由执行的顺序是怎么样的。
+
+执行后我们访问 [http://127.0.0.1:8199/priority/show](http://127.0.0.1:8199/priority/show) ，随后我们看到页面输出以下信息：
+
+```
+/priority/show
+/priority/:name
+/priority/*any
+priority service
+```
+
+### 示例5，允许跨域请求
+
+在 [路由管理-中间件/拦截器](../%E8%B7%AF%E7%94%B1%E7%AE%A1%E7%90%86/%E8%B7%AF%E7%94%B1%E7%AE%A1%E7%90%86-%E4%B8%AD%E9%97%B4%E4%BB%B6%E6%8B%A6%E6%88%AA%E5%99%A8/%E4%B8%AD%E9%97%B4%E4%BB%B6%E6%8B%A6%E6%88%AA%E5%99%A8-%E5%9F%BA%E6%9C%AC%E4%BB%8B%E7%BB%8D.md) 和 [CORS跨域处理](CORS跨域处理.md) 章节也有介绍跨域处理的示例，大多数情况下，我们使用中间件来处理跨域请求的实现居多。
+
+`HOOK` 和中间件都能实现跨域请求处理，我们这里使用HOOK来实现简单的跨域处理。 首先我们来看一个简单的接口示例：
+
+```go
+package main
+
+import (
+    "github.com/gogf/gf/v2/frame/g"
+    "github.com/gogf/gf/v2/net/ghttp"
+)
+
+func Order(r *ghttp.Request) {
+    r.Response.Write("GET")
+}
+
+func main() {
+    s := g.Server()
+    s.Group("/api.v1", func(group *ghttp.RouterGroup) {
+        group.GET("/order", Order)
+    })
+    s.SetPort(8199)
+    s.Run()
+}
+```
+
+接口地址是 [http://localhost:8199/api.v1/order](http://localhost:8199/api.v1/order) ，当然这个接口是不允许跨域的。我们打开一个不同的域名，例如：百度首页(正好用了 `jQuery`，方便调试)，然后按 `F12` 打开开发者面板，在 `console` 下执行以下 `AJAX` 请求：
+
+```
+$.get("http://localhost:8199/api.v1/order", function(result){
+    console.log(result)
+});
+```
+
+结果如下：
+
+返回了不允许跨域的错误，接着我们修改一下测试代码，如下：
+
+```go
+package main
+
+import (
+    "github.com/gogf/gf/v2/frame/g"
+    "github.com/gogf/gf/v2/net/ghttp"
+)
+
+func Order(r *ghttp.Request) {
+    r.Response.Write("GET")
+}
+
+func main() {
+    s := g.Server()
+    s.Group("/api.v1", func(group *ghttp.RouterGroup) {
+        group.Hook("/*any", ghttp.HookBeforeServe, func(r *ghttp.Request) {
+            r.Response.CORSDefault()
+        })
+        group.GET("/order", Order)
+    })
+    s.SetPort(8199)
+    s.Run()
+}
+```
+
+我们增加了针对于路由 `/api.v1/*any` 的绑定事件 `ghttp.HookBeforeServe`，该事件将会在所有服务执行之前调用，该事件的回调方法中，我们通过调用 `CORSDefault` 方法使用默认的跨域设置允许跨域请求。该绑定的事件路由规则使用了模糊匹配规则，表示所有 `/api.v1` 开头的接口地址都允许跨域请求。
+
+返回刚才的百度首页，再次执行请求 `AJAX` 请求，这次便成功了：

package/skills/goframe-v2/references/WEB/346/234/215/345/212/241/345/274/200/345/217/221//351/253/230/347/272/247/347/211/271/346/200/247/HTTPS & TLS.md"

@@ -0,0 +1,263 @@
+## HTTPS服务
+
+建立 `HTTPS` 服务非常简单，使用框架WebServer提供的 `EnableHTTPS(certFile, keyFile string) error` 方法即可。很显然，该方法中需要提供两个参数，即两个用于 `HTTPS` 非对称加密的证书文件以及对应的秘钥文件。
+
+### 准备工作
+
+在本地演示的需要，我们可以使用 `openssl` 命令生成本地用于测试的证书和对应的秘钥文件。命令如下：
+
+1. 使用常用的 `RSA` 算法生成秘钥文件
+
+    ```shell
+    openssl genrsa -out server.key 2048
+    ```
+
+    （可选）或者，我们也可以使用 `ECDSA` 算法来生成秘钥文件：
+
+    ```shell
+    openssl ecparam -genkey -name secp384r1 -out server.key
+    ```
+
+2. 根据秘钥文件生成证书文件
+
+    ```shell
+    openssl req -new -x509 -key server.key -out server.crt -days 365
+    ```
+
+3. （可选）根据秘钥生成公钥文件，该文件用于客户端与服务端通信
+
+    ```shell
+    openssl rsa -in server.key -out server.key.public
+    ```
+
+`openssl` 支持的算法以及命令参数比较多，如果想要深入了解请使用 `man openssl` 命令进行查看。本次示例中，本地环境（`Ubuntu`）使用命令生成相关秘钥、公钥、证书文件的流程如下：
+
+```bash
+$ openssl genrsa -out server.key 2048
+Generating RSA private key, 2048 bit long modulus
+.........................+++
+.....................................................................+++
+unable to write 'random state'
+e is 65537 (0x10001)
+
+$ openssl req -new -x509 -key server.key -out server.crt -days 365
+You are about to be asked to enter information that will be incorporated
+into your certificate request.
+What you are about to enter is what is called a Distinguished Name or a DN.
+There are quite a few fields but you can leave some blank
+For some fields there will be a default value,
+If you enter '.', the field will be left blank.
+-----
+Country Name (2 letter code) [AU]:CH
+State or Province Name (full name) [Some-State]:SiChuan
+Locality Name (eg, city) []:Chengdu
+Organization Name (eg, company) [Internet Widgits Pty Ltd]:John.cn
+Organizational Unit Name (eg, section) []:Dev
+Common Name (e.g. server FQDN or YOUR name) []:John
+Email Address []:john@johng.cn
+
+$ openssl rsa -in server.key -out server.key.public
+writing RSA key
+
+$ ll
+total 20
+drwxrwxr-x  2 john john 4096 Apr 23 21:26 ./
+drwxr-xr-x 90 john john 4096 Apr 23 20:55 ../
+-rw-rw-r--  1 john john 1383 Apr 23 21:26 server.crt
+-rw-rw-r--  1 john john 1675 Apr 23 21:25 server.key
+-rw-rw-r--  1 john john 1675 Apr 23 21:26 server.key.public
+```
+
+其中，生成证书的命令提示需要录入一些信息，可以直接回车留空即可，我们这里随便填写了一些。
+
+### 示例代码
+
+根据以上生成的秘钥和证书文件，我们来演示如果使用 `ghttp.Server` 实现一个HTTPS服务。示例代码如下：
+
+```go
+package main
+
+import (
+    "github.com/gogf/gf/v2/frame/g"
+    "github.com/gogf/gf/v2/net/ghttp"
+)
+
+func main() {
+    s := g.Server()
+    s.BindHandler("/", func(r *ghttp.Request) {
+        r.Response.Writeln("来自于HTTPS的：哈喽世界！")
+    })
+    s.EnableHTTPS("server.crt", "server.key")
+    s.SetPort(8000)
+    s.Run()
+}
+```
+
+可以看到，我们直接将之前生成的证书和秘钥文件地址传递给 `EnableHTTPS` 即可，通过 `s.SetPort(8199)` 设置HTTPS的服务端口，当然我们也可以通过 `s.SetHTTPSPort(8199)` 来实现，在单一服务下两者没有区别，当 `WebServer` 需要同时支持 `HTTP` 和 `HTTPS` 服务的时候，两者的作用就不同了，这个特性我们会在后面介绍。随后我们访问页面 [https://127.0.0.1:8199/](https://127.0.0.1:8199/) 来看一下效果：
+
+可以看到浏览器有提示信息，主要是因为我们生成的证书为私有的，非第三方授信企业提供的。浏览器大多会自带一些第三方授信的HTTPS证书机构，这些机构提供的HTTPS证书被浏览器认为是权威的、可信的，才不会出现该提示信息。一般这种第三方权威机构授信证书价格在每年几千到几万人民币不等，感兴趣的朋友可在搜索引擎上了解下。
+
+我们这里直接点击 `Advanced`，然后点击 `Proceed to 127.0.0.1 (unsafe)`，最终可以看到页面输出预期的结果：
+
+## `HTTPS` 与 `HTTP` 支持
+
+我们经常会遇到需要通过HTTP和HTTPS来提供同一个服务的情况，即除了端口和访问协议不一样，其他都是相同的。如果按照传统的使用多 `WebServer` 的方式来运行的话会比较繁琐，为轻松地解决开发者的烦恼， `ghttp` 提供了非常方便的特性：支持 “同一个” `WebServer` 同时支持 `HTTPS` 及 `HTTP` 访问协议。我们先来看一个例子：
+
+```go
+package main
+
+import (
+    "github.com/gogf/gf/v2/frame/g"
+    "github.com/gogf/gf/v2/net/ghttp"
+)
+
+func main() {
+    s := g.Server()
+    s.BindHandler("/", func(r *ghttp.Request) {
+        r.Response.Writeln("您可以同时通过HTTP和HTTPS方式看到该内容！")
+    })
+    s.EnableHTTPS("server.crt", "server.key")
+    s.SetHTTPSPort(443)
+    s.SetPort(80)
+    s.Run()
+}
+```
+
+执行后，通过本地浏览器访问这两个地址 [http://127.0.0.1/](http://127.0.0.1/) 和 [https://127.0.0.1/](https://127.0.0.1/) 都会看到同样的内容（需要注意的是，由于部分系统对于权限的限制，WebServer绑定 `80` 和 `443` 端口需要 `root/管理员` 权限，如果启动报错，可以更改端口号后重新执行即可）。
+
+在本示例中，我们使用了两个方法来开启HTTPS特性：
+
+```go
+func (s *Server) EnableHTTPS(certFile, keyFile string) error
+func (s *Server) SetHTTPSPort(port ...int) error
+```
+
+一个是添加证书及密钥文件，一个是设置HTTPS协议的监听端口，一旦这两个属性被设置了，那么WebServer就会启用HTTPS特性。并且，在示例中也通过 `SetPort` 方法来设置了HTTP服务的监听端口，因此该WebServer将会同时监听指定的HTTPS和HTTP服务端口。
+
+## 使用 `Let’s Encrypt` 免费证书
+
+`SSL免费证书` 机构比较多，如：
+
+1. `Let’s Encrypt`: [https://letsencrypt.org/](https://letsencrypt.org/)
+2. `腾讯云DV SSL 证书`: [https://cloud.tencent.com/product/ssl](https://cloud.tencent.com/product/ssl)
+3. `CloudFlare SSL`: [https://www.cloudflare.com/](https://www.cloudflare.com/)
+4. `StartSSL`: [https://www.startcomca.com/](https://www.startcomca.com/)
+5. `Wosign沃通SSL`: [https://www.wosign.com/](https://www.wosign.com/)
+6. `
+               loovit.net AlphaSSL`: [https://www.lowendtalk.com/entry/register?Target=discussion%2Fcomment%2F2306096](https://www.lowendtalk.com/entry/register?Target=discussion%2Fcomment%2F2306096)
+
+以下以 `Let's Encrypt` 为例，介绍如何申请、使用、续期免费证书。
+
+`Let’s Encrypt` 官网地址： [https://letsencrypt.org/](https://letsencrypt.org/)
+
+以下以 `Ubuntu` 系统为例，如何申请 `Let's Encrypt` 免费证书及在 `GoFrame` 框架下对证书的使用。
+
+### 安装 `Certbot`
+
+`Certbot` 官网地址： [https://certbot.eff.org/](https://certbot.eff.org/)
+
+申请 `Let’s Encrypt` 免费证书需要使用到 `certbot` 工具：
+
+```
+sudo apt-get update
+sudo apt-get install software-properties-common
+sudo add-apt-repository ppa:certbot/certbot
+sudo apt-get update
+sudo apt-get install certbot
+```
+
+### 申请证书
+
+使用以下命令：
+
+```
+certbot certonly --standalone -d 申请域名 --staple-ocsp -m 邮箱地址 --agree-tos
+```
+
+例如：
+
+```
+root@ip-172-31-41-204:~# certbot certonly --standalone -d goframe.org --staple-ocsp -m john@goframe.org --agree-tos
+Saving debug log to /var/log/letsencrypt/letsencrypt.log
+Plugins selected: Authenticator standalone, Installer None
+Starting new HTTPS connection (1): acme-v02.api.letsencrypt.org
+Obtaining a new certificate
+Performing the following challenges:
+http-01 challenge for goframe.org
+Waiting for verification...
+Cleaning up challenges
+
+IMPORTANT NOTES:
+ - Congratulations! Your certificate and chain have been saved at:
+   /etc/letsencrypt/live/goframe.org/fullchain.pem
+   Your key file has been saved at:
+   /etc/letsencrypt/live/goframe.org/privkey.pem
+   Your cert will expire on 2019-01-25. To obtain a new or tweaked
+   version of this certificate in the future, simply run certbot
+   again. To non-interactively renew *all* of your certificates, run
+   "certbot renew"
+ - If you like Certbot, please consider supporting our work by:
+
+   Donating to ISRG / Let's Encrypt:   https://letsencrypt.org/donate
+   Donating to EFF:                    https://eff.org/donate-le
+```
+
+默认情况下，证书会被安装到 `/etc/letsencrypt/`，证书和私钥文件分别为：
+
+```
+/etc/letsencrypt/live/goframe.org/fullchain.pem
+/etc/letsencrypt/live/goframe.org/privkey.pem
+```
+
+### 使用证书
+
+```go
+package main
+
+import (
+    "github.com/gogf/gf/v2/frame/g"
+    "github.com/gogf/gf/v2/net/ghttp"
+)
+
+func main() {
+    s := g.Server()
+    s.BindHandler("/", func(r *ghttp.Request) {
+        r.Response.Writeln("来自于HTTPS的：哈喽世界！")
+    })
+    s.EnableHTTPS(
+        "/etc/letsencrypt/live/goframe.org/fullchain.pem",
+        "/etc/letsencrypt/live/goframe.org/privkey.pem",
+    )
+    s.Run()
+}
+```
+
+### 证书续期
+
+证书默认有效期为 `3个月`，到期后需要手动续期，使用以下命令：
+
+```
+certbot renew
+```
+
+示例1，我们可以使用 `crontab` 定时任务来实现自动续期：
+
+```
+# 每天尝试续期一次，成功后重启`GoFrame`框架运行的WebServer
+0 3 * * * certbot renew --quiet --renew-hook "kill -SIGUSR1 $(pidof 进程名称)"
+```
+
+示例2，如果我们通过 `nginx` 管理证书，那么我们可以这样来设置定时任务：
+
+```
+# 每天尝试续期一次，证书续期需要先关闭80端口的WebServer监听
+0 3 * * * service nginx stop && certbot renew --quiet --renew-hook "service nginx start"
+```
+
+为了防止 `certbot renew` 命令可能的失败导致 `nginx` 无法重新启动，为保证稳定性，可以这样：
+
+```
+# 每天尝试续期一次，证书续期需要先关闭80端口的WebServer监听
+0 3 * * * service nginx stop && certbot renew --quiet --renew-hook "service nginx start"
+5 3 * * * service nginx start
+```

package/skills/goframe-v2/references/WEB/346/234/215/345/212/241/345/274/200/345/217/221//351/253/230/347/272/247/347/211/271/346/200/247/HTTPServer-/347/233/221/346/216/247/346/214/207/346/240/207.md

@@ -0,0 +1,25 @@
+`HTTP Server` 支持监控指标能力，默认是关闭的不影响性能，只有在 `metric` 特性全局开启时该组件才会默认开启监控指标计算和生成功能。
+
+## 指标列表
+
+| **指标名称** | **指标类型** | **指标单位** | **指标描述** |
+| --- | --- | --- | --- |
+| `http.server.request.duration` | `Histogram` | `ms` | 对 `Server` 端请求执行的时间开销分组。 |
+| `http.server.request.duration_total` | `Counter` | `ms` | 每个请求的执行时间总开销。 |
+| `http.server.request.total` | `Counter` |  | 已经执行完毕的请求总数，不包含正在执行的请求数。 |
+| `http.server.request.active` | `Gauge` |  | 当前正在处理的请求数量。 |
+| `http.server.request.body_size` | `Counter` | `bytes` | 请求的字节总大小。 |
+| `http.server.response.body_size` | `Counter` | `bytes` | 返回的字节总大小。 |
+
+## 属性列表
+
+| **Label名称** | **Label描述** | **Label示例** |
+| --- | --- | --- |
+| `server.address` | 接受请求的请求地址。来源于 `Request.Host`，可能是域名也可能是IP地址。 | `goframe.org`<br />`10.0.1.132` |
+| `server.port` | 接受请求的服务端口。同一服务可能有多个端口地址，当前请求连接的是哪个端口就记录哪个端口。 | `8000` |
+| `http.route` | 请求的路由规则。 | `/api/v1/user/:id` |
+| `url.schema` | 请求协议名称。 | `http`; `https` |
+| `network.protocol.version` | 请求的协议版本。 | `1.0`; `1.1` |
+| `http.request.method` | 请求的方法名称。 | `GET`; `POST`; `DELETE` |
+| `error.code` | 请求返回的业务自定义错误码，字符串类型以提高兼容性。 | `-1`; `0`; `51` |
+| `http.response.status_code` | 处理返回的 `HTTP` 状态码。 | `200` |