网站配置

2023/12/20大约 37 分钟

网站配置

1 部署架构：

请依据下面的架构方式布局SamWaf防火墙

1.1 部署在同台服务器（常见）

重要

重要:部署在同台服务器会存在端口：80、443已经占用的情况，请在本机或者网站业务不繁忙得时候操作。关于端口修改，请查看常见问题。

1.2 部署在不同服务器

此部署方式适合服务器资源丰富的情况。将SamWaf单独部署在独立服务器，并把域名解析到SamWaf所在服务器即可。用SamWaf所在的服务器反向代理内网各个服务器，而公网只暴露SamWaf所在服务器。

2 新增可被防火墙保护的网站：

关键配置，配置一次即可随时使用。

2.1 新增网站

网站：
- 只需填写网站的域名部分。注意诸如https、http前缀以及/等后缀都不需要填入
例如：www.baidu.com，pan.baidu.com

表单分区

「基础内容」按主题分为 站点 / 监听与协议 / HTTPS 证书 / 回源（后端）/ 运行方式 / 备注信息 六个小节，下面按小节顺序说明。表单右上角可切换竖向/横向标签与全屏显示。

监听端口：
- 逐个声明这个网站在本机的监听端口以及每个端口使用的协议（HTTP / HTTPS）。第一行是主端口，其余为附加端口，可用「+ 添加端口」增加、用行尾的删除按钮移除。 http服务的常用端口是80，https服务的常用端口是443（如果已经安装了宝塔、Nginx、IIS等网站服务器需要手工改动端口，以解除成80、443端口的占用。关于端口修改，请查看常见问题。）
- 详见下方 2.2 监听端口与协议。

加密证书： 1.如果是https需要选择加密证书，80端口不需要首次需要点击“添加新证书”，新增证书。

通常文件名：*.key
内容格式如下：-----BEGIN RSA PRIVATE KEY----- ... 全选复制填写进来

证书串

通常文件名：*.crt
内容格式如下：-----BEGIN CERTIFICATE----- ... 全选复制填写进来

从证书夹选择对应证书

启动状态：自动启动：添加后正常提供服务；手工启动，添加后不会占用端口，不提供服务。
来源严格端口：来源严格端口默认是开启，此时若端口配置为80，则不可通过非80端口来访。若外层还有NGINX、CDN等代理的情况，建议关闭，否则可能无法正常访问。
后端系统类型、后端应用类型：非必要，可以选择和实际一样，也可以保持默认（后期可能针对后端接入不同做适配处理）
后端域名：默认同主域名相同（需要加上http或者https协议头）；有特例，如果SamWaf配置的前置域名和后置域名不相同，此时需要开启【是否传递后端域名】才可以正常访问。
后端IP：如SamWaf与需反代的服务在同一台服务器，填写127.0.0.1。如SamWaf与需反代的服务不在同一台服务器，填写需反代的服务的实际IP。
后端端口：填写需要反代的服务的对应端口（注意若已按常见问题修改过端口，需要填写修改后端口，如81）

2.2 监听端口与协议

端口在整机上是共享资源：同一个端口只会有一个监听、只能是一种协议。所以每个端口的协议需要逐个声明，而不是由「加密证书」开关统一推断。

操作步骤

在「监听与协议」小节的端口表里，第一行填写主端口，并在右侧选择该端口的协议（HTTP 或 HTTPS）。
需要多个端口时点「+ 添加端口」，逐行填写端口号并各自选择协议。
有端口选择了 HTTPS 时，必须在下方「HTTPS 证书」小节把「加密证书」设为「加密证书（需上传证书）」并配置证书，否则无法保存。
保存前若与本机其它网站的同端口协议不一致，表单会当场给出红色提示并点名冲突站点，保存也会被拒绝。

字段说明

字段	说明
端口	监听端口号，范围 1–65535，最多 32 个，不能重复
协议	该端口对外提供 HTTP 还是 HTTPS。80 端口也可以选 HTTPS，由你决定
IP 版本	默认监听全部（IPv4+IPv6）。勾选「指定 IP 版本（默认 IPv4+IPv6）」后才出现这一列，可单独选「仅 IPv4」或「仅 IPv6」
添加 80 端口（证书文件验证用）	站点存在 HTTPS 端口且主端口不是 80 时出现，默认勾选，会自动补一条 `80:HTTP`

IP 版本

选择「仅 IPv6」前请确认机器确实有 IPv6 地址，否则该端口无法监听。监听失败会在系统日志与管理端提示中告知。

取消「指定 IP 版本」勾选会把所有行重置回 IPv4+IPv6，避免留下看不见却仍在生效的设置。

为什么默认要加 80 端口

