自 自在知识库
首页归档分类标签图谱关于
Admin Core

新建 Gateway 网关项目

Yarp Gateway 是基于 YARPhttps://microsoft.github.io/reverse-proxy/ 构建的 API 网关项目模板，主要用于统一接入后端服务，实现请求转发、负载均衡、动态配置等能力。

· 22 分钟阅读 ·更新于 2026.06.13

项目介绍

Yarp Gateway 是基于 YARP 构建的 API 网关项目模板，主要用于统一接入后端服务，实现请求转发、负载均衡、动态配置等能力。

功能特性

1. 反向代理

网关可以接收客户端请求，并根据路由规则将请求转发到对应的后端服务。

例如：

1
2
客户端请求：/api/admin/user
网关转发：http://localhost:18010/api/admin/user

2. 负载均衡

支持在多个后端服务实例之间分配请求，提高系统的可扩展性和可靠性。

支持的负载均衡策略可参考 YARP 官方文档，常见策略包括：

  • RoundRobin
  • Random
  • LeastRequests
  • PowerOfTwoChoices
  • FirstAlphabetical

示例：

1
"LoadBalancingPolicy": "RoundRobin"

3. 动态配置

支持在线动态添加和修改以下配置：

  • 集群配置
  • 路由绑定
  • 域名绑定
  • HTTPS 证书配置

配置修改后可即时生效，无需重启网关服务。

更多功能请参考 YARP 官方文档：
https://microsoft.github.io/reverse-proxy/

安装或升级模板

安装模板

1
dotnet new install ZhonTai.Template.Gateway

升级模板命令与安装模板命令相同。

安装指定版本

1
dotnet new install ZhonTai.Template.Gateway::10.1.0

查看模板帮助

1
dotnet new MyGateway -h

模板参数说明：

参数 简写 类型 默认值 说明
--port -p int 16010 网关启动端口

示例：

1
dotnet new MyGateway -h

输出示例：

1
2
3
-p, --port port   Port settings
                    类型: int
                    默认: 16010

卸载模板

1
dotnet new uninstall ZhonTai.Template.Gateway

创建网关项目

使用默认端口创建项目

默认网关端口为 16010。

1
dotnet new MyGateway -n MyCompanyName.MyGateway

指定网关端口创建项目

1
dotnet new MyGateway -n MyCompanyName.MyGateway -p 16010

参数说明：

参数 说明
-n 指定项目名称
-p 指定网关启动端口

配置文件说明

appsettings.json

appsettings.json 是应用程序主配置文件，主要包含以下配置：

  • 日志配置
  • 服务监听地址
  • YARP 路由配置
  • YARP 集群配置
  • 网关模块配置
  • 健康检查配置

示例配置如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Urls": "http://*:16010",
  "ReverseProxy": {
    "Routes": {
      "admin": {
        "ClusterId": "admin",
        "Match": {
          "Path": "/api/admin/{**catch-all}",
          "Hosts": []
        }
      },
      "admin-doc": {
        "ClusterId": "admin",
        "Match": {
          "Path": "/doc/admin/{**catch-all}",
          "Hosts": []
        }
      },
      "admin-file": {
        "ClusterId": "admin",
        "Match": {
          "Path": "/upload/{**catch-all}",
          "Hosts": []
        }
      },
      "dev": {
        "ClusterId": "dev",
        "Match": {
          "Path": "/api/dev/{**catch-all}",
          "Hosts": []
        }
      },
      "dev-doc": {
        "ClusterId": "dev",
        "Match": {
          "Path": "/doc/dev/{**catch-all}",
          "Hosts": []
        }
      },
      "sys": {
        "ClusterId": "admin",
        "Match": {
          "Path": "/api/sys/{**catch-all}",
          "Hosts": []
        }
      },
      "sys-doc": {
        "ClusterId": "admin",
        "Match": {
          "Path": "/doc/sys/{**catch-all}",
          "Hosts": []
        }
      },
      "biz": {
        "ClusterId": "biz",
        "Match": {
          "Path": "/api/biz/{**catch-all}",
          "Hosts": []
        }
      },
      "biz-doc": {
        "ClusterId": "biz",
        "Match": {
          "Path": "/doc/biz/{**catch-all}",
          "Hosts": []
        }
      },
      "mem": {
        "ClusterId": "mem",
        "Match": {
          "Path": "/api/mem/{**catch-all}",
          "Hosts": []
        }
      },
      "mem-doc": {
        "ClusterId": "mem",
        "Match": {
          "Path": "/doc/mem/{**catch-all}",
          "Hosts": []
        }
      }
    },
    "Clusters": {
      "admin": {
        "Destinations": {
          "destination1": {
            "Address": "http://localhost:18010"
          }
        },
        "LoadBalancingPolicy": "RoundRobin"
      },
      "dev": {
        "Destinations": {
          "destination1": {
            "Address": "http://localhost:18020"
          }
        },
        "LoadBalancingPolicy": "RoundRobin"
      },
      "biz": {
        "Destinations": {
          "destination1": {
            "Address": "http://localhost:19010"
          }
        },
        "LoadBalancingPolicy": "RoundRobin"
      },
      "mem": {
        "Destinations": {
          "destination1": {
            "Address": "http://localhost:20010"
          }
        },
        "LoadBalancingPolicy": "RoundRobin"
      }
    }
  },
  "GatewayConfig": {
    "ModuleList": [
      {
        "Name": "权限接口文档",
        "Url": "/doc/admin/index.html"
      },
      {
        "Name": "系统接口文档",
        "Url": "/doc/sys/index.html"
      },
      {
        "Name": "开发接口文档",
        "Url": "/doc/dev/index.html"
      },
      {
        "Name": "业务接口文档",
        "Url": "/doc/biz/index.html"
      },
      {
        "Name": "会员接口文档",
        "Url": "/doc/mem/index.html"
      }
    ],
    "HealthChecks": {
      "Enable": true,
      "Path": "/health"
    }
  }
}

