Skip to content

Commit 82fc302

Browse files
andrewshanandrewshan
authored
调整readme和构建脚本，删除nginx代码 (#14)
* feat：调整构建脚本，删除nginx代码 * 使用rm -f防止删除失败 * feat; 无需执行清理逻辑 * feat: 修改nginx限流的问题 * feat： 重新编写readme
1 parent 8f6cdae commit 82fc302

File tree

4 files changed

+158
-183
lines changed

4 files changed

+158
-183
lines changed

‎README.md

Lines changed: 96 additions & 182 deletions
Original file line numberDiff line numberDiff line change
@@ -1,195 +1,109 @@
1-
# Nginx Gateway
2-
## Table of Contents
3-
4-
* [What is nginx-polaris?](#what-is-nginx-polaris)
5-
* [Supported Nginx Version](#supported-nginx-version)
6-
* [Installation Instructions](#installation-instructions)
7-
* [Features And Usage](#features-and-usages)
8-
* [Directives Explanation](#directives-explanation)
1+
# Nginx网关
92

103
---
114

12-
## What is nginx-polaris?
13-
nginx-polaris is a nginx module which works as a load-balanceer based on PolarisMesh. No hardcoded ip is remained after embedding nginx-polaris with your nginx, which makes your nginx configuration file easy to maintain. What's more, nginx-polaris provided various functionality which PolarisMesh can provide.
5+
## 什么是nginx网关
146

15-
## Supported Nginx Version
16-
nginx version above 1.4.7 will have no problem.
7+
Nginx网关是一个微服务网关。在原生Nginx的基础上，通过对接北极星服务治理中心，扩展nginx的module，提供微服务场景下所需要使用的增强能力，如对接注册中心、访问限流、流量调度、熔断降级、动态配置等。
178

18-
## Installation Instructions
19-
1. If you want to try it asap, use the `nginx` binary (nginx version: nginx/1.18.0) we compiled for you in release package and put it in `/usr/local/nginx/sbin` which is the default working directory for nginx. Then you can jump to [Features And Usage](#features-and-usages) part.
20-
2. First you need to setup a [PolarisMesh server](https://github.com/PolarisMesh/polaris).
21-
3. Compile and package [PolarisCpp](https://github.com/PolarisMesh/polaris-cpp). Unzip `polaris_cpp_sdk.tar.gz` and move the whole folder to your compile workspace, such as `/path/to/workspace/polaris_cpp_sdk`
22-
4. Move file `config` to `/path/to/workspace/polaris_cpp_sdk`, move folder `nginx_polaris_limit_module` and `nginx_polaris_module` to `/path/to/workspace`.
23-
5. Download opensource [Nginx](http://nginx.org/en/download.html) to your workspace, so the final file structure of your workspace looks like this:
24-
```
25-
|-- nginx-1.19.2
26-
| |-- CHANGES
27-
| |-- CHANGES.ru
28-
| |-- LICENSE
29-
| |-- Makefile
30-
| |-- README
31-
| |-- auto
32-
| |-- build
33-
| |-- build.sh
34-
| |-- conf
35-
| |-- configure
36-
| |-- contrib
37-
| |-- html
38-
| |-- man
39-
| |-- objs
40-
| |-- polaris_client
41-
| `-- src
42-
|-- nginx_polaris_limit_module
43-
| |-- config
44-
| |-- ngx_http_polaris_limit_module.cpp
45-
| `-- ngx_http_polaris_limit_module.h
46-
|-- nginx_polaris_module
47-
| |-- config
48-
| |-- ngx_http_upstream_polaris_module.cpp
49-
| |-- ngx_http_upstream_polaris_module.h
50-
| |-- ngx_http_upstream_polaris_wrapper.cpp
51-
| `-- ngx_stream_upstream_polaris_module.cpp
52-
`-- polaris_cpp_sdk
53-
|-- config
54-
|-- dlib
55-
|-- include
56-
`-- slib
57-
```
58-
5. Run following command to build nginx with nginx-polaris module.
59-
```
60-
./configure \
61-
--add-module=/path/to/workspace/nginx_polaris_limit_module \
62-
--add-module=/path/to/workspace/nginx_polaris_module \
63-
--add-module=/path/to/workspace/polaris_cpp_sdk \
64-
--with-stream
65-
make install
66-
```
9+
## 支持的nginx版本
10+
11+
当前支持 nginx 的版本为>=1.4.7
12+
13+
## 安装说明
14+
15+
### 操作系统支持
16+
17+
当前仅支持linux操作系统，linux下要求GCC版本>=4.8.5
6718

68-
## Features And Usages
69-
First you need to create a name by Polaris Server, we will take `Test:test.servicename` as an example, in which `Test` represents Polaris namespace and `test.servicename` represents Polaris name.
70-
And you should also configure the polaris server address by placing `polairs.yaml` within the same folder as nginx binary executable file.
71-
```
72-
global:
73-
#描述:对接polaris server的相关配置
74-
serverConnector:
75-
#描述:server列表，由于SDK在运行过程中可以通过接口定时拉取最新server列表，因此这里填的是初始的地址
76-
#类型:list
77-
#默认值:代理模式，默认为127.0.0.1:8888（本地agent地址）;直连模式，无默认值
78-
addresses:
79-
- 127.0.0.1:8091 # 埋点地址
80-
```
81-
### L4 and L7 load balance.
82-
Add below to your nginx configuration under http or stream namespace, L4 or L7 reverse proxy is ready to go and you are no longer bothered by hardcoded ip.
83-
```
84-
upstream test_upstream {
85-
polaris service_namespace=Test service_name=test.servicename timeout=1.5;
86-
server 10.223.130.162:6000;
87-
}
88-
```
89-
You can also use nginx native variable for runtime configuration like below. ***This feature is supported only in L4 load balance***
90-
```
91-
upstream test_upstream {
92-
polaris service_namespace=$http_namespace service_name=$http_name timeout=1.5;
93-
server 10.223.130.162:6000;
94-
}
95-
```
96-
### Business-Level Fail Status Report
97-
***This feature is only supported in L4 load balance.***
98-
If you have already read the doc of [PolarisCpp](https://github.com/PolarisMesh/polaris-cpp), you will find out that Polaris has circuit breaker feature which relies on the business-level report on failed requests. Nginx-polaris has already report failed requests which are led by network error. In order to make it better, Nginx-polaris also supports business-level failed requests report, this feature is only activated in L4 load balance mode and developer needs to configure failed status code. For the configuration below, polaris Nginx module will report fail when backend server returns ***502*** or ***405*** to Nginx.
99-
```
100-
upstream test_upstream {
101-
polaris service_namespace=Test service_name=test.servicename timeout=1.5 fail_report=502,405;
102-
server 10.223.130.162:6000;
103-
}
104-
```
105-
### Session Sticky
106-
Nginx-polaris module supports various load balance mode. Developer can use Nginx-polaris module to achieve session sticky. Add configuration like below, session sticky is achieved and all the requests from same remote_addr will be proxied to the same backed server.
107-
```
108-
upstream test_upstream {
109-
polaris service_namespace=Test service_name=test.servicename timeout=1.5 mode=2 key=$remote_addr;
110-
server 10.223.130.162:6000;
111-
}
112-
```
113-
### Dynamic Route
114-
***This feature is only supported in L4 load balance.***
115-
1. You need to learn about what dynamic route is from [PolarisCpp](https://github.com/PolarisMesh/polaris-cpp) first.
116-
2. Tured on dynamic route by set ***dr=on***.
117-
3. Set ***metadata*** key-value list to filter the value specified by http header, url arguments or cookies.
118-
4. For example, if you configured dynamic route rules on Polaris Console like below:
119-
![image](https://user-images.githubusercontent.com/7314436/130551250-c4b52235-59c6-456d-832b-74263f6a4ebd.png)
120-
And you add upstream configuration like below:
121-
```
122-
upstream test_upstream {
123-
polaris service_namespace=Test service_name=polaris.demo timeout=1.5 dr=on metadata=[key1,key2];
124-
server 127.0.0.1:8000;
125-
}
126-
```
127-
For all three kinds of requests like below, will be routed to instances which have ***test:true*** metadata.
128-
```
129-
POST /recv?key1=check HTTP/1.1
130-
Host: 127.0.0.1
131-
{
132-
}
133-
```
134-
```
135-
POST /recv HTTP/1.1
136-
key1: check
137-
Host: 127.0.0.1
138-
{
139-
}
140-
```
141-
```
142-
POST /recv HTTP/1.1
143-
Cookie: key1=check; x_host_key=176d798f8b4-c8c30f5e7d8ebe8a1bab15661f32730ecfb156e5;
144-
Host: 127.0.0.1
145-
{
146-
}
147-
```
148-
Likewise, for all three kinds of requests like below, will be routed to instances which have ***test:false*** metadata.
149-
```
150-
POST /recv?key2=nonce HTTP/1.1
151-
Host: 127.0.0.1
152-
{
153-
}
154-
```
15519
```
156-
POST /recv HTTP/1.1
157-
key2: nonce
158-
Host: 127.0.0.1
159-
{
160-
}
20+
[sam@VM_15_118_centos ~/testgen]$ gcc --version
21+
gcc (GCC) 4.8.5 20150623 (Red Hat 4.8.5-39)
22+
Copyright (C) 2015 Free Software Foundation, Inc.
23+
This is free software; see the source for copying conditions. There is NO
24+
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
16125
```
26+
27+
### 下载安装包
28+
29+
可以直接从[releases](https://github.com/polarismesh/nginx-gateway/releases)下载最新的nginx网关安装包。
30+
31+
### 【可选】编译生成安装包
32+
33+
用户也可以通过源码编译的方式，生成安装包。
34+
35+
- 安装依赖项：在编译之前，需要先安装依赖项。通过执行```yum install autoconf automake libtool curl make g++ unzip```进行安装。
36+
37+
- 下载源码包：可以直接从[releases](https://github.com/polarismesh/nginx-gateway/releases)下载最新的nginx网关源码包。
38+
39+
- 编译安装：解压源码包。执行以下命令构建，构建过程需要连接网络下载依赖，请务必保证外网连通性。
40+
41+
```shell
42+
cd build
43+
bash build.sh
44+
```
45+
46+
- 获取编译结果：构建成功后，在源码包的根目录下，可以获取安装包：```nginx-gateway-release-*.tar.gz```
47+
48+
### 【可选】修改端口号
49+
50+
nginx默认端口号为80，如需修改端口号，可以通过编辑conf/nginx.conf配置文件进行修改。
51+
16252
```
163-
POST /recv HTTP/1.1
164-
Cookie: key2=nonce; x_host_key=176d798f8b4-c8c30f5e7d8ebe8a1bab15661f32730ecfb156e5;
165-
Host: 127.0.0.1
166-
{
167-
}
53+
http {
54+
server {
55+
listen 80; #这里修改成希望监听的端口号
56+
}
57+
}
16858
```
169-
### Metadata Route
170-
***This feature is only supported in L4 load balance.***
171-
Metadata route is used when user want to control requests to be routed to certain instance which has certain metadata.
172-
1. Turned on metadata route by set ***mr=on***.
173-
2. Set ***metadata*** key-value list to filter the value specified by http header, url arguments or cookies.
174-
3. Specify metadata route fail over mode.
175-
For example, if you add upstream configuration like below, all requests will be routed to instances which match the ***key2:value*** or ***key3:value*** in their header, url arguments or cookies.
59+
60+
### 运行安装包
61+
62+
解压安装包，并运行命令启动nginx网关。
63+
17664
```
177-
upstream test_upstream {
178-
polaris service_namespace=Test service_name=polaris.demo timeout=1.5 mr=on metadata=[key2,key3];
179-
server 127.0.0.1:8000;
180-
}
65+
tar xf nginx-gateway-release-*.tar.gz
66+
cd nginx-gateway-release-*/sbin
67+
bash start.sh
18168
```
182-
## Directives Explanation
183-
| Parameter | Necessary | Comment | Default |
184-
| :------------- | :----------: | -----------: | :------------- |
185-
| service_namespace | Y | Polaris namespace | "" |
186-
| service_name | Y | Polaris service name| "" |
187-
| timeout | N | Timeout for get rs from polaris name | 1 seconds |
188-
| mode | N| Load balance algorithm| 0 |
189-
| key | N | Hash key when mode equals 2 or 3 | "" |
190-
| dr | N | Switch for dynamic route | off |
191-
| mr | N | Switch for metadata route| off |
192-
| mr_mode | N | metadata route fail over mode | 0 |
193-
| fail_report | N | Business-level fail report status code | "" |
194-
| max_tries | N | Limits the number of tries for request to backend ip | 2 |
69+
70+
## 使用指南
71+
72+
### 使用访问限流功能
73+
74+
- 安装北极星
75+
76+
参考[安装指南](https://polarismesh.cn/zh/doc/%E5%BF%AB%E9%80%9F%E5%85%A5%E9%97%A8/%E5%AE%89%E8%A3%85%E6%9C%8D%E5%8A%A1%E7%AB%AF/%E5%AE%89%E8%A3%85%E5%8D%95%E6%9C%BA%E7%89%88.html#%E5%8D%95%E6%9C%BA%E7%89%88%E5%AE%89%E8%A3%85)进行安装。
77+
78+
- 配置限流规则
79+
80+
在北极星可视化控制台上配置限流规则，比如针对uri为```/test```的请求，限制每秒只能100QPS。参考[限流使用指南](https://polarismesh.cn/zh/doc/%E4%BD%BF%E7%94%A8%E6%8C%87%E5%8D%97/%E8%AE%BF%E9%97%AE%E9%99%90%E6%B5%81/%E5%8D%95%E6%9C%BA%E9%99%90%E6%B5%81.html#%E5%8D%95%E6%9C%BA%E9%99%90%E6%B5%81)。
81+
82+
- 修改nginx配置
83+
84+
通过修改nginx中的location，添加polaris_rate_limiting配置，启用北极星限流功能。
85+
```
86+
http {
87+
server {
88+
location / {
89+
polaris_rate_limiting namespace=default service=testcpp;
90+
}
91+
}
92+
}
93+
```
94+
95+
polaris_rate_limiting参数说明：
96+
97+
| 参数名 | 说明 | 是否必选 |
98+
| --------- | -------------------------------- | ----------------- |
99+
| service | 服务名，与限流规则服务名对应 | 是 |
100+
| namespace | 命名空间，与限流规则命名空间对应 | 否，不填为default |
101+
102+
- 重启nginx
103+
104+
```
105+
cd nginx-gateway-release-*/sbin
106+
bash stop.sh
107+
bash start.sh
108+
```
195109

‎build/build.sh

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,6 @@ curl http://nginx.org/download/nginx-1.18.0.tar.gz -o nginx-1.18.0.tar.gz
1515
tar xf nginx-1.18.0.tar.gz
1616
cp nginx/make nginx-1.18.0/auto/
1717

18-
1918
pushd polaris-cpp
2019
make
2120
make package
@@ -41,6 +40,8 @@ chmod +x configure
4140
--with-stream
4241
make
4342
make install
43+
cp ../nginx/start.sh ../../$folder_name/sbin/start.sh
44+
cp ../nginx/stop.sh ../../$folder_name/sbin/stop.sh
4445
popd
4546

4647
pushd ..

‎third_party/nginx/start.sh

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
#!/bin/bash
2+
3+
curpath=$(pwd)
4+
5+
if [ "${0:0:1}" == "/" ]; then
6+
dir=$(dirname "$0")
7+
else
8+
dir=$(pwd)/$(dirname "$0")
9+
fi
10+
11+
cd $dir
12+
13+
function log_date() {
14+
echo $(date "+%Y-%m-%dT%H:%M:%S")
15+
}
16+
17+
function log_info() {
18+
echo -e "\033[32m\033[01m$(log_date)\tinfo\t$1 \033[0m"
19+
}
20+
21+
pids=$(ps -ef | grep -w "nginx: master" | grep -v "grep" | awk '{print $2}')
22+
array=($pids)
23+
if [ "${#array[@]}" == "0" ]; then
24+
log_info "start nginx"
25+
nohup ./nginx -c conf/nginx.conf >> ../logs/stdout 2>&1
26+
fi
27+
28+
#------------------------------------------------------
29+
30+
cd $curpath

‎third_party/nginx/stop.sh

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
#!/bin/bash
2+
3+
curpath=$(pwd)
4+
5+
if [ "${0:0:1}" == "/" ]; then
6+
dir=$(dirname "$0")
7+
else
8+
dir=$(pwd)/$(dirname "$0")
9+
fi
10+
11+
cd $dir
12+
13+
function log_date() {
14+
echo $(date "+%Y-%m-%dT%H:%M:%S")
15+
}
16+
17+
function log_info() {
18+
echo -e "\033[32m\033[01m$(log_date)\tinfo\t$1 \033[0m"
19+
}
20+
21+
pids=$(ps -ef | grep -w "nginx: master" | grep -v "grep" | awk '{print $2}')
22+
array=($pids)
23+
for pid in ${array[@]}; do
24+
log_info "stop nginx: pid=$pid"
25+
kill -15 $pid
26+
done
27+
28+
#------------------------------------------------------
29+
30+
cd $curpath

0 commit comments

Comments
 (0)