插件版接入指南(OpenResty)

💡 注意:
本指南适用于采用 OpenResty 作为反向代理服务器的站点,通过安装插件的方式接入瑞数云。如果采用其他方式接入,请退回到 接入指南 页面选择适当的文档;如果需要在本地私有化部署瑞数云的服务并通过插件方式接入该私有化服务,请跳到 私有化部署指南。
以下内容将以 Debian 发行版的 Linux 操作系统上运行 OpenResty 为例。对于非 DebIan 发行版的 Linux 操作系统下运行的 OpenResty,除了 “3.1 使用预编译包安装” 小节,该文档其他章节的描述都可以作为参考。
目前暂不支持 HTTP 响应头中包含 CSP 策略(Content-Security-Policy)的用户站点。如果此类站点需要接入瑞数云,请先禁用该响应头。(关于插件版接入原理,请参考 接入原理简介)
1 创建站点和保存信息
首先使用瑞数云或华为云上注册的租户登录 瑞数云管理界面。单击左侧导航栏底部的 平台,然后进入 账号管理 标签,如下图所示。将 企业ID 的号码复制下来,以便后续使用。
💡 提示:
租户是指通过瑞数云登录界面注册的、或通过华为云注册的账号。该账号具有不可撤销的管理员权限,可以创建新管理员、以及对新管理员进行权限修改、重置密码和账号删除等操作。
进入 配置管理 > 站点管理。将 全局配置 标签下的 Access Key 复制保存,以便后续使用。
单击页面左上角的 添加站点 进入新站点的配置界面。
请参考 使用手册 > 3.1 站点管理 小节中的内容来配置新站点(如果站点的客户端是微信小程序,记住配置时勾选 微信小程序防护),并记录填写的域名,以便后续使用。
💡 注意:
请确保这里填写的域名与 OpenResty 配置文件中 server_name 指令的值相同。
对于 OpenResty 配置文件中 server_name 指令采用正则表达式的情况,请同时参考 附录 2 中的内容。
2 下载插件
在购买服务后(未购买服务的账号仅有一个月的试用期。请参考 如何获得瑞数云账号 中的内容来了解购买方法),请使用收到的账号登录 瑞数云管理界面, 并通过 配置管理 > 站点管理 页面上方的 插件 按钮(如下图所示),将插件的安装文件 rskeeper_xxx.tar.gz 下载到本地。