appsettings.json 配置说明

基础配置

1
2
"AllowedHosts": "*",
"Urls": "http://*:16010"
配置项 说明
AllowedHosts 允许访问的主机名，* 表示允许所有主机
Urls 网关监听地址和端口

ReverseProxy 配置

ReverseProxy 是 YARP 的核心配置节点，包含：

  • Routes：路由配置
  • Clusters：集群配置
1
2
3
4
"ReverseProxy": {
  "Routes": {},
  "Clusters": {}
}

Routes 路由配置

路由用于定义客户端请求如何匹配到后端服务集群。

示例：

1
2
3
4
5
6
7
"admin": {
  "ClusterId": "admin",
  "Match": {
    "Path": "/api/admin/{**catch-all}",
    "Hosts": []
  }
}

配置说明：

配置项 说明
admin 路由名称，全局唯一
ClusterId 对应的集群 ID
Match.Path 请求路径匹配规则
Match.Hosts 主机匹配规则，空数组表示不限制 Host

路径匹配示例

1
"Path": "/api/admin/{**catch-all}"

表示匹配所有以 /api/admin/ 开头的请求。

例如：

1
2
3
/api/admin/user
/api/admin/role/page
/api/admin/menu/tree

都会匹配该路由。

Clusters 集群配置

集群用于定义后端服务地址和负载均衡策略。

示例：

1
2
3
4
5
6
7
8
"admin": {
  "Destinations": {
    "destination1": {
      "Address": "http://localhost:18010"
    }
  },
  "LoadBalancingPolicy": "RoundRobin"
}

配置说明：

配置项 说明
admin 集群名称，需要与路由中的ClusterId 对应
Destinations 后端服务地址列表
Address 后端服务地址
LoadBalancingPolicy 负载均衡策略

模块路由说明

当前示例中配置了以下模块：

模块 路由路径 文档路径 后端服务地址
权限管理 /api/admin/{**catch-all} /doc/admin/{**catch-all} http://localhost:18010
系统管理 /api/sys/{**catch-all} /doc/sys/{**catch-all} http://localhost:18010
开发管理 /api/dev/{**catch-all} /doc/dev/{**catch-all} http://localhost:18020
业务管理 /api/biz/{**catch-all} /doc/biz/{**catch-all} http://localhost:19010
会员管理 /api/mem/{**catch-all} /doc/mem/{**catch-all} http://localhost:20010

GatewayConfig 网关配置

GatewayConfig 用于配置网关自身功能。

ModuleList 模块列表

用于配置网关首页或接口文档入口。

1
2
3
4
5
6
7
8
9
10
"ModuleList": [
  {
    "Name": "权限接口文档",
    "Url": "/doc/admin/index.html"
  },
  {
    "Name": "系统接口文档",
    "Url": "/doc/sys/index.html"
  }
]

配置说明：

配置项 说明
Name 文档名称
Url 文档访问地址

HealthChecks 健康检查

用于配置网关健康检查接口。

1
2
3
4
"HealthChecks": {
  "Enable": true,
  "Path": "/health"
}

配置说明：

配置项 说明
Enable 是否启用健康检查
Path 健康检查访问路径

健康检查访问地址示例：

1
http://localhost:16010/health

launchSettings.json

launchSettings.json 是开发环境启动配置文件，主要用于配置：

  • 启动方式
  • 启动端口
  • 环境变量
  • 是否启动浏览器
  • IIS Express 配置

示例配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "profiles": {
    "MyGateway.Host": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      },
      "dotnetRunMessages": true,
      "applicationUrl": "http://localhost:16010"
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  },
  "$schema": "https://json.schemastore.org/launchsettings.json",
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:16010",
      "sslPort": 0
    }
  }
}

launchSettings.json 配置说明

配置项 说明
profiles 启动配置集合
commandName 启动方式，Project 表示直接启动项目
launchBrowser 启动时是否自动打开浏览器
environmentVariables 环境变量配置
ASPNETCORE_ENVIRONMENT ASP.NET Core 运行环境
applicationUrl 应用启动地址
iisSettings IIS Express 配置

启动项目

进入项目目录后执行：

1
dotnet run

启动成功后访问：

1
http://localhost:16010

健康检查地址：

1
http://localhost:16010/health

常用命令汇总

操作 命令
安装模板 dotnet new install ZhonTai.Template.Gateway
安装指定版本 dotnet new install ZhonTai.Template.Gateway::10.1.0
升级模板 dotnet new install ZhonTai.Template.Gateway
查看帮助 dotnet new MyGateway -h
卸载模板 dotnet new uninstall ZhonTai.Template.Gateway
创建项目 dotnet new MyGateway -n MyCompanyName.MyGateway
指定端口创建项目 dotnet new MyGateway -n MyCompanyName.MyGateway -p 16010
启动项目 dotnet run

参考文档

#中台/搭建网关