证书的「文件验证（http01）」在申请与自动续期时，验证方会以明文 HTTP 访问本站的 80 端口，所以默认给 HTTPS 站点补一条 80:HTTP。如果你用「DNS 验证」方式申请证书，可以取消勾选、不添加 80 端口。

反过来，如果把 80 端口设为 HTTPS，文件验证方式的申请与自动续期将无法完成，表单会给出橙色提示。

与「强制80跳转HTTPS」的关系

开启「强制80跳转HTTPS」后，即使端口表里没有 80，引擎也会自动占用 80 端口做跳转，端口区会有相应提示。

升级说明

从旧版本升级时，端口协议表为空的站点会按原有规则推导，行为与升级前完全一致，不需要做任何操作。只有当你主动编辑并保存过端口区之后，该站点才改用显式声明。

常见问题：整机 80 端口变成了 HTTPS

如果某个站点主端口是 80 且开启了加密证书，旧版本会把整机的 80 端口建成 HTTPS 监听，导致其它走明文 HTTP 的站点、以及 CDN 明文回源全部返回 400 Client sent an HTTP request to an HTTPS server。现在把该站点 80 端口的协议显式改为 HTTP 并保存即可恢复，证书配置会原样保留。可用工具栏的「端口占用总览」确认每个端口当前实际被谁、以什么协议占用（见 9.1）。

3 负载均衡：

负载均衡支持：权重轮询(WRR),IP Hash

权重轮询(WRR)：根据后端服务器的权重，按依次将请求分发给不同的服务器。权值越高的服务器被轮询到的次数（概率）越高。
IP Hash：根据请求的源 IP 地址，使用散列键（Hash Key）从散列表找出对应的服务器,使得相同IP每次访问的服务器是固定的。

3.1 负载均衡配置

点击被防护的网站启动“负载均衡”。

负载均衡列表。

3.2 添加后端负载

负载配置。

IP：填入后端可接入的IP
端口：填入后端可接入的端口
权重：填入权重，针对权重轮询(WRR)模式，可以增加客户访问该服务器的几率。

4 网站密码访问

自v1.3.9-beta.11 已支持网站密码访问, 添加或者编辑网站最后一个选项卡，网站密码访问。网站密码访问默认关闭，可以自行打开。

4.1 网站密码访问列表

在此查看、添加、编辑、或者删除网站的密码访问用户。

具体访问效果如下：

5.其他配置

5.1 记录日志时排除URL

一行一个日志URL

按前缀匹配：请求 URL 以其中任意一行开头，该次访问就不写入日志。空行会被忽略。

5.2 访问超时设置

自v1.3.9-beta.13 支持自定义设置,默认60s,单位秒，如果填写0则是不限制

6.导出导入

6.1 导出

导出可以导出所有主机信息,如果是首次可以作为初始化的导入模板来源。

6.2 导入

导入主机信息可以有两个选择：

导入新增主机编码(适用全新数据)
导入保留主机编码(适用老数据数据)

提示

SamWaf是轻量级的防火墙。对于老数据迁移，推荐的方式是关闭服务后，直接拷贝SamWaf安装目录下的所有数据到新服务器即可。

7.同时绑定多个域名

可以支持多个域名一行一个。支持泛域名

8.健康度检测

系统定时每5秒中进行一次健康度查询，如果配置了负载均衡会剔除已经失效的连接。

8.1 支持自定义配置，

启用健康检测也可以手动关闭
检测方法支持GET HEAD，注意HEAD需要确认后端是否支持
检测路径默认为根目录 /
预期状态码 200，可以自定义HTTP响应码
响应超时时间 5秒
连续失败次数 3次
连续成功次数 3次

8.2 显示健康度情况

9 网站列表页

进入“网站配置”页面后，可看到所有受保护网站的列表，以及一系列管理操作。

9.1 工具栏按钮

按钮	说明
新建防护	打开新增网站表单，添加受保护网站
导出数据	将所有网站信息导出为 Excel（可作为导入模板，见第 6 节）
导入数据	从 Excel 导入网站信息，支持“导入新增主机编码”/“导入保留主机编码”两种策略（见第 6 节）
一键防护开关	一次性修改所有网站的防护状态，可选择 `已防护` 或 `未防护`（会弹出二次确认）
批量复制配置	将某个源站点的指定配置模块复制到多个目标站点（见 9.4）
批量导入nginx网址	跳转到"一键修改"页的"批量导入网址"标签，从 Nginx 配置批量提取站点并添加为被防护主机（见一键修改）
端口占用总览	查看全机每个端口当前被哪些网站以什么协议占用（见 9.6）

