跳到主要内容
版本：v1.5.2

插件版接入指南（OpenResty）

💡   注意：

以下内容将以 Debian 发行版的 Linux 操作系统上运行 OpenResty 为例。对于非 DebIan 发行版的 Linux 操作系统下运行的 OpenResty，除了“2.1 使用预编译包安装”小节，该文档其他章节的描述都可以作为参考。

目前暂不支持 HTTP 响应头中包含CSP策略（Content-Security-Policy）的用户站点。如果此类站点需要接入云服务，请先禁用该响应头。（关于插件版接入原理，请参考接入原理简介）

1 下载插件​

在购买服务后，请使用收到的账号登录瑞数云服务配置界面, 并通过站点配置页面右上方的下载插件按钮，将插件的安装文件 keeper-lua.tar.gz 下载到本地。

将文件复制到 OpenResty 所在的操作系统中准备安装。

2 安装插件​

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

运行下面命令解压文件。

tar -zxvf keeper-lua.tar.gz

解压后得到文件名类似 keeper-lua_v1.5.2_amd64_debian.deb 的预编译文件，以及文件名类似 keeper-lua_v1.5.2_source.tar.gz 的源码文件。

💡   提示：

非 Debian 发行版的操作系统下请使用源码包进行安装。

2.1 使用预编译包安装​

执行以下命令，完成安装。

dpkg -i keeper-lua_v1.5.2_amd64_debian.deb

2.2 使用源码包安装​

确保环境已安装gcc编译套件和make工具，并且 Lua 库头文件已经存在于以下路径：

openresty/luajit/include/luajit-2.1/

执行以下命令，完成安装。

tar -zvxf keeper-lua_v1.5.2_source.tar.gz
cp -r keeper-lua/riversec /usr/local/openresty/lualib

💡   提示：

OpenResty 的官方默认安装路径为 /usr/local/openresty/。如果实际安装路径不是默认路径，例如 /apt/openresty/，则需要将以上路径 /usr/local/openresty/ 替换为 /apt/openresty/。

3 配置OpenResty服务器​

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

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

❷ 备份和修改配置文件。

❸ 重新启动 OpenResty。

3.1 获得站点防护配置ID​

站点配置是指您在云服务配置界面中创建的安全防护方案。每个方案都有一个唯一的站点配置 ID 号（例如创建了一个名称为 website_protection 的方案，其 ID 号为 revol_b2rblvr25zo6lrcw)， 如下图所示。

💡   提示：

请首先参考如何获得云服务账号的内容，得到新账号后再登录瑞数云服务配置界面，并根据使用手册 > 3 站点配置中的描述新建站点配置。

将站点配置ID号复制下来，以便稍后使用。

3.2 备份和修改配置文件​

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

💡   提示：

OpenResty 的官方默认安装路径下，其配置文件位于 /usr/local/openresty/nginx/conf/nginx.conf。如果实际安装路径不是默认路径，例如 /apt/openresty/，则需要将以上路径 /usr/local/openresty/ 替换为 /apt/openresty/。

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

