插件版接入指南

注意：

💡 目前暂不支持 HTTP 响应头中包含CSP策略（Content-Security-Policy）的用户站点。如果此类站点需要接入云服务，请先禁用该响应头。

1 下载插件

在购买服务后，请使用收到的账号登录 https://console.riveryun.com, 并通过站点配置页面右上方的下载插件按钮，将插件的安装文件 keeper-lua.tar.gz 下载到本地，解压后得到预编译文件 keeper-lua_v1.5.0_amd64_debian.deb 和源码文件 keeper-lua_v1.5.0_source.tar.gz 。

请选择一种插件文件并复制到 Nginx 所在的操作系统中，然后按照下面提供的方法，完成对 OpenResty 服务器的插件安装。

提示：

💡 如果您的 Nginx 运行在基于 Debian 的发行版操作系统上，则可以使用任意一种方法进行安装。其他操作系统请使用源码包进行安装。以下内容将基于 Debian 的操作系统上运行 OpenResty 为例。

2 安装插件

首先确保系统中已安装好 OpenResty，安装方法可参考官方安装说明。

2.1 使用预编译包安装

提示：

💡 如果 OpenResty 的实际安装路径不是在官方默认路径，则需要添加以下搜索路径到 nginx.conf 中，确保 OpenResty 能找到相应 Lua 文件。

​ lua_package_path "/usr/local/openresty/lualib/?.lua;;";

运行下面命令即可完成安装。

dpkg -i keeper-lua_v1.5.0_amd64_debian.deb

2.2 使用源码包安装

确保 Lua 库头文件已经存在于以下路径：

/usr/local/openresty/luajit/include/luajit-2.1/

解压源码包并复制到 openresty 目录下。