右上角支持按网站下拉筛选并查询；表格的网站、主端口、后端 IP、后端端口、备注列还支持列内输入筛选。

工具栏下方是一条分组导航，用于按分组快速筛选网站，分组的新建与维护也在这一行完成（见 9.5）。

9.2 列表展示信息

每行展示：网站（含昵称、SSL 标识、绑定的多域名/多端口）、监听端口、分组、统计信息、状态、后端 IP、后端端口、备注、创建时间、操作。

监听端口列以「端口·协议」标签展示该站的全部监听端口，例如 443·HTTPS、80·HTTP；若该站与本机其它站点在同一端口上声明了不同协议，标签会变红并附带「端口冲突」标记，鼠标悬停可看到处理建议。

分组列显示该网站所属的分组标签，点击标签可直接筛选出同组网站；未归组的网站显示「未分组」，全局网站显示 —。

统计信息列实时展示：PV、UV、拦截（今日攻击数）、入/出流量、QPS、连接数。

状态列包含若干开关与标识：

项	说明
健康状态	后端健康度（开启健康检测后显示正常/异常）
防御状态	防护开关，`已防护` / `未防护`，切换时弹出确认
启动状态	启动开关，`自动启动` / `手工启动`，切换时弹出确认
静态服务	若开启静态网站，显示“开启”标识
来源严格端口	若关闭来源严格端口，显示对应标识

9.3 行操作

每行操作列直接展示两个高频操作：

操作	说明
编辑	打开该网站的配置表单
证书申请	即「SSL证书自动申请」，鼠标悬停可看到全称

其余操作收在更多下拉里：

操作	说明
复制	基于该网站快速创建新网站，会清空 SSL 与绑定关系
删除	删除后该网站信息与规则将被清空且无法恢复

注意：全局网站只能配置防护状态，不能复制、编辑、删除或申请证书。

提示：列较多时表格可以横向滚动，操作列会始终吸附在右侧，左侧的勾选列会始终吸附在左侧，不需要拖到底才能操作。

9.4 批量复制配置

点击 批量复制配置 后：

选择 源站点（已配置的站点）。
勾选要复制的 功能模块，当前支持：缓存、响应压缩。
在 目标站点 列表中勾选一个或多个站点（可全选），目标站点会自动排除源站点。
点击 执行复制，弹窗会显示复制进度，完成后提示成功。

9.5 网站分组

网站多了以后，靠域名模糊搜索定位很费劲，批量操作也只能一行行勾。网站分组用来按你自己的口径（生产/测试/内网、按客户、按机房……）把网站归类。

分组只是组织与筛选维度：它不会给网站带来任何防护配置，也不影响 WAF 对请求的处理。把网站移进移出分组，防护行为完全不变。

9.5.1 分组导航条

工具栏下方一行即分组导航，从左到右依次是：

项	说明
分组	标题
全部网站 N	不筛选，显示所有网站（含全局网站）
未分组 N	只看还没有归组的网站
各个分组 N	点击即筛选该分组；数字是组内网站数
＋新建分组	新建一个分组
⇄ 移动到分组 (N)	把列表里勾选的网站批量移动到某个分组；未勾选时为置灰状态

切换分组时列表会自动回到第 1 页。

9.5.2 新建 / 维护分组

新建：点击「＋新建分组」，填写分组名称（1~50 字符，不能与已有分组重名），从 8 个预设色里选一个标签色，可选填备注。
维护：鼠标移到某个分组上会出现 ⋮，可以进行 重命名 / 改颜色、左移、右移、删除。左移右移用于调整分组在导航条上的顺序。
删除：删除分组不会删除网站。组内网站会回到「未分组」，配置与防护状态一律不受影响。删除前会提示该分组下有多少个网站。

9.5.3 把网站放进分组

有两种方式：

单个网站：在新增或编辑网站的表单里，「基本内容」选项卡有 所属分组 下拉，留空即未分组。下拉旁的「＋新建分组」可以就地建一个新分组并自动回填。
批量：在列表里勾选若干网站（最左侧勾选列），然后点分组导航条上的「⇄ 移动到分组」，选择目标分组，或选「移出分组（未分组）」把它们取消归组。单次最多移动 500 个网站。

全局网站不参与分组，勾选列对它是禁用的；即使通过其它方式带上它，后端也会自动跳过。

9.5.4 常见问题

分组列显示「未知分组」：说明该网站记录里的分组已经不存在了。最常见的原因是从另一台 SamWaf 导入了网站数据（hosts 表），但没有一并导入分组数据。列表不会报错，用「移动到分组」重新归置一次即可。
升级后分组是空的：正常。分组是新增功能，升级后所有网站默认都在「未分组」，与升级前的行为完全一致。

