Enabling Session Persistence 粘性会话

NGINX Docs | HTTP Load Balancing https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/

cookie实现客户端与后端服务器的会话保持, 在一定条件下可以保证同一个客户端访问的都是同一个后端服务器

ngx_http_upstream_session_sticky_module - The Tengine Web Server http://tengine.taobao.org/document_cn/http_upstream_session_sticky_cn.html

该模块是一个负载均衡模块，通过cookie实现客户端与后端服务器的会话保持, 在一定条件下可以保证同一个客户端访问的都是同一个后端服务器。

Example 1

# 默认配置：cookie=route mode=insert fallback=on
upstream foo {
    server 192.168.0.1;
    server 192.168.0.2;
    session_sticky;
}

server {
    location / {
        proxy_pass http://foo;
    }
}

Example 2

#insert + indirect模式：
upstream test {
    session_sticky cookie=uid domain=www.xxx.com fallback=on path=/ mode=insert option=indirect;
    server  127.0.0.1:8080;
}

server {
    location / {
        #在insert + indirect模式或者prefix模式下需要配置session_sticky_hide_cookie
        #这种模式不会将保持会话使用的cookie传给后端服务，让保持会话的cookie对后端透明
        session_sticky_hide_cookie upstream=test;
        proxy_pass http://test;
    }
}

指令

语法：session_sticky [cookie=name] [domain=your_domain] [path=your_path] [maxage=time] [mode=insert|rewrite|prefix] [option=indirect] [maxidle=time] [maxlife=time] [fallback=on|off] [hash=plain|md5]
默认值：session_sticky cookie=route mode=insert fallback=on
上下文：upstream

说明:

本指令可以打开会话保持的功能，下面是具体的参数：

• cookie设置用来记录会话的cookie名称
• domain设置cookie作用的域名，默认不设置
• path设置cookie作用的URL路径，默认不设置
• maxage设置cookie的生存期，默认不设置，即为session cookie，浏览器关闭即失效

• mode设置cookie的模式:

• insert: 在回复中本模块通过Set-Cookie头直接插入相应名称的cookie。

• prefix: 不会生成新的cookie，但会在响应的cookie值前面加上特定的前缀，当浏览器带着这个有特定标识的cookie再次请求时，模块在传给后端服务前先删除加入的前缀，后端服务拿到的还是原来的cookie值，这些动作对后端透明。如："Cookie: NAME=SRV~VALUE"。
• rewrite: 使用服务端标识覆盖后端设置的用于session sticky的cookie。如果后端服务在响应头中没有设置该cookie，则认为该请求不需要进行session sticky，使用这种模式，后端服务可以控制哪些请求需要sesstion sticky，哪些请求不需要。

• option 设置用于session sticky的cookie的选项，可设置成indirect或direct。indirect不会将session sticky的cookie传送给后端服务，该cookie对后端应用完全透明。direct则与indirect相反。

• maxidle设置session cookie的最长空闲的超时时间

• maxlife设置session cookie的最长生存期
• fallback设置是否重试其他机器，当sticky的后端机器挂了以后，是否需要尝试其他机器
• hash 设置cookie中server标识是用明文还是使用md5值，默认使用md5

---

语法: session_sticky_hide_cookie upstream=name;
默认值: none
上下文： server, location

说明：

配合proxy_pass指令使用。用于在insert+indirect模式和prefix模式下删除请求用于session sticky的cookie，这样就不会将该cookie传递给后端服务。upstream表示需要进行操作的upstream名称。

nginx会话保持之sticky模块 - 天生帅才 - 博客园 https://www.cnblogs.com/tssc/p/7481885.html

Module ngx_http_upstream_module http://nginx.org/en/docs/http/ngx_http_upstream_module.html#sticky

Syntax:	sticky cookie name [expires=time] [domain=domain] [httponly] [secure] [path=path]; sticky route $variable ...; sticky learn create=$variable lookup=$variable zone=name:size [timeout=time] [header] [sync];
Default:	—
Context:	upstream

This directive appeared in version 1.5.7.

Enables session affinity, which causes requests from the same client to be passed to the same server in a group of servers. Three methods are available:

cookie

When the cookie method is used, information about the designated server is passed in an HTTP cookie generated by nginx:

upstream backend {
    server backend1.example.com;
    server backend2.example.com;

    sticky cookie srv_id expires=1h domain=.example.com path=/;
}

A request that comes from a client not yet bound to a particular server is passed to the server selected by the configured balancing method. Further requests with this cookie will be passed to the designated server. If the designated server cannot process a request, the new server is selected as if the client has not been bound yet.

The first parameter sets the name of the cookie to be set or inspected. The cookie value is a hexadecimal representation of the MD5 hash of the IP address and port, or of the UNIX-domain socket path. However, if the “route” parameter of the server directive is specified, the cookie value will be the value of the “route” parameter:

upstream backend {
    server backend1.example.com route=a;
    server backend2.example.com route=b;

    sticky cookie srv_id expires=1h domain=.example.com path=/;
}

In this case, the value of the “srv_id” cookie will be either a or b.

Additional parameters may be as follows:

expires=time

Sets the time for which a browser should keep the cookie. The special value max will cause the cookie to expire on “31 Dec 2037 23:55:55 GMT”. If the parameter is not specified, it will cause the cookie to expire at the end of a browser session.

domain=domain

Defines the domain for which the cookie is set. Parameter value can contain variables (1.11.5).

httponly

Adds the HttpOnly attribute to the cookie (1.7.11).

secure

Adds the Secure attribute to the cookie (1.7.11).

path=path

Defines the path for which the cookie is set.

If any parameters are omitted, the corresponding cookie fields are not set.

route

When the route method is used, proxied server assigns client a route on receipt of the first request. All subsequent requests from this client will carry routing information in a cookie or URI. This information is compared with the “route” parameter of the server directive to identify the server to which the request should be proxied. If the “route” parameter is not specified, the route name will be a hexadecimal representation of the MD5 hash of the IP address and port, or of the UNIX-domain socket path. If the designated server cannot process a request, the new server is selected by the configured balancing method as if there is no routing information in the request.

The parameters of the route method specify variables that may contain routing information. The first non-empty variable is used to find the matching server.

Example:

map $cookie_jsessionid $route_cookie {
    ~.+\.(?P<route>\w+)$ $route;
}

map $request_uri $route_uri {
    ~jsessionid=.+\.(?P<route>\w+)$ $route;
}

upstream backend {
    server backend1.example.com route=a;
    server backend2.example.com route=b;

    sticky route $route_cookie $route_uri;
}

Here, the route is taken from the “JSESSIONID” cookie if present in a request. Otherwise, the route from the URI is used.

learn

When the learn method (1.7.1) is used, nginx analyzes upstream server responses and learns server-initiated sessions usually passed in an HTTP cookie.

upstream backend {
   server backend1.example.com:8080;
   server backend2.example.com:8081;

   sticky learn
          create=$upstream_cookie_examplecookie
          lookup=$cookie_examplecookie
          zone=client_sessions:1m;
}

In the example, the upstream server creates a session by setting the cookie “EXAMPLECOOKIE” in the response. Further requests with this cookie will be passed to the same server. If the server cannot process the request, the new server is selected as if the client has not been bound yet.

The parameters create and lookup specify variables that indicate how new sessions are created and existing sessions are searched, respectively. Both parameters may be specified more than once, in which case the first non-empty variable is used.

Sessions are stored in a shared memory zone, whose name and size are configured by the zoneparameter. One megabyte zone can store about 4000 sessions on the 64-bit platform. The sessions that are not accessed during the time specified by the timeout parameter get removed from the zone. By default, timeout is set to 10 minutes.

The header parameter (1.13.1) allows creating a session right after receiving response headers from the upstream server.

The sync parameter (1.13.8) enables synchronization of the shared memory zone.

This directive is available as part of our commercial subscription.

Syntax:	sticky_cookie_insert name [expires=time] [domain=domain] [path=path];
Default:	—
Context:	upstream

This directive is obsolete since version 1.5.7. An equivalent sticky directive with a new syntax should be used instead:

sticky cookie name [expires=time] [domain=domain] [path=path];