将文件复制到 OpenResty 所在的操作系统中准备安装。
3 安装插件
首先确保系统中已安装好 OpenResty,安装方法可参考 官方安装说明。
运行下面命令解压文件。
tar -xvf rskeeper_xxx.tar.gz
解压后得到文件名类似 rskeeper_1.5.5-xxxx_amd64.deb 的预编译文件,以及文件名类似 rskeeper_1.5.5_xxxx_source.tgz 的源码文件。
💡 提示:
非 Debian 发行版的操作系统下请使用源码包进行安装。
3.1 使用预编译包安装
执行以下命令,完成安装。
dpkg -i rskeeper_1.5.5-xxxx_amd64.deb
3.2 使用源码包安装
确保环境已安装 gcc 编译套件和make工具,并且 Lua 库头文件已经存在于以下路径:
openresty/luajit/include/luajit-2.1/
执行以下命令,完成安装。
tar -zvxf rskeeper_1.5.5_xxxx_source.tgz
cp -r riversec /usr/local/openresty/lualib
💡 提示:
OpenResty 的官方默认安装路径为 /usr/local/openresty/。如果实际安装路径不是默认路径,例如 /apt/openresty/,则需要将以上路径 /usr/local/openresty/ 替换为 /apt/openresty/。
4 配置OpenResty服务器
配置 OpenResty 服务器需要三个步骤:
❶ 备份和修改服务器配置文件。
❷ 修改插件配置文件
❸ 重新启动 OpenResty。
同时,针对不同的防护需求,可以通过这三个步骤的不同配置细节,实现两种防护模式:异步模式 和 同步模式。
异步模式:是指插件在收到瑞数云返回的、针对业务请求的检测结果之前,会先转发业务请求。当接收到返回的结果后,再根据当前站点的工作模式来对该请求端的后续请求做出相应处理。
这种模式适用于对拦截时机要求不是特别严格,允许少量异常请求访问服务器,但对网关的转发速度要求很高的场景。
💡 提示:
如果未购买规则模块,建议采用异步模式。
同步模式:是指插件在收到瑞数云返回的、针对业务请求的检测结果之前,会暂时保留该请求。当接收到返回的结果后,再根据当前站点的工作模式来对该请求、以及该请求端的后续请求做出相应处理。
这种模式适用于允许网关的转发速度有轻微下降,但对拦截时机要求特别严格,不允许任何异常请求访问服务器的场景。
下面将分别针对两种模式的配置进行介绍。
4.1 异步模式配置方法
4.1.1 备份和修改服务器配置文件
首先将原有 OpenResty 配置文件备份,以便在需要时恢复。
💡 提示:
OpenResty 的官方默认安装路径下,其配置文件位于 /usr/local/openresty/nginx/conf/nginx.conf。如果实际安装路径不是默认路径,例如 /apt/openresty/,则需要将以上路径 /usr/local/openresty/ 替换为 /apt/openresty/。
假设原有 OpenResty 配置文件如下所示。
# 针对 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;
#########################################################
###### 确保 server_name 域名与创建新站点时填写的域名相同 ######
#########################################################
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;
}
}
}
如果想对站点 website1.com 的路径 location / 进行保护,需要在原有配置文件中做三处修改:
在配置文件 http 配置块下增加 指令集1。
在配置文件的 server > location / 配置块下增加 指令集2。
确保 server 配置块内的 server_name 与瑞数云配置界面新建站点时填写的域名相同。
以下展示了插入指令集后的配置文件内容。
💡 注意:
每个指令集中需要修改的指令下方都添加了注释,请务必按照注释进行相应的修改。
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 114.114.114.114 ipv6=off;
# 需要为 OpenResty 指定一个有效的 DNS 地址。114.114.114.114 为国内常用 DNS。可根据需要决定是否修改。
# 如果原配置文件中已经配置了 DNS,则可以注释这一行。但需要确保原有 DNS 服务器能够解析 detector.riveryun.com。
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;
#########################################################
###### 确保 server_name 域名与创建新站点时填写的域名相同 ######
#########################################################
location / {
2️⃣ ###### 指令集 2 开始行
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;
}
}
}
4.1.2 修改插件配置文件
插件配置文件路径为 /usr/local/openresty/lualib/riversec/static/config.json,请使用之前复制的信息,按照以下内容进行修改。
{
"module": "guard",
"company": "riversec",
"version": "1.5.5",
"build": "6e6c503",
"keeper_id": "keeper_GATEWAY_IP",
"tenant_id": "default_tenant", #### 修改为章节 1 中复制的企业ID ####
"access_key": "default_access_key", #### 修改为章节 1 中复制的 Access Key ####
"endpoint_url": "https://detector.riveryun.com/4h2uWW2S/",
"enable": true,
"http": {
"interval_in_seconds": 3,
"max_retry": 3,
"connect_timeout_ms": 500,
"send_timeout_ms": 500,
"read_timeout_ms": 500
}
}
4.1.3 重新启动OpenResty
完成上面的配置后,执行 systemctl restart openresty 或 openresty -s reload 重新启动 OpenResty,即可实现瑞数云接入。
💡 提示:
对于 OpenResty 配置文件中 server_name 指令采用正则表达式的情况,请参考 附录 2 中的内容。
4.2 同步模式配置方法
4.2.1 备份和修改服务器配置文件
首先将原有 OpenResty 配置文件备份,以便在需要时恢复。
💡 提示:
OpenResty 的官方默认安装路径下,其配置文件位于 /usr/local/openresty/nginx/conf/nginx.conf。如果实际安装路径不是默认路径,例如 /apt/openresty/,则需要将以上路径 /usr/local/openresty/ 替换为 /apt/openresty/。
假设原有 OpenResty 配置文件如下所示。
# 针对 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;
#########################################################
###### 确保 server_name 域名与创建新站点时填写的域名相同 ######
#########################################################
###########################
###### 这里插入指令集 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;
}
}
}
如果想对站点 website1.com 的路径 location / 进行保护,需要在原有配置文件中做三处修改:
在配置文件 http 配置块下增加 指令集1。
在配置文件的 server 配置块下增加 指令集2。
确保 server 配置块内的 server_name 与瑞数云配置界面新建站点时填写的域名相同。
在配置文件的 server > location / 配置块下增加 指令集3。
以下展示了插入指令集后的配置文件内容。
💡 注意:
每个指令集中需要修改的指令下方都添加了注释,请务必按照注释进行相应的修改。
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 114.114.114.114 ipv6=off;
# 需要为 OpenResty 指定一个有效的 DNS 地址。114.114.114.114 为国内常用 DNS。可根据需要决定是否修改。
# 如果原配置文件中已经配置了 DNS,则可以注释这一行。但需要确保原有 DNS 服务器能够解析 detector.riveryun.com。
include /usr/local/openresty/lualib/riversec/conf/sync/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;
#########################################################
###### 确保 server_name 域名与创建新站点时填写的域名相同 ######
#########################################################
2️⃣ ###### 指令集 2 开始行
include /usr/local/openresty/lualib/riversec/conf/sync/detect.conf;
2️⃣ ###### 指令集 2 结束行
location / {
3️⃣ ###### 指令集 3 开始行
include /usr/local/openresty/lualib/riversec/conf/sync/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;
}
}
server {
listen 82;
server_name website2.com;
location / {
proxy_pass http://10.10.71.143:8080;
}
}
}
4.2.2 修改插件配置文件
插件配置文件路径为 /usr/local/openresty/lualib/riversec/static/config.json,请使用之前复制的信息,按照以下内容进行修改。
💡 注意:
插件支持同步和异步模式。请务必根据下方配置实例中的注释来选择不同的模式。
{
"module": "guard",
"company": "riversec",
"version": "1.5.5",
"build": "6e6c503",
"keeper_id": "keeper_GATEWAY_IP",
"tenant_id": "default_tenant", #### 修改为章节 1 中复制的企业ID ####
"access_key": "default_access_key", #### 修改为章节 1 中复制的 Access Key ####
"sync": "true", #### 添加该配置。####
"endpoint_url": "https://detector.riveryun.com/4h2uWW2S/",
"enable": true,
"http": {
"interval_in_seconds": 3,
"max_retry": 3,
"connect_timeout_ms": 500,
"send_timeout_ms": 500,
"read_timeout_ms": 500
}
}
4.2.3 重新启动OpenResty
完成上面的配置后,执行 systemctl restart openresty 或 openresty -s reload 重新启动 OpenResty,即可实现瑞数云接入。
💡 提示:
对于 OpenResty 配置文件中 server_name 指令采用正则表达式的情况,请参考 附录 2 中的内容。
5 验证接入
💡 提示:
以下内容为 Web 站点接入的验证方式。对于微信小程序业务的防护,需要首先在小程序中集成瑞数云的 SDK 软件包,才能成功接入。请通过 联系方式 页面中的信息,向瑞数信息有限公司咨询微信小程序集成业务。
为了验证站点已经成功接入瑞数云,请先通过浏览器访问该站点的域名。然后按照以下两个方法进行验证,如果看到的现象与以下两个方法的描述都相符,表示站点已成功完成接入。
方法 1. 在浏览器开发者工具中 (按下 F12 打开该工具),确认站点下包含名为 zVZq 和 PpaP 的 Cookie。
方法 2. 登录 瑞数云管理界面,在 配置管理 > 站点管理 页面中,配置状态 一栏下方,确认插件名称 keeper_GATEWAY_IP 如下图所示,以绿色背景显示为一个标签(鼠标悬停在名称上方可查看全名)。