9.6 端口占用总览

工具栏点「端口占用总览」，可以看到全机每个端口当前的占用情况。端口是全机共享资源：一个端口只有一个监听、只能是一种协议，这张表就是用来排查"我配的端口为什么不生效"的。

列	说明
端口	端口号
实际监听	该端口当前真正生效的协议与 IP 版本；未启动监听时显示「未监听」
占用站点	占用该端口的所有网站，标签上标注各自声明的协议，主端口带「主端口」后缀，由「强制80跳转HTTPS」隐式占用的带「自动(HTTPS跳转)」后缀
状态	「正常」/「协议冲突」/「未监听」，冲突行整行标红

出现「协议冲突」说明多个站点在同一端口上声明了不同协议，实际以先加载的站点为准。处理办法是编辑相关站点统一协议，或给其中一方更换端口。

10 引擎自带防护

在新增/编辑网站的“引擎自带防护”选项卡中，可按网站开关各类内置检测：

检测项	说明
Bot 检测	检测是否有伪装的搜索引擎爬虫
Sql 注入检测	检测是否存在 SQL 注入
XSS 检测	检测是否存在 XSS 攻击
扫描工具检测	检测扫描工具
RCE 检测	RCE 远程攻击检测
敏感词检测	敏感词检测
目录穿越检测	目录穿越检测
OWASP 集检测	OWASP 规则集检测
AI 智能检测（测试）	基于机器学习模型检测异常请求，需先上传模型包并开启全局 AI 开关；建议先用观察模式核对误报再切拦截

10.1 仅记录模式

开启“仅记录模式”后，SamWaf 会记录攻击日志但不阻断攻击请求，适合上线初期观察误报。

10.2 IP 提取模式

用于选择如何从请求中提取客户端 IP，该设置会应用于 CC 防护、验证码、IP 白名单等所有功能：

网卡模式：直接从网络连接获取客户端 IP（适用于直连场景）。
代理模式：从 HTTP 头部（X-Forwarded-For 等）获取真实 IP（适用于使用 CDN、Nginx 等代理的场景）。

10.3 真实IP来源（代理模式加固）

选择 代理模式 后，会出现 真实IP来源 下拉，用于决定如何从请求头安全地提取真实客户端 IP，防止直连攻击者伪造代理头绕过黑名单/白名单。网卡模式下此项被忽略。留空即保持旧行为，存量网站零影响。

选择不同来源后，下拉框下方会实时显示该模式的说明，并展开对应的配置项：

默认(兼容,取XFF最左)：取 X-Forwarded-For 最左的一个 IP。最左值可被客户端伪造、不校验来源。存量网站用它零影响；新站建议改用下面三种加固方式。
指定HTTP头：只从你指定的某个头（真实IP头名，如 X-Real-IP/CF-Connecting-IP）取真实 IP。适合确定上游只写这一个头的场景；仍建议配下方 可信代理网段 校验来源。
XFF按层深/可信代理：按反向代理层数，从 X-Forwarded-For 右侧往左数第 N 跳取 IP（nginx 等把真实 IP 追加在右侧）。需填 从右起第N跳 和 可信代理网段；多层自建反代/负载均衡时最准。
CDN厂商预设：选择 CDN 厂商即自动使用该厂商的真实 IP 头，并用中心库的官方回源段校验来源（伪造无效）。厂商无公开回源段时（如 EdgeOne、阿里云），需先到 CDN回源IP 页配置或拉取回源段，否则来源校验会回退网络层 IP。选中厂商后此处只读展示该厂商中心库的已下载条数与上次更新时间，无需手填。

字段说明

字段	说明
真实IP来源	决定代理模式下如何提取真实客户端 IP；留空=旧行为（取 XFF 最左，可被伪造）。
真实IP头名	“指定HTTP头”模式下，从该请求头取真实 IP。
从右起第N跳	“XFF按层深/可信代理”模式下，从 XFF 右侧往左数第 N 个非可信 hop。
可信代理网段	CIDR/IP 逗号分隔。仅当直连对端属于此网段（或所选 CDN 厂商回源段）时才信任真实 IP 头，防止伪造。
CDN厂商	“CDN厂商预设”模式下选择的厂商，决定使用的真实 IP 头与用于来源校验的官方回源段。

在网站编辑页的「Cookie 安全」标签页配置。开启后，SamWaf 会在应答方向给后端下发的 Set-Cookie 自动补齐安全属性——缺失才补、绝不覆盖应用已设置的值，并保留原 Cookie 的全部内容（Path / Domain / Max-Age / Expires 等）。在 HTTP 下不会自动添加 Secure，以免 Cookie 失效。