# 针对 website1.com 下的根路径进行保护
worker_processes auto;
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;
        

        location / {
            
            ###########################
            ###### 这里插入指令集2 ######
            ###########################
            
            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;
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 地址！！！
    resolver 61.139.2.69 ipv6=off; 
    # 在测试环境中需要为 OpenResty 指定一个有效的 DNS 地址，例如电信 DNS 61.139.2.69。如果原配置文件中已经配置了 DNS，则可以注释这一行。
    
    lua_package_path "/usr/local/openresty/lualib/?.ljbc;/usr/local/openresty/lualib/?.lua;;";
    # OpenResty 的官方默认安装路径为 /usr/local/openresty/。如果实际安装路径不是默认路径，例如路径为 /apt/openresty/，则需要将以上路径 /usr/local/openresty/ 替换为 /apt/openresty/。
  
    include /usr/local/openresty/lualib/riversec/conf/init.conf;​     
    # OpenResty 的官方默认安装路径为 /usr/local/openresty/。如果实际安装路径不是默认路径，例如路径为 /apt/openresty/，则需要将以上路径 /usr/local/openresty/ 替换为 /apt/openresty/。同样，也需要将 init.conf 文件中的 /usr/local/openresty/ 替换为 /apt/openresty/。
    1️⃣ ###### 指令集1结束行
    
    
    server {
        listen       80;
        server_name  website1.com;
    

        location / {
    
​            
            2️⃣ ###### 指令集2开始行
            set $site_id 'revol_b2rblvr25zo6lrcw'; 
            # 确保该指令最后的字符串是刚才复制的站点配置ID
            
            include /usr/local/openresty/lualib/riversec/conf/guard.conf;​ 
            # OpenResty 的官方默认安装路径为 /usr/local/openresty/。如果实际安装路径不是默认路径，例如路径为 /apt/openresty/，则将以上路径 /usr/local/openresty/ 替换为 /apt/openresty/。同样，也需要将 guard.conf 文件中的 /usr/local/openresty/ 替换为 /apt/openresty/。
            2️⃣ ###### 指令集2结束行
    
    
            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 重新启动 OpenResty，即可实现云服务接入。

💡   提示：

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

4 验证接入​

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

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

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

💡   提示：

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

5 手动逃生​

方法一​

如果遇到紧急情况，可以通过插件配置文件 /usr/local/openresty/lualib/riversec/static/config.json 的修改，让访问流量绕过插件直接转发到后端服务器，保证业务流量的持续性。

💡   提示：

OpenResty 的官方默认安装路径为 /usr/local/openresty/。如果实际安装路径不是默认路径，例如路径为 /apt/openresty/，则需要将以上路径 /usr/local/openresty/ 替换为 /apt/openresty/。

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

{
    "module": "guard",
    "company": "riversec",
    "version": "v1.5.2",
    "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
    }
}

方法二​

除了上面通过修改插件的配置文件实现逃生，还可以通过在 OpenResty 的配置文件 /usr/local/openresty/nginx/conf/nginx.conf 中注释下方所列出的两行指令，来实现相同的效果。

💡   提示：

OpenResty 的官方默认安装路径为 /usr/local/openresty/。如果实际安装路径不是默认路径，例如路径为 /apt/openresty/，则需要将以上路径 /usr/local/openresty/ 替换为 /apt/openresty/。

# 注释掉 OpenResty 配置文件中所添加的这两行指令
# include /usr/local/openresty/lualib/riversec/conf/init.conf;
# include /usr/local/openresty/lualib/riversec/conf/guard.conf;

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

附录 1 插件配置项​

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

💡   提示：

OpenResty 的官方默认安装路径为 /usr/local/openresty/。如果实际安装路径不是默认路径，例如路径为 /apt/openresty/，则需要将以上路径 /usr/local/openresty/ 替换为 /apt/openresty/。

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

修改插件名称​

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

因此建议将 /usr/local/openresty/lualib/riversec/static/config.json 文件中的 “keeper_id” 值修改为易于理解的字符串，例如当前 OpenResty服务器的名称或 IP 地址 (假设是 10.0.0.1)，如下所示：

💡   提示：

OpenResty 的官方默认安装路径为 /usr/local/openresty/。如果实际安装路径不是默认路径，例如路径为 /apt/openresty/，则需要将以上路径 /usr/local/openresty/ 替换为 /apt/openresty/。

{
    "module": "guard",
    "company": "riversec",
    "version": "v1.5.2",
    "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秒后即可生效。这时登录云服务管理界面，进入站点配置页面，即可看到该名称以蓝色底纹显示在连接的插件一栏中。

配置项列表​

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

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

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

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

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

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

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

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

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

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

您可以参考下面的实例来修改 OpenResty 的配置文件。

💡   注意：

除了 OpenResty 配置文件的内容以及新建站点配置的数量外，不同路径的防护与单一路径的防护在其他步骤上的操作内容相同。请确保完成所有操作步骤，而不仅仅限于下面的两个步骤。

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

  2. 将站点配置的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 地址！！！
        resolver 61.139.2.69 ipv6=off; 
        # 在测试环境中需要为 OpenResty 指定一个有效的 DNS 地址，例如电信 DNS 61.139.2.69。如果原配置文件中已经配置了 DNS，则可以注释这一行。

        lua_package_path "/usr/local/openresty/lualib/?.ljbc;/usr/local/openresty/lualib/?.lua;;";
        # OpenResty 的官方默认安装路径为 /usr/local/openresty/。如果实际安装路径不是默认路径，例如路径为 /apt/openresty/，则需要将以上路径 /usr/local/openresty/ 替换为 /apt/openresty/。

        include /usr/local/openresty/lualib/riversec/conf/init.conf;​ 
        # OpenResty 的官方默认安装路径为 /usr/local/openresty/。如果实际安装路径不是默认路径，例如路径为 /apt/openresty/，则将以上路径 /usr/local/openresty/ 替换为 /apt/openresty/。同样，也需要将 init.conf 文件中的 /usr/local/openresty/ 替换为 /apt/openresty/。​
        1️⃣ ###### 指令集1结束行
     
     
       server {
           listen       80;
           server_name  website1.com;
           
           location /abc/ {
            
                ​            
               2️⃣ ###### 指令集2开始行
               set $site_id 'revol_b2rblvr25zo6lrcw'; 
               # 确保指令结果的字符串是刚才复制的、采用监控模式的站点配置ID

               include /usr/local/openresty/lualib/riversec/conf/guard.conf;​ 
               # OpenResty 的官方默认安装路径为 /usr/local/openresty/。如果实际安装路径不是默认路径，例如路径为 /apt/openresty/，则将以上路径 /usr/local/openresty/ 替换为 /apt/openresty/。同样，也需要将 guard.conf 文件中的 /usr/local/openresty/ 替换为 /apt/openresty/。​
               2️⃣ ###### 指令集2结束行
               
               
               proxy_pass http://10.10.71.143:9090;
           }
            
           location /def/ {
           
                ​            
               3️⃣ ###### 指令集3开始行
               set $site_id 'revol_a2csjew43ag6lrcx'; 
               # 确保指令结果的字符串是刚才复制的、采用拦截模式的站点配置ID
        
               include /usr/local/openresty/lualib/riversec/conf/guard.conf;​ 
               # OpenResty 的官方默认安装路径为 /usr/local/openresty/。如果实际安装路径不是默认路径，例如路径为 /apt/openresty/，则将以上路径 /usr/local/openresty/ 替换为 /apt/openresty/。同样，也需要将 guard.conf 文件中的 /usr/local/openresty/ 替换为 /apt/openresty/。​
               3️⃣ ###### 指令集3结束行
                
               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 / 的配置块应该放到最后才能保证不同路径上的防护功能生效。

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

附录 3 默认站点配置ID​

登录瑞数云服务配置界面后进入 站点配置 页面，可以看到一个以 “default” 结尾的默认站点配置ID，例如 "revol93791579_config_default"。

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

插件通过 /usr/local/openresty/lualib/riversec/static/default.json 文件中的 uid 键值来读取和连接默认的站点配置ID。请将 uid 键值改为您的默认站点配置ID，如下方例子所示。

💡   提示：

OpenResty 的官方默认安装路径为 /usr/local/openresty/。如果实际安装路径不是默认路径，例如路径为 /apt/openresty/，则将以上路径 /usr/local/openresty/ 替换为 /apt/openresty/。

{
    "uid": "revol_config_default", # 将 "revol_config_default" 改为 "revol93791579_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，重新加载使其生效。

💡   提示：

OpenResty 的官方默认安装路径为 /usr/local/openresty/。如果实际安装路径不是默认路径，例如路径为 /apt/openresty/，则将以上路径 /usr/local/openresty/ 替换为 /apt/openresty/。

附录 4 卸载插件​

方法一：

在 OpenResty 服务器上执行 rm 命令，删除 riversec 目录来实现卸载。

  1. 执行 rm 命令来卸载插件

    rm -rf /usr/local/openresty/lualib/riversec/

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

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

    systemctl restart openresty

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

💡   提示：

OpenResty 的官方默认安装路径为 /usr/local/openresty/。如果实际安装路径不是默认路径，例如路径为 /apt/openresty/，则将以上路径 /usr/local/openresty/ 替换为 /apt/openresty/。

方法二：

在 OpenResty 服务器上执行 dpkg 命令来卸载服务器上安装的插件。

  1. 执行 dpkg 命令来卸载插件。

    dpkg -r keeper-lua

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

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

    systemctl restart openresty

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