💡 提示:
方法 2 中显示的 “配置状态” 名称为插件的默认名称,当它显示为绿色标签时,表示当前 OpenResty 上安装的插件已经在正常工作。该名称可以根据需要进行更改,例如修改为当前 OpenResty 服务器的 IP 地址,表示该服务器上正在运行插件。请阅读 附录 1 插件配置项 获取修改方法。
6 手动逃生
方法一
如果遇到紧急情况,可以通过插件配置文件 /usr/local/openresty/lualib/riversec/static/config.json 的修改,让访问流量绕过插件直接转发到后端服务器,保证业务流量的持续性。
💡 提示:
OpenResty 的官方默认安装路径为 /usr/local/openresty/。如果实际安装路径不是默认路径,例如路径为 /apt/openresty/,则需要将以上路径 /usr/local/openresty/ 替换为 /apt/openresty/。
打开该配置文件,然后将顶层键值对中的 “enable” 设置为 false 并保存,然后通过 openresty -s reload 命令重新加载配置即可实现逃生。如下所示:
{
"module": "guard",
"company": "riversec",
"version": "1.5.5",
"build": "6e6c503",
"keeper_id": "keeper_GATEWAY_IP",
"tenant_id": "你的企业 ID",
"access_key": "你的 Access Key",
"endpoint_url": "https://detector.riveryun.com/4h2uWW2S/",
"enable": false, #### 修改为 false 实现手动逃生 ####
"http": {
"interval_in_seconds": 3,
"max_retry": 3,
"connect_timeout_ms": 500,
"send_timeout_ms": 500,
"read_timeout_ms": 500
}
}
方法二
除了上面通过修改插件的配置文件实现逃生,还可以通过在 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;
# # 针对同步模式,请注释掉 OpenResty 配置文件中所添加的这三行指令
# include /usr/local/openresty/lualib/riversec/conf/sync/init.conf;
# include /usr/local/openresty/lualib/riversec/conf/sync/guard.conf;
# include /usr/local/openresty/lualib/riversec/conf/sync/detect.conf;
注释后,通过 openresty -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": "1.5.5",
"build": "6e6c503",
"keeper_id": "10.0.0.1", #### 修改为插件所在服务器的名称或地址,显示在瑞数云管理界面中 ####
"tenant_id": "你的企业 ID",
"access_key": "你的 Access Key",
"endpoint_url": "https://detector.riveryun.com/4h2uWW2S/",
"enable": true,
"http": {
"interval_in_seconds": 3,
"max_retry": 3,
"connect_timeout_ms": 500,
"send_timeout_ms": 500,
"read_timeout_ms": 500
}
}
保存后,通过 openresty -s reload 命令重新加载配置,然后通过浏览器访问站点,2-3秒后即可生效。这时登录 瑞数云管理界面,进入 配置管理 > 站点管理 页面,即可看到该名称以绿色底纹显示在 配置状态 一栏中。
配置项列表
以下列表包含了 config.json 文件中主要配置项的说明。
enable
: 是否启用整个模块下的所有功能,可设置为true
或false
,默认为true
。
keeper_id
: 用来标识成功连接站点的插件,默认为revol_keeper_default
。
tenant_id
: 你的租户 ID 号,即章节 1 创建站点和保存信息 中 步骤 1 获得的 企业ID。
💡 提示:
租户是指通过瑞数云登录界面注册的、或通过华为云注册的账号。该账号具有不可撤销的管理员权限,可以创建新管理员、以及对新管理员进行权限修改、重置密码和账号删除等操作。
access_key
: 你的专属访问码。
http.interval_in_seconds
: 设置针对瑞数检测服务的健康检查间隔时间(单位: 秒), 默认为3
。(请同时参考 已知问题 中的问题1)
http.max_retry
: 设置针对瑞数检测服务的健康检查重试次数,检测服务无正常响应的次数连续超过该数字,则认为检测服务不可用,会立刻禁用本插件功能,默认为3
。
http.connect_timeout_ms
: 健康检查的连接超时设置,默认值为500ms
,详见 openresty lua sock。
http.send_timeout_ms
: 健康检查的发送超时设置,默认值为500ms
。
http.read_timeout_ms
: 健康检查的接收超时设置,默认值为500ms
。
附录 2 OpenResty配置文件中server_name为正则的配置方法
对于 OpenResty 配置文件中的 server_name 指令采用正则表达式的情况,需要对 /usr/local/openresty/lualib/riversec/static/config.json 文件进行相应修改,才能实现正确接入。
例如,OpenResty 配置文件中存在以下配置。
server_name ~^(www\.)?(.+)(\.riveryun\.com)?$;
而在瑞数云上新建站点时填写的域名为 www.mysite.riveryun.com 。则需要在 config.json 文件中添加以下字段,从而让瑞数云能够成功匹配到站点中所填的域名,实现与插件的连接。
"hosts": [
{ "server_name": "~^(www\.)?(.+)(\.riveryun\.com)?$",
"alias": "www.mysite.riveryun.com" }
],
添加字段后的实例如下。添加后执行 openresty -s reload 使配置生效。
{
"module": "guard",
"company": "riversec",
"version": "1.5.5",
"build": "6e6c503",
"keeper_id": "keeper_GATEWAY_IP",
"tenant_id": "default_tenant", #### 修改为之前复制的企业ID ####
"access_key": "default_access_key", #### 修改为之前复制的 Access Key ####
"endpoint_url": "https://detector.riveryun.com/4h2uWW2S/",
"enable": true,
"hosts": [
{ "server_name": "~^(www\.)?(.+)(\.riveryun\.com)?$",
"alias": "www.mysite.riveryun.com"}
],
"http": {
"interval_in_seconds": 3,
"max_retry": 3,
"connect_timeout_ms": 500,
"send_timeout_ms": 500,
"read_timeout_ms": 500
}
}
附录 3 卸载插件
方法一:
在 OpenResty 服务器上执行 rm 命令,删除 riversec 目录来实现卸载。
执行 rm 命令来卸载插件
rm -rf /usr/local/openresty/lualib/riversec
用之前备份的 OpenResty 配置文件覆盖当前配置文件。
然后执行以下命令重启 OpenResty。
systemctl restart openresty
或
openresty -s reload登录 瑞数云管理界面,配置管理 > 站点管理 页面中 配置状态 一栏下的插件标签变成橙色,表示插件已断开连接。如果通过浏览器能够打开站点页面,表示已成功完成卸载,站点已恢复到安装之前的状态。
💡 提示:
OpenResty 的官方默认安装路径为 /usr/local/openresty/。如果实际安装路径不是默认路径,例如路径为 /apt/openresty/,则将以上路径 /usr/local/openresty/ 替换为 /apt/openresty/。
方法二:
在 OpenResty 服务器上执行 dpkg 命令来卸载服务器上安装的插件。
执行 dpkg 命令来卸载插件。
dpkg -r rskeeper
用之前备份的 OpenResty 配置文件覆盖当前配置文件。
然后执行以下命令重启 OpenResty。
systemctl restart openresty
或
openresty -s reload登录 瑞数云管理界面,配置管理 > 站点管理 页面中 配置状态 一栏下的插件标签变成橙色,表示插件已断开连接。如果通过浏览器能够打开站点页面,表示已成功完成卸载,站点已恢复到安装之前的状态。