11.1 操作步骤

编辑网站，切换到「Cookie 安全」标签页。
将「启用 Cookie 安全保护」设为开启（可点击「推荐策略」一键填入建议值）。
按需设置 HttpOnly / Secure / SameSite / 排除的 Cookie 名。
保存网站配置即可生效。

11.2 字段说明

字段	说明
启用 Cookie 安全保护	关闭 / 开启。开启后才会处理后端下发的 Set-Cookie。
HttpOnly	不处理 / 缺失才补。缺少 HttpOnly 时追加，防止脚本读取 Cookie（缓解 XSS 窃取会话）。
Secure	不处理 / 强制添加 / 仅 HTTPS 时自动添加。HTTP 下添加 Secure 会使 Cookie 失效，故「仅 HTTPS 时自动添加」只在当前请求为 HTTPS 时才追加。
SameSite	保持原样 / Lax / Strict / None。选择 None 时会自动补 Secure（浏览器要求 SameSite=None 必须配合 Secure）。
排除的 Cookie 名	命中的 Cookie 原样放过、不加固，逗号分隔。适合三方 / SSO 等需要跨站的 Cookie，例如 `_ga,sso_token`。

推荐策略：开启 + HttpOnly「缺失才补」+ Secure「仅 HTTPS 时自动添加」+ SameSite=Lax。

12 CSRF 防护

在网站编辑页的「CSRF 防护」标签页配置。开启后，SamWaf 会对状态变更类请求（POST / PUT / DELETE / PATCH 等）校验请求的 Origin / Referer 来源是否属于本站，来源非本站时判定为跨站请求伪造（CSRF）并拦截。该能力完全在 WAF 侧透明完成，不需要改动后端代码，也不会影响 GET / HEAD 等安全方法。

判定时优先使用 Origin（更可靠）；当请求没有 Origin 时再用 Referer 判定。本站域名以及在「绑定多域名」中填写的域名会被自动视为可信来源。

前提

CSRF 防护属于请求检测链的一环，需要该网站的防御处于开启状态才会生效（网站列表中防御为开启）。若网站开启了「仅记录模式」，命中只记录日志、不真正拦截。

12.1 操作步骤

编辑网站，切换到「CSRF 防护」标签页。
将「启用 CSRF 防护」设为开启（可点击「推荐策略」一键填入建议值）。
按需勾选保护的请求方法、填写额外允许来源、设置无来源头时的处理方式与排除路径。
保存网站配置即可生效。

也可在「防御」标签页的总览中，直接对「CSRF 防护」「Cookie 安全」做开/关，并点击「配置详情」跳转到对应标签页调整细节。

12.2 字段说明

字段	说明
启用 CSRF 防护	关闭 / 开启。开启后才会对请求做来源校验。
保护的请求方法	仅对勾选的方法（POST / PUT / DELETE / PATCH）做来源校验；GET / HEAD / OPTIONS 等安全方法不校验。
额外允许来源	本站域名与绑定的多域名会自动允许，此处填写额外可信来源。每行一个，支持 `host`、`scheme://host` 或通配 `*.example.com`。
无来源头时	请求既无 Origin 又无 Referer 时的处理方式：放行（默认）/ 拦截。原生 App、curl、服务端调用常无来源头，默认放行可避免误杀；要求更严格时可改为拦截。
排除的路径前缀	命中前缀的路径不做 CSRF 校验，每行一个。适合 webhook、回调、使用 Token 鉴权的 API 等无浏览器来源头的接口，例如 `/api/webhook`。

推荐策略：开启 + 保护 POST/PUT/DELETE/PATCH + 无来源头时放行，并为 API / webhook 类接口配置排除路径。

13 网页防篡改

在网站编辑页的「网页防篡改」标签页配置。开启后，SamWaf 为你指定的静态页面 URL 学习一份「正确页面」基线（内容哈希 + 正文），之后每次该 URL 的应答都会比对哈希；一旦页面被篡改（源站被黑、文件被改），SamWaf 直接把学习到的正确副本回吐给访客，并告警、记攻击日志。

采用反代响应基线比对，SamWaf 与站点文件不必在同一台机器，远程后端也能防；且不额外回源——反代本就要转发后端，防篡改只是在应答回来时顺手比对一次哈希。反向代理与 SamWaf 自身静态伺服（静态站点服务 / 路径路由静态文件）两种出流量都覆盖。

前提

网页防篡改属于应答处理链的一环，需要该网站的防御处于开启状态才会生效。若网站开启了「仅记录模式」，命中只记录日志、不真正替换。基线正文超过「基线大小上限」的页面不学习、不保护。

只适合逐字节稳定的静态资源