tar -xf keeper-lua_v1.5.0_source.tar.gz
cd keeper-lua/
sudo cp -r ./lib/resty/* /usr/local/openresty/lualib/resty/
sudo cp -r ./riversec /usr/local/openresty/lualib

3 配置OpenResty服务器

配置 OpenResty 服务器需要三个步骤：

❶ 创建站点防护配置，并获得配置ID。

❷ 备份和修改配置文件。

❸ 重新启动 OpenResty。

3.1 获得站点防护配置ID

站点配置是指您在云服务配置界面中创建的安全防护方案（请登录云服务配置界面，并根据使用手册 > 2 站点配置中的描述进行创建）。每个方案都有一个唯一的站点配置 ID 号（例如创建了一个名称为 website_protection 的方案，其 ID 号为 revol_b2rblvr25zo6lrcw)， 如下图所示。

将ID号复制下来，以便稍后使用。

3.2 备份和修改配置文件

首先将原有 OpenResty 配置文件备份，以便在需要时恢复。

假设原有 OpenResty 配置文件如下所示。如果想对站点 website1.com 的路径 location / 进行保护，需要在下面几个配置块中（分别是 http 配置块下、server website1 配置块下、以及 location / 配置块下）分别插入对应的三个指令集，从而实现对该站点指定路径的保护。

# 针对 website1.com 下的根路径进行保护
worker_processes auto;
pcre_jit on;
error_log  logs/error.log error;
events {
    worker_connections  1024;
}

http {
    include       mime.types;
    default_type  application/octet-stream;
    sendfile        on;
    keepalive_timeout  65;

    ###### 这里插入指令集1 ######
    
    server {
        listen       80;
        server_name  website1.com;
        
        ###### 这里插入指令集2 ######
    
        location / {
            
            ###### 这里插入指令集3 ######
            
            proxy_pass http://10.10.71.143:9090;
        }
    }

    server {
        listen 82;
        server_name website2.com;
        location / {
            proxy_pass http://10.10.71.143:8080;
        }
    }
}

以下展示了插入指令集后的配置文件内容。已在每个指令集中需要修改的行尾添加了注释，请注意进行相应的修改。

worker_processes auto;
pcre_jit on;
error_log  logs/error.log error;

events {
    worker_connections  1024;
}

http {
    include       mime.types;
    default_type  application/octet-stream;
    sendfile        on;
    keepalive_timeout  65;


    1️⃣ ###### 指令集1开始行: 记住测试环境中需要指定一个有效 DNS 地址！！！
    
    map $msec $msec_no_decimal { ~(.*)\.(.*) $1$2; }
    log_format  proxy  escape=json
        '{'
            '"keeper_version": "$revol_version",'
            '"site_id":"$site_id",'
            '"timestamp": $msec_no_decimal,'
            '"session": "$revol_session",'
            '"account": "$revol_account",'
            '"src_ip":"$remote_addr",'
            '"referrer":"$http_referer",'
            '"request":"$request",'
            '"status": $status,'
            '"body_bytes_sent": $body_bytes_sent,'
            '"user_agent":"$http_user_agent",'
            '"x_forwarded_for":"$http_x_forwarded_for",'
            '"guard_status":"$guard_status",'
            '"scheme":"$scheme",'
            '"hostname":"$host",'
            '"request_time": $request_time'
        '}';
    
    resolver 61.139.2.69 ipv6=off; # 在测试环境中需要为 OpenResty 指定一个有效的 DNS 地址，例如电信 DNS 61.139.2.69。如果原有配置文件中已经配置了 DNS，则可以注释这一行。
    lua_shared_dict keeper 1m;
    init_worker_by_lua_file /usr/local/openresty/lualib/riversec/handlers/init.lua;
    
    1️⃣ ###### 指令集1结束行
    
    
    server {
        listen       80;
        server_name  website1.com;
    
    
        2️⃣ ###### 指令集2开始行: 记住添加站点配置ID！！！
        
        set $guard_status '';
        set $revol_session '';
        set $revol_account '';
        set $revol_version '';
        set $site_id 'site_id'; # 需要用刚才复制的站点配置ID替换site_id，例如 set $site_id 'revol_b2rblvr25zo6lrcw'
        
        2️⃣ ###### 指令集2结束行
    
    
        location / {
    
    
            3️⃣ ###### 指令集3开始行
            
            set $role 'MAIN';
            access_by_lua_file /usr/local/openresty/lualib/riversec/handlers/main.lua;
            header_filter_by_lua_file /usr/local/openresty/lualib/riversec/handlers/main.lua;
            body_filter_by_lua_file /usr/local/openresty/lualib/riversec/handlers/main.lua;

            access_log syslog:server=detector.riveryun.com,tag=revol_keeper proxy;
            proxy_http_version 1.1;
            proxy_set_header Host $host;
            
            3️⃣ ###### 指令集3结束行
    
    
            proxy_pass http://10.10.71.143:9090;
        }
    }

    server {
        listen 82;
        server_name website2.com;
        location / {
            proxy_pass http://10.10.71.143:8080;
        }
    }
}

3.3 重新启动OpenResty

完成上面的配置后，执行 systemctl restart openresty 重新启动 OpenResety，即可实现云服务接入。

提示：

请参考附录 2 不同的路径上实现不同的防护效果，以了解如何针对不同路径实现不同的防护效果。

4 验证接入

为了验证站点已经成功接入云服务，请先通过浏览器访问该站点的域名。然后按照以下两个方法进行验证，如果看到的现象与以下两个方法的描述都相符，表示站点已成功完成接入。

1. 在浏览器开发者工具中 (按下 F12 打开该工具)，确认站点下包含名为 zVZq 和 PpaP 的 Cookie。

2. 登录云服务，在站点配置页面中，连接的插件一栏下方，确保插件名称 keeper_GATEWAY_IP 如下图所示，以蓝色背景显示为一个标签（鼠标悬停在名称上方可查看全名）。

提示：

💡 方法 2 中显示的“连接的插件”名称为插件的默认名称，当它显示为蓝色标签时，表示当前 OpenResty 上安装的插件已经在正常工作。该名称可以根据需要进行更改，例如修改为当前 OpenResty 服务器的 IP 地址，表示该服务器上正在运行插件。请阅读附录 1 插件配置项获取修改方法。

5 手动逃生

如果遇到紧急情况，可采用以下方式让访问流量绕过插件直接转发到后端服务器，保证业务流量的持续性。

# 注释掉 OpenResty 配置文件中所添加的这五行指令
# lua_shared_dict keeper 1m;
# init_worker_by_lua_file /usr/local/openresty/lualib/riversec/handlers/init.lua;
# access_by_lua_file /usr/local/openresty/lualib/riversec/handlers/main.lua;
# header_filter_by_lua_file /usr/local/openresty/lualib/riversec/handlers/main.lua;
# body_filter_by_lua_file /usr/local/openresty/lualib/riversec/handlers/main.lua;

注释后，通过 /usr/local/openresty/nginx/sbin/nginx -s reload 命令重新加载配置，即可实现逃生。

提示：

💡 请参考附录 1 插件配置项，查看另一种手动逃生方法。

附录 1 插件配置项

插件安装后，会生成专门的配置文件 ( /usr/local/openresty/lualib/riversec/static/config.json )。通常采用默认配置即可生效，不需要更多修改，

但如果需要修改插件的名称、禁用插件实现手动逃生、以及实现其他操作，则可以通过修改这个 JSON 文件中的配置项来实现。

修改插件名称

当插件成功与云服务连接后，插件名称（即下方 keeper_id 的值）会在站点配置页面的连接的插件一栏中，以蓝色底纹显示。

因此建议将 “keeper_id” 的值修改为易于理解的字符串，例如当前 OpenResty服务器的名称或 IP 地址 (假设是 10.0.0.1)，如下所示：

{
    "module": "guard",
    "company": "riversec",
    "version": "v1.5.0",
    "build": "6e6c503",
    "endpoint_url": "https://detector.riveryun.com/4h2uWW2S/",
    "enable": true,
    "keeper_id": "10.0.0.1", # 修改为插件所在服务器的名称或地址，显示在云服务管理界面中
    "http": {
        "interval_in_seconds": 3,
        "max_retry": 3,
        "connect_timeout_ms": 1000,
        "send_timeout_ms": 100,
        "read_timeout_ms": 100
    }
}

保存后，通过 /usr/local/openresty/nginx/sbin/nginx -s reload 命令重新加载配置，然后通过浏览器访问站点，2-3秒后即可生效。这时登录云服务管理界面，进入站点配置页面，即可看到该名称以蓝色底纹显示在连接的插件一栏中。

手动逃生

除了正文中描述的在 OpenResty 配置文件中注释指令来实现逃生，还可以通过插件的配置文件 config.json 的修改来达到相同的效果。

打开该配置文件，然后将顶层键值对中的 “enable” 设置为 false 并保存，然后通过 /usr/local/openresty/nginx/sbin/nginx -s reload 命令重新加载配置即可实现逃生。如下所示：

{
    "module": "guard",
    "company": "riversec",
    "version": "v1.5.0",
    "build": "6e6c503",
    "endpoint_url": "https://detector.riveryun.com/4h2uWW2S/",
    "enable": false, # 修改为 false 实现手动逃生
    "keeper_id": "10.0.0.1",
    "http": {
        "interval_in_seconds": 3,
        "max_retry": 3,
        "connect_timeout_ms": 1000,
        "send_timeout_ms": 100,
        "read_timeout_ms": 100
    }
}

配置项列表

以下列表包含了 config.json 文件中主要配置项的说明。

enable : 是否启用整个模块下的所有功能，可设置为true或false，默认为true。

keeper_id : 用来标识站点配置在哪个插件上被使用，默认为revol_keeper_default。

http.interval_in_seconds : 设置针对瑞数检测服务的健康检查间隔时间（单位: 秒）, 默认为3。（请同时参考使用手册 > 附录3 已知问题中的问题2）

http.max_retry : 设置针对瑞数检测服务的健康检查重试次数，检测服务无正常响应的次数连续超过该数字，则认为检测服务不可用，会立刻禁用本插件功能，默认为3。

http.connect_timeout_ms : 健康检查的连接超时设置，默认值为1000ms，详见openresty lua sock。

http.send_timeout_ms : 健康检查的发送超时设置，默认值为100ms。

http.read_timeout_ms : 健康检查的接收超时设置，默认值为100ms。

附录 2 不同的路径上实现不同的防护效果

如果您需要对网站不同的路径实现不同的防护效果，例如需要对路径 /abc/ 上的请求实施监控但不拦截，而对路径 /def/ 上的请求实施拦截，则应该创建两个不同工作模式的站点配置，并把对应的站点配置ID号分别应用到 OpenResty 配置文件中的 location /abc/ 和 location /def/ 配置块下。

您可以参考下面的步骤来进行配置。

1. 备份 OpenResty 原有配置文件。

2. 用您的账号登录云服务配置界面，并根据使用手册 > 2 站点配置中的描述创建两个站点配置。一个站点配置选择监控模式，另一个选择拦截模式。

3. 将站点配置的ID号复制下来，然后将以下范例中的指令集复制到 OpenResty 的配置文件中。已在每个指令集中需要修改的行尾添加了注释，请注意进行相应的修改。

worker_processes auto;
pcre_jit on;
error_log  logs/error.log error;

events {
    worker_connections  1024;
}

http {
    include       mime.types;
    default_type  application/octet-stream;
    sendfile        on;
    keepalive_timeout  65;


    1️⃣ ###### 指令集1开始行: 记住测试环境中需要指定一个有效 DNS 地址！！！
    
    map $msec $msec_no_decimal { ~(.*)\.(.*) $1$2; }
    log_format  proxy  escape=json
        '{'
            '"keeper_version": "$revol_version",'
            '"site_id":"$site_id",'
            '"timestamp": $msec_no_decimal,'
            '"session": "$revol_session",'
            '"account": "$revol_account",'
            '"src_ip":"$remote_addr",'
            '"referrer":"$http_referer",'
            '"request":"$request",'
            '"status": $status,'
            '"body_bytes_sent": $body_bytes_sent,'
            '"user_agent":"$http_user_agent",'
            '"x_forwarded_for":"$http_x_forwarded_for",'
            '"guard_status":"$guard_status",'
            '"scheme":"$scheme",'
            '"hostname":"$host",'
            '"request_time": $request_time'
        '}';
    
    resolver 61.139.2.69 ipv6=off; # 在测试环境中需要为 OpenResty 指定一个有效的 DNS 地址，例如电信 DNS 61.139.2.69。如果原有配置文件中已经配置了 DNS，则可以注释这一行。
    lua_shared_dict keeper 1m;
    init_worker_by_lua_file /usr/local/openresty/lualib/riversec/handlers/init.lua;
    
    1️⃣ ###### 指令集1结束行
    
    
    server {
        listen       80;
        server_name  website1.com;
    
    
        2️⃣ ###### 指令集2开始行: 记住添加站点配置ID！！！
        
        set $guard_status '';
        set $revol_session '';
        set $revol_account '';
        set $revol_version '';
        # 注意，这里并没有像 3.2 小节中的例子那样包含指令 set $site_id 'site_id'; 这是因为本实例并不需要保护整个站点的所有路径，仅需要保护下面的指定路径，因此该指令被移到了后面需要保护的 location 配置块中。
        
        
        2️⃣ ###### 指令集2结束行
    
    
        location /abc/ {
    
    
            3️⃣ ###### 指令集3开始行
            
            set $role 'MAIN';
            set $site_id 'site_id'; # 需要用刚才复制的、采用监控模式的站点配置ID替换site_id，例如 set $site_id 'revol_b2rblvr25zo6lrcw'
            access_by_lua_file /usr/local/openresty/lualib/riversec/handlers/main.lua;
            header_filter_by_lua_file /usr/local/openresty/lualib/riversec/handlers/main.lua;
            body_filter_by_lua_file /usr/local/openresty/lualib/riversec/handlers/main.lua;

            access_log syslog:server=detector.riveryun.com,tag=revol_keeper proxy;
            proxy_http_version 1.1;
            proxy_set_header Host $host;
            
            3️⃣ ###### 指令集3结束行
    
    
            proxy_pass http://10.10.71.143:9090;
        }
        
        location /def/ {
    
    
            3️⃣ ###### 指令集4开始行
            
            set $role 'MAIN';
            set $site_id 'site_id'; # 需要用刚才复制的、采用拦截模式的站点配置ID替换site_id，例如 set $site_id 'revol_a2csjew43ag6lrcx'
            access_by_lua_file /usr/local/openresty/lualib/riversec/handlers/main.lua;
            header_filter_by_lua_file /usr/local/openresty/lualib/riversec/handlers/main.lua;
            body_filter_by_lua_file /usr/local/openresty/lualib/riversec/handlers/main.lua;

            access_log syslog:server=detector.riveryun.com,tag=revol_keeper proxy;
            proxy_http_version 1.1;
            proxy_set_header Host $host;
            
            3️⃣ ###### 指令集4结束行
    
    
            proxy_pass http://10.10.71.143:9090;
        }
        
        
        location / { # 根目录的访问配置应该放到最后
            ...
            proxy_pass http://10.10.71.143:9090;
        }
    }

    server {
        listen 82;
        server_name website2.com;
        location / {
            proxy_pass http://10.10.71.143:8080;
        }
    }
}

注意：

location / 的配置块应该放到最后才能保证不同路径上的防护功能生效。

4. 完成上面的配置后，执行 systemctl restart openresty 重新启动 OpenResety，即可针对不同的路径实现不同的防护效果。

附录 3 默认站点配置ID

登录 https://console.riveryun.com 后进入 站点配置 页面，可以看到一个以您的租户ID开头的默认站点配置ID，例如您的租户ID为 tenant，那么默认站点配置ID会显示为 "tenant_config_default"。

默认站点配置ID将作为其他自定义配置ID的备用ID。如果某个正在使用的配置ID由于某些原因失效（例如配置ID被误删除），那么插件会自动尝试连接默认的站点配置ID，并在连接成功后应用其中的安全配置。

插件通过 /usr/local/openresty/lualib/riversec/static/default.json 文件中的 uid 键值来确定默认的站点配置ID。如下所示，请将 uid 键值改为您的默认站点配置ID。

{
    "uid": "revol_config_default", # 将 "revol_config_default" 改为 "tenant_config_default"
    "mode": "0",
    "hide_server_version": true,
    "token": {
        "action": {
            "block_page": "<html><body>BLOCKED</body></html>",
            "reload_page": "<html><meta id=\"TiQn\" content=\"AQ\"><body></body></html>",
            "block_status_code": 400,
            "reload_status_code": 412
        }
    },
    "mobile": {
        "enable": false,
        "shakehdr": "X-Revol-Shake",
        "sechdr": "Eoh8Woo5",
        "block_response": "{\"title\":\"Forbidden\", \"description\": \"You are not allowed to do this.\"}",
        "reload_response": "{\"title\":\"Unauthorized\", \"description\": \"Please send me a valid token.\"}",
        "block_status_code": 400,
        "reload_status_code": 412
    },
    "list": {
        "mode": "all",
        "ips": "disabled",
        "paths": "disabled"
    }
}

注意：

默认站点配置ID默认处于透传模式。

保存修改后，执行 /usr/local/openresty/nginx/sbin/nginx -s reload，重新加载使其生效。

附录 4 卸载插件

通过以下步骤，可以卸载服务器上安装的插件。

1. 在 OpenResty 所在的操作系统上，执行以下命令来卸载插件。

   dpkg -r keeper-lua

2. 用之前备份的 OpenResty 配置文件覆盖当前配置文件。

3. 然后执行以下命令重启 OpenResty。

   systemctl restart openresty

4. 登录 https://console.riveryun.com ，站点配置页面中连接的插件一栏下的插件标签变成灰色，表示插件已断开连接。如果通过浏览器能够打开站点页面，表示已成功完成卸载，站点已恢复到安装之前的状态。