插件版接入指南（OpenResty）
💡 注意：
本指南适用于采用 OpenResty 作为反向代理服务器的站点，通过安装插件的方式接入瑞数云。如果采用其他方式接入，请退回到 接入指南 页面选择适当的文档；如果需要在本地私有化部署瑞数云的服务并通过插件方式接入该私有化服务，请跳到 私有化部署指南。
插件支持 Windows Server 2012 或更高版本。以下内容将以 Windows Server 2012 操作系统上运行 OpenResty 为例。对于其他版本的 Windows 服务器，该文档也可以作为参考。
目前暂不支持 HTTP 响应头中包含 CSP 策略（Content-Security-Policy）的用户站点。如果此类站点需要接入瑞数云，请先禁用该响应头。（关于插件版接入原理，请参考 接入原理简介）
1 创建站点和保存信息
首先使用瑞数云上注册的租户登录 瑞数云管理界面。单击左侧导航栏底部的 平台，然后进入 账号管理 标签，如下图所示。将 企业ID 的号码复制下来，以便后续使用。
💡 提示：
租户是指通过瑞数云登录界面注册的、或通过华为云注册的账号。该账号具有不可撤销的管理员权限，可以创建新管理员、以及对新管理员进行权限修改、重置密码和账号删除等操作。
进入 配置管理 > 站点管理。将 全局配置 标签下的 Access Key 复制保存，以便后续使用。
单击页面左上角的 添加站点 进入新站点的配置界面。
请参考 使用手册 > 3.1 站点管理 小节中的内容来配置新站点（如果站点的客户端是微信小程序，记住配置时勾选 微信小程序防护），并记录填写的域名，以便后续使用。
💡 注意：
请确保这里填写的域名与 OpenResty 配置文件中 server_name 指令的值相同。
对于 OpenResty 配置文件中 server_name 指令采用正则表达式的情况，请同时参考 附录 2 中的内容。
2 下载插件
在购买服务后（未购买服务的账号仅有一个月的试用期。请参考 如何获得瑞数云账号 中的内容来了解购买方法），请使用收到的账号登录 瑞数云管理界面, 并通过 配置管理 > 站点管理 页面上方的 插件 按钮（如下图所示），将插件的安装文件 rskeeper.tar.gz 下载到本地。
将文件复制到 OpenResty 所在的操作系统中准备安装。
3 安装插件
首先确保系统中已安装好 OpenResty，安装方法可参考 官方安装说明。
解压刚才下载的插件，解压后得到文件名类似 rskeeper_1.5.5_xxxx_amd64.deb 的预编译文件，以及文件名类似 rskeeper_1.5.5_xxxx_source.tgz 的源码文件。
对于 Windows 系统来说，仅需要源码文件即可安装插件。解压该源码文件，生成名为 riversec 的文件夹。
复制文件到 OpenResty 安装目录。
💡 提示：
以下假设 OpenResty 的安装目录为 C:\openresty 。
将 riversec 文件夹复制到 C:\openresty\lualib\ 目录下，复制后目录结构为 C:\openresty\lualib\riversec\
4 配置OpenResty服务器
配置 OpenResty 服务器需要三个步骤：
❶ 备份和修改服务器配置文件。
❷ 备份和修改配置文件。
❸ 重启 OpenResty。
同时，针对不同的防护需求，可以通过这三个步骤的不同配置细节，实现两种防护模式：异步模式 和 同步模式。
异步模式：是指插件在收到瑞数云返回的、针对业务请求的检测结果之前，会先转发业务请求。当接收到返回的结果后，再根据当前站点的工作模式来对该请求端的后续请求做出相应处理。
这种模式适用于对拦截时机要求不是特别严格，允许少量异常请求访问服务器，但对网关的转发速度要求很高的场景。
💡 提示：
如果未购买规则模块，建议采用异步模式。
同步模式：是指插件在收到瑞数云返回的、针对业务请求的检测结果之前，会暂时保留该请求。当接收到返回的结果后，再决根据当前站点的工作模式来对该请求、以及该请求端的后续请求做出相应处理。
这种模式适用于允许网关的转发速度有轻微下降，但对拦截时机要求特别严格，不允许任何异常请求访问服务器的场景。
下面将分别针对两种模式的配置进行介绍。
4.1 异步模式配置方法
4.1.1 备份和修改服务器配置文件
首先将原有 OpenResty 配置文件（C:\openresty\conf\nginx.conf）备份，以便在需要时恢复。
假设原有 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;
#########################################################
###### 确保 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 ../lualib/riversec/conf/init.conf;
1️⃣ ###### 指令集 1 结束行
server {
listen 80;
server_name website1.com;
#########################################################
###### 确保 server_name 域名与创建新站点时填写的域名相同 ######
#########################################################
location / {
2️⃣ ###### 指令集 2 开始行
include ../lualib/riversec/conf/guard.conf;
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 配置插件
按照以下内容修改 C:\openresty\lualib\riversec\static/conf.json 文件。
{
"module": "guard",
"company": "riversec",
"version": "1.5.5",
"build": "bb3b2b2b",
"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
完成上面的配置后，重启 OpenResty 即可实现瑞数云接入。
4.2 同步模式配置方法
4.2.1 备份和修改服务器配置文件
首先将原有 OpenResty 配置文件（C:\openresty\conf\nginx.conf）备份，以便在需要时恢复。
假设原有 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 ../lualib/riversec/conf/init.conf;
1️⃣ ###### 指令集 1 结束行
server {
listen 80;
server_name website1.com;
#########################################################
###### 确保 server_name 域名与创建新站点时填写的域名相同 ######
#########################################################
2️⃣ ###### 指令集 2 开始行
include ../lualib/riversec/conf/sync/detect.conf;
2️⃣ ###### 指令集 2 结束行
location / {
3️⃣ ###### 指令集 3 开始行
include ../lualib/riversec/conf/guard.conf;
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 配置插件
按照以下内容修改 C:\openresty\lualib\riversec\static\conf.json 文件。
{
"module": "guard",
"company": "riversec",
"version": "1.5.5",
"build": "bb3b2b2b",
"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
完成上面的配置后，重启 OpenResty 即可实现瑞数云接入。
5 验证接入
💡 提示：
以下内容为 Web 站点接入的验证方式。对于微信小程序业务的防护，需要首先在小程序中集成瑞数云的 SDK 软件包，才能成功接入。请通过 联系方式 页面中的信息，向瑞数信息有限公司咨询微信小程序集成业务。
为了验证站点已经成功接入瑞数云，请先通过浏览器访问该站点的域名。然后按照以下两个方法进行验证，如果看到的现象与以下两个方法的描述都相符，表示站点已成功完成接入。
方法 1. 在浏览器开发者工具中 (按下 F12 打开该工具)，确认站点下包含名为 zVZq 和 PpaP 的 Cookie。
方法 2. 登录 瑞数云管理界面，在 配置管理 > 站点管理 页面中，配置状态 一栏下方，确保插件名称 keeper_GATEWAY_IP 如下图所示，以绿色背景显示为一个标签（鼠标悬停在名称上方可查看全名）。
💡 提示：
方法 2 中显示的“连接的插件”名称为插件的默认名称，当它显示为绿色标签时，表示当前 OpenResty 上安装的插件已经在正常工作。该名称可以根据需要进行更改，例如修改为当前 OpenResty 服务器的 IP 地址，表示该服务器上正在运行插件。请阅读 附录 1 插件配置项 获取修改方法。
6 手动逃生
方法一
如果遇到紧急情况，可以通过插件配置文件 C:\openresty\lualib\riversec\static\config.json 的修改，让访问流量绕过插件直接转发到后端服务器，保证业务流量的持续性。
打开该配置文件，然后将顶层键值对中的 “enable” 设置为 false 并保存，然后重启 OpenResty 即可实现逃生。如下所示：
{
"module": "guard",
"company": "riversec",
"version": "1.5.5",
"build": "bb3b2b2b",
"keeper_id": "keeper_GATEWAY_IP",
"tenant_id": "default_tenant",
"access_key": "default_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 的配置文件 C:\openresty\nginx\conf\nginx.conf 中注释下方所列出的两行指令，来实现相同的效果。
# 针对异步模式，请注释掉 OpenResty 配置文件中所添加的这两行指令
# include ../lualib/riversec/conf/init.conf;
# include ../lualib/riversec/conf/guard.conf;
# 针对同步模式，请注释掉 OpenResty 配置文件中所添加的这三行指令
# include ../lualib/riversec/conf/sync/init.conf;
# include ../lualib/riversec/conf/sync/guard.conf;
# include ../lualib/riversec/conf/sync/detect.conf;
注释后，重启 OpenResty 即可实现逃生。
附录 1 插件配置项
插件安装后，会生成专门的配置文件 (C:\openresty\lualib\riversec\static\config.json )。通常采用默认配置即可生效，不需要进行更多修改。
但如果需要修改插件的名称、禁用插件实现手动逃生（参考 手动逃生 > 方法一）、以及实现其他操作，则可以通过修改这个 JSON 文件中的配置项来实现。
修改插件名称
当插件成功与瑞数云连接后，插件名称（即下方 keeper_id 的值）会在 瑞数云管理界面 的 配置管理 > 站点管理 页面中 配置状态 一栏内，以绿色底纹显示。
因此建议将 config.json 文件中的 “keeper_id” 值修改为易于理解的字符串，例如当前 OpenResty服务器的名称或 IP 地址 (假设是 10.0.0.1)，如下所示：
{
"module": "guard",
"company": "riversec",
"version": "1.5.5",
"build": "bb3b2b2b",
"keeper_id": "10.0.0.1", #### 修改为插件所在服务器的名称或地址，显示在瑞数云管理界面中 ####
"tenant_id": "default_tenant",
"access_key": "default_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，然后通过浏览器访问站点，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 指令采用正则表达式的情况，需要对 C:\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 使配置生效。
{
"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 服务器上删除 riversec 目录来实现卸载。
删除 C:\openresty\lualib\ 路径下的 riversec 目录。
用之前备份的 OpenResty 配置文件覆盖当前配置文件。
重启 OpenResty 使配置文件生效。
登录 瑞数云管理界面，配置管理 > 站点管理 页面中 配置状态 一栏下的插件标签变成橙色，表示插件已断开连接。如果通过浏览器能够打开站点页面，表示已成功完成卸载，站点已恢复到安装之前的状态。