逐字节哈希基线只适合每次返回都完全一致的资源：真静态的 .html / .js / .css / 图片等。若页面正文里嵌了每次请求都变的内容（实时时间、CSRF Token、随机数等），会被误判为篡改，请不要对这类动态页添加保护（或先用「仅告警」观察）。

13.1 操作步骤

编辑网站，切换到「网页防篡改」标签页。
将「启用网页防篡改」设为开启（可点击「推荐策略」一键填入：开启 + 替换为正确副本 + 1MB 上限）。
先保存网站（受保护 URL 规则按网站存储，需网站已存在）。
回到「网页防篡改」标签页，在「受保护的 URL」里点「新增受保护 URL」，填精确路径（如 /index.html、/app.js、/logo.png）。
保存后，首次有人访问该 URL 时自动学习基线，状态从「待学习」变为「已学习」。

也可在「防御」标签页的总览中，直接对「网页防篡改」做开 / 关，并点「配置详情」跳转到本标签页。

13.2 从页面批量提取受保护 URL

逐条手加太麻烦时，用「从页面提取」自动发现：

在「受保护的 URL」上方点「从页面提取」。
「选择域名」（下拉是本站主域名 + 绑定的多域名），再填页面路径（默认 /）。
点「提取」——SamWaf 通过该网站已配置的后端抓取这个页面，解析出页面里引用的同站 js / css / html / 图片，带类型标签列出。
默认全部勾选，可自行增减；按需勾「忽略 URL 参数」；点「添加选中」批量建规则（自动跳过已存在的）。

只抓本站、不访问外部地址

提取只会通过该网站已配置的后端抓取（就是平时代理转发的那个后端），不会访问你填的任意外部地址；也只会列出同站资源，页面里引用的第三方 CDN 地址会被自动丢弃。

13.3 重新学习与批量操作

重新学习：你合法更新了页面后内容变了、会被判为篡改，点该行「重新学习」——SamWaf 会立刻从后端重新抓取一次该 URL、当场重建基线（该网站未配置后端时，退回「下次访问时重学」）。
批量重新学习 / 全部重新学习：勾选多行后批量重学，或对本站所有受保护 URL 一次性重学（发版后常用）。
批量删除：勾选多行后一次性删除。
查看基线：查看当前基线的内容类型 / 大小 / 哈希 / 学习时间，文本可展开、图片可预览，并可「下载基线」核对。
受保护 URL 列表支持按各列排序与过滤（受保护 URL、规则名称、启用、基线状态等）。

13.4 字段说明

站点级配置

字段	说明
启用网页防篡改	关闭 / 开启。开启后才会学习并比对受保护 URL。
命中动作	替换为正确副本（推荐）/ 仅告警（监控）。「替换」在比对不一致时回吐基线正确副本给访客并告警、记攻击日志；「仅告警」只告警、仍放行后端页，适合上线初期先观察。
基线大小上限(KB)	超过该大小的页面不学习、不保护，默认 1024（1MB）。关键静态页通常几十 KB。

受保护 URL 规则

字段	说明
受保护 URL	精确路径匹配，如 `/index.html`、`/app.js`；不支持通配 `/*`、目录、参数。
规则名称 / 备注	便于识别的名称与说明，可选。
启用	停用 / 启用该条规则。
忽略 URL 参数	开启（默认）：按路径匹配、忽略 `?v=时间戳` 等缓存刷新参数照常比对（静态资源推荐）；关闭：带参数的请求直接放行、不比对（内容随参数变化的页面用）。
基线状态	待学习 / 已学习 / 超限未学习。
大小 / 命中次数	基线正文大小 / 累计命中篡改次数。

推荐策略：开启 + 命中动作「替换为正确副本」+ 1MB 上限；受保护 URL 只添加真正逐字节稳定的静态资源。

不覆盖服务器文件扫描

本功能防的是「受保护页面的内容被改」，不扫描服务器文件系统、不检测新增文件（如上传的 Webshell），那属于主机型文件防篡改的范畴。

14 文件上传检测

在网站编辑页的「文件上传检测」标签页配置。开启后，SamWaf 对 multipart/form-data 文件上传请求做内容检测，命中危险文件即拦截。四个检测维度可各自独立开关：危险扩展名黑名单、Webshell 内容特征、声明类型与真实内容不符、单文件大小上限。

只检测文件上传请求，其它请求零开销；只处理带文件名的文件字段，普通表单字段由 SQL 注入 / XSS 等检测覆盖。检测过程读取上传内容后会完整放行给后端，正常文件不受影响。

前提

