代理

Proxy 提供 HTTP/WebSocket 反向代理中间件。它会使用配置的负载均衡技术将请求转发到上游服务器。

所有核心中间件都位于 middleware 包中：

import "github.com/labstack/echo/v5/middleware"

用法

url1, err := url.Parse("http://localhost:8081")
if err != nil {
  e.Logger.Error("failed to parse url", "error", err)
}
url2, err := url.Parse("http://localhost:8082")
if err != nil {
  e.Logger.Error("failed to parse url", "error", err)
}
e.Use(middleware.Proxy(middleware.NewRoundRobinBalancer([]*middleware.ProxyTarget{
  {
    URL: url1,
  },
  {
    URL: url2,
  },
})))

自定义配置

e := echo.New()
e.Use(middleware.ProxyWithConfig(middleware.ProxyConfig{}))

配置

ProxyConfig · github.com/labstack/echo/v5@5196b9b

字段说明由英文源码注释生成。

包源码中的字段

字段	类型	说明	源码
Skipper	Skipper	Skipper defines a function to skip middleware.	L31
Balancer	ProxyBalancer	Balancer defines a load balancing technique. Required.	L35
RetryCount	int	RetryCount defines the number of times a failed proxied request should be retried using the next available ProxyTarget. Defaults to 0, meaning requests are never retried.	L39
RetryFilter	func(c *echo.Context, e error) bool	RetryFilter defines a function used to determine if a failed request to a ProxyTarget should be retried. The RetryFilter will only be called when the number of previous retries is less than RetryCount. If the function returns true, the request will be retried. The provided error indicates the reason for the request failure. When the ProxyTarget is unavailable, the error will be an instance of echo.HTTPError with a code of http.StatusBadGateway. In all other cases, the error will indicate an internal error in the Proxy middleware. When a RetryFilter is not specified, all requests that fail with http.StatusBadGateway will be retried. A custom RetryFilter can be provided to only retry specific requests. Note that RetryFilter is only called when the request to the target fails, or an internal error in the Proxy middleware has occurred. Successful requests that return a non-200 response code cannot be retried.	L53
ErrorHandler	func(c *echo.Context, err error) error	ErrorHandler defines a function which can be used to return custom errors from the Proxy middleware. ErrorHandler is only invoked when there has been either an internal error in the Proxy middleware or the ProxyTarget is unavailable. Due to the way requests are proxied, ErrorHandler is not invoked when a ProxyTarget returns a non-200 response. In these cases, the response is already written so errors cannot be modified. ErrorHandler is only invoked after all retry attempts have been exhausted.	L62
Rewrite	map[string]string	Rewrite defines URL path rewrite rules. The values captured in asterisk can be retrieved by index e.g. $1, $2 and so on. Examples: "/old": "/new", "/api/*": "/$1", "/js/*": "/public/javascripts/$1", "/users/*/orders/*": "/user/$1/order/$2",	L71
RegexRewrite	map[*regexp.Regexp]string	RegexRewrite defines rewrite rules using regexp.Rexexp with captures Every capture group in the values can be retrieved by index e.g. $1, $2 and so on. Example: "^/old/[0.9]+/": "/new", "^/api/.+?/(.*)": "/v2/$1",	L78
ContextKey	string	Context key to store selected ProxyTarget into context. Optional. Default value "target".	L82
Transport	http.RoundTripper	To customize the transport to remote. Examples: If custom TLS certificates are required.	L86
ModifyResponse	func(*http.Response) error	ModifyResponse defines function to modify response from ProxyTarget.	L89

包源码中的函数

类型	源码
func Proxy(balancer ProxyBalancer) echo.MiddlewareFunc	L292
func ProxyWithConfig(config ProxyConfig) echo.MiddlewareFunc	L301

默认配置

名称	值
Skipper	DefaultSkipper
ContextKey	target

基于正则表达式的规则

对于代理请求的高级重写，也可以使用正则表达式定义规则。可以用 () 定义普通捕获组， 并在重写后的路径中按索引引用（$1、$2 等）。

RegexRewrite 可以和普通 Rewrite 规则组合使用。

e.Use(middleware.ProxyWithConfig(middleware.ProxyConfig{
  Balancer: rrb,
  Rewrite: map[string]string{
    "^/v1/*": "/v2/$1",
  },
  RegexRewrite: map[*regexp.Regexp]string{
    regexp.MustCompile("^/foo/([0-9].*)"):  "/num/$1",
    regexp.MustCompile("^/bar/(.+?)/(.*)"): "/baz/$2/$1",
  },
}))

完整示例请参见反向代理 cookbook。

Echo 安全更新 (v5.4.0 / v4.16.0)

Proxy 从 Context#Scheme() 设置 X-Forwarded-Proto，并在转发前删除 X-Forwarded-Ssl、X-Forwarded-Protocol 和 X-Url-Scheme。v5 还从 Context#RealIP() 设置 X-Real-IP。对于 nginx → Echo Proxy → 上游服务的链路，请按可信代理配置协议和 IP 提取器。