文件上传检测需要该网站的防御处于开启状态才会生效。若网站开启了「仅记录模式」，命中只记录日志、不真正拦截。默认关闭，开启后默认拦截，老网站不受影响。

14.1 操作步骤

编辑网站，切换到「文件上传检测」标签页。
将「启用文件上传检测」设为开启（可点击「推荐策略」一键填入：四个维度全开 + 内置默认黑名单 + 10MB 上限 + 超限拦截）。
按需调整各维度开关、扩展名黑名单、大小上限、只检测/排除路径。
保存网站。

也可在「防御」标签页的总览表格中直接对「文件上传检测」做开 / 关，并点「详情」跳转到本标签页。从总览一键开启时，若四个维度当前全部关闭，会自动套用推荐策略（四维全开），避免「总开关开了却什么都不检测」。

14.2 字段说明

字段	说明
启用文件上传检测	关闭 / 开启。开启后才会对上传请求做检测。
扩展名黑名单检测	开 / 关。命中黑名单的上传文件被拦截。会检查文件名的所有扩展名段（防 `shell.php.jpg` 双扩展名）并处理空字节绕过。
危险扩展名黑名单	逗号分隔，如 `php,jsp,asp,exe`；留空则使用内置默认黑名单（php/jsp/asp/exe/sh/bat 等一系列可执行/脚本后缀）。仅在「扩展名黑名单检测」开启时显示。
Webshell 内容特征检测	开 / 关。扫描文件头部的 Webshell 特征（PHP/JSP/ASP 脚本标记 + `eval`/`system`/`Runtime.exec` 等危险调用的组合），命中即拦。压缩 JS 里孤立的 `eval` 等不会误报。
真实类型检测	开 / 关。嗅探文件真实类型：声称是图片、内容却是脚本 / HTML（改扩展名 + 改 Content-Type 伪装图片）时拦截。
单文件大小上限检测	开 / 关。单个文件超过「大小上限」时拦截。
大小上限(KB)	单文件大小上限，同时也是请求体的可检测缓冲上限，默认 10240（10MB）。
超上限动作	拦截（推荐）/ 放行不检测。上传体超过可检测上限时的处理。默认「拦截」，防止把恶意文件填大来绕过内容检测；确有大文件上传业务的站点可调大上限或改为「放行不检测」。
只检测路径	每行一个路径前缀；留空 = 所有上传都检测。非空时只对命中这些前缀的上传请求做检测。
排除路径	每行一个路径前缀，命中则跳过检测，优先级高于「只检测路径」。适合可信的内部上传接口。

推荐策略：四个维度全开 + 内置默认黑名单 + 10MB 上限 + 超限拦截。

检测范围

仅检测 multipart/form-data 文件上传；base64 内嵌在 JSON 等非标准上传方式不在覆盖范围。Webshell 内容只扫描每个文件的头部（前 64KB），对头部即可识别的一句话木马 / 特征足够。

15 路径路由规则

在网站编辑页的「路径路由」标签页配置。作用类似 Nginx 的 location：同一个网站下，按 URL 路径把不同请求分发到不同去处——可以转发到另一个后端、直接返回本地静态文件、或做重定向。没有命中任何规则的请求，仍按网站原本的后端设置转发。

15.1 操作步骤

编辑网站，切换到「路径路由」标签页。
点「新建」，填写「匹配路径」和「匹配方式」，选择「目标类型」。
根据目标类型填写对应参数（后端代理 / 静态文件 / 重定向）。
保存。规则即时生效，无需重启。

优先级与匹配顺序

一个请求可能同时命中多条规则，此时按「优先级」数字从小到大选取（默认 100）；数字相同时，精确匹配优先于前缀匹配、更长的路径优先。建议把更具体的规则设更小的优先级数字。

15.2 通用字段

字段	说明
网站	规则所属网站。
规则名称	规则的名称，同一网站内不可重复。
匹配路径	以 `/` 开头的 URL 路径。前缀匹配示例 `/api/`，精确匹配示例 `/index.html`。
匹配方式	前缀匹配 / 精确匹配 / 正则匹配。
优先级	数字越小优先级越高，默认 100。
目标类型	后端代理 / 静态文件 / 重定向。选择后展开对应参数。
备注	可选说明。

15.3 目标类型：后端代理

把命中的请求转发到指定后端。

字段	说明
后端协议	连接后端使用的协议：自动（跟随客户端） / HTTP / HTTPS。自动表示客户端用 HTTPS 访问则以 HTTPS 回源、HTTP 则以 HTTP 回源；若后端只支持其中一种协议，请显式选择对应项。
后端主机	后端域名，例如 `backend.example.com`。
后端端口	后端端口。
后端 IP（可选）	留空则按后端主机名解析；填写后直接连接该 IP，跳过 DNS 解析。
响应超时(秒)	等待后端返回响应头的超时时间。`0` = 继承网站的「访问超时」设置；大文件下载或后端启动较慢时可调大。
记录访问请求	默认关闭。开启后，命中该规则的转发请求会记入程序日志（URL、目标地址、状态码、耗时），便于排查请求是否到达后端。
去掉路径前缀	是 / 否。转发时是否去除匹配到的路径前缀，例如匹配 `/api/` 后去掉 `/api/` 再转发给后端。

表单下方有「转发效果预览」，会根据填写内容实时显示「客户端请求」与「实际转发到」两行示例，帮助确认转发效果。

响应超时只管「等首字节」

「响应超时」只限制等待后端开始返回（首字节 / 响应头）的时间，不限制响应体的下载传输时长。因此后端只要及时开始应答，几个 G 的大文件下载多久都不会被这个超时中断；只有后端「憋很久才开口」（如动态打包大文件后才返回）的情况，才需要把该值调大或设为继承网站的无限等待。

路径路由自动支持 WebSocket（ws / wss）

无需任何额外开关。WebSocket 握手本身跑在 HTTP(S) 之上，随「后端协议」一起回源：

后端协议选择自动：客户端用 wss:// 则以 wss 回源、ws:// 则以 ws 回源；
后端协议选择HTTPS：以 wss:// 连接后端；
后端协议选择HTTP：以 ws:// 连接后端。

长连接不受「响应超时」限制——该超时只管等响应头，握手（101）瞬时完成后的双向通信不会被它中断。浏览器发起的 ws/wss 默认走 HTTP/1.1 升级，正常无需额外配置。

15.4 目标类型：静态文件

把命中的请求交给 SamWaf 直接返回本地目录里的静态文件。

字段	说明
静态文件目录	服务器本地目录，例如 `/var/www/html`，用于提供静态文件访问。
SPA 回退模式	开启后，请求路径无对应文件时自动回退到 `index.html`（适用于 Vue/React Router 的 history 模式）。
去掉路径前缀	是 / 否。同后端代理，转发到静态目录前是否去除匹配前缀。

15.5 目标类型：重定向

把命中的请求重定向到另一个 URL。

字段	说明
重定向 URL	重定向目标，例如 `https://example.com/new-path`。
重定向状态码	302 Found / 301 Moved Permanently，默认 302。

16 统一访问认证（站点级）

统一访问认证是全局功能：开启后，访问任何被 WAF 代理的站点都要先登录一次。本标签用于给单个站点开例外。

页面提示：统一访问认证(Access 模式)：开启后，访问本站点必须先通过统一认证。账号在【统一访问认证-访问账号】里维护，全局开关与认证中心在【统一访问认证】配置页。

16.1 本站点策略

取值	说明
继承全局	跟随系统配置里的总开关（推荐）
强制开启	即使全局关闭，本站点也要求登录（适合只保护一个后台）
强制关闭	即使全局开启，本站点也直接放行（适合对外公开的站点）

提示

存量站点默认都是 继承全局，升级后行为不变。

16.2 免认证路径

按路径段匹配，一行一条。用于健康检查、webhook 回调等无法登录的调用方。

填 /api 放行的是这一整棵子树：

请求路径	结果
`/api`	放行
`/api/`	放行
`/api/user/list`	放行
`/apixxx`	不放行

结尾写不写斜杠效果一样，/api 与 /api/ 是同一个意思。

提示

放行的是一棵子树，不是所有同前缀的路径——填 /health 不会顺带放行 /healthz，填 /admin 也不会放行 /adminconsole。证书校验路径 /.well-known/acme-challenge/ 已内置放行，无需填写。

WebSocket 在任何设置下都返回 401，因为它不跟随重定向。

16.6 与网页缓存同时开启的风险

若本站点同时开启了网页缓存，标签页底部会出现红色警告：

注意：本站点同时开启了网页缓存。缓存键不包含用户身份，可能把某个用户的私有页面缓存后返回给另一个已登录用户。建议关闭网页缓存，或只对静态资源启用缓存。

注意

统一访问认证挡得住未登录的访客，但挡不住已登录用户之间的缓存串号。保护私有内容时，建议关闭该站点的网页缓存，或把缓存规则限定为静态资源。

16.7 字段说明

字段	说明
本站点策略	继承全局 / 强制开启 / 强制关闭
免认证路径	本站点专属的免认证路径前缀，一行一条
免认证IP组	命中即在本站点放行的 IP 组
二次验证	继承全局 / 强制 / 豁免
未认证响应	继承全局 / 自动判断 / 一律跳转 / 一律401