参数设置

2026/6/30大约 13 分钟

参数设置

参数设置用于集中管理 SamWaf 管理端自身的安全与访问相关配置，对应 conf/config.yml 中的相关项，可在界面修改并即时保存。

菜单路径：系统设置 → 参数设置

1 管理端 IP 白名单

限制可以访问 SamWaf 管理端的来源 IP，支持 CIDR。填写后点击「保存」生效。

注意

若白名单配置错误，可能把自己也挡在管理端之外。此时可编辑 conf/config.yml 的 security.ip_whitelist（如改为 0.0.0.0/0,::/0）后重启恢复，详见常见问题。

2 域名白名单

限制可以通过哪些域名访问管理端。填写后点击「保存」生效。

3 管理端 SSL

为管理端开启 HTTPS 访问。

启用 SSL：开启后管理端支持 HTTPS。
仅 HTTPS：强制管理端只允许 HTTPS 访问。
证书状态：显示是否已上传证书，以及证书域名、到期时间。
证书内容 / 私钥：粘贴 PEM 格式的证书与私钥；也可点击「从证书夹选择」一次性复制，或「上传证书」保存。
绑定证书夹证书：绑定后自动同步——证书夹中的证书更新时，管理端证书随之更新；可随时解绑。
重启管理端：修改 SSL 相关设置后，点击「重启管理端」使其生效。

3.1 怎么给管理端拿到证书

管理端和被防护站点不一样：它通常不对公网开放，所以"文件验证（HTTP-01）"那条路走不通——那种方式需要 Let's Encrypt 从公网访问你的 80 端口。

有域名的话，走 DNS 验证（DNS-01）：验证过程只改 DNS 记录，全程不需要开 80 端口、也不需要把管理端暴露到公网。

已支持的 DNS 托管商：阿里云、华为云、腾讯云、Cloudflare、百度云。

操作步骤：

到「SSL 证书管理」→「证书自动申请」→ 新建，申请方式选「DNS 验证」，填写管理端要用的域名与申请人邮箱；
申请成功后回到本页的「绑定证书夹证书」，选中刚申请的那张；
点击「重启管理端」使其生效。

绑定之后是自动续期 + 自动刷新：证书夹里的证书在到期前 30 天自动续期，管理端证书随之更新，不需要再手工操作。这也是比「粘贴证书内容」更省心的原因——后者每次续期都要重新贴一遍。

域名不必解析到公网

DNS-01 校验的是"你能不能改这个域名的 DNS 记录"，与域名解析到哪个 IP 无关。把域名解析到 192.168.x.x 这类内网地址完全可以，照样能签发证书。

没有域名怎么办

如果只有 IP、连内部域名都没有，DNS-01 用不了。这种情况见下一节的本地证书。

3.2 本地证书（没有域名时用）

只有 IP、或者有域名但不想走证书申请时，可以让 SamWaf 在本机生成一个长效 CA，用它给管理端签发证书。

先明确一点

本地证书加密强度与正式证书完全相同——TLS 的强度与"谁签的"无关。区别只在浏览器默认不认识这个 CA，所以需要在你用来访问管理端的那台电脑上导入一次根证书。导入之后就是正常的绿锁。

操作步骤

在「管理端 SSL」卡片里打开启用 SSL；
找到本地证书，在输入框里填写你实际用来访问管理端的所有地址，逗号分隔。例如：
```
192.168.1.10,waf.internal,localhost,127.0.0.1
```
点击「生成本地证书」；
点击「下载根证书」，得到 samwaf-local-ca.crt，把它拷到你平时访问管理端的电脑上导入（下一节）；
点击「重启管理端」生效。

访问地址一个都不能漏

现代浏览器只看证书里的 SAN 列表，不看 CommonName。你用哪个地址访问管理端，那个地址就必须出现在上面的输入框里，否则用那个地址访问会直接报证书错误。常见的漏项：只填了域名却习惯用 IP 访问、只填了内网 IP 却又从公网 IP 进过一次。填多了没有坏处，漏了才有。

导入根证书

Windows（存储位置是最容易点错的一步，务必按这三步）：

双击 samwaf-local-ca.crt → 点「安装证书」→ 存储位置选「本地计算机」（只给自己用可选「当前用户」）。
关键一步：选「将所有的证书都放入下列存储」，不要用上面那个「根据证书类型，自动选择证书存储」——自动会把它放进「个人」，放错地方等于没装。
点「浏览」→ 在列表里选「受信任的根证书颁发机构」→ 确定 → 下一步 → 完成，弹出安全警告点「是」。

装完重启浏览器：Chrome / Edge 只在启动时读系统信任库，不重启会一直显示"不安全"。

macOS：双击导入到「钥匙串访问」的登录或系统钥匙串 → 找到 SamWaf Local CA 双击 → 展开「信任」→ 「使用此证书时」选始终信任。重启浏览器。

Linux（Debian/Ubuntu）：

sudo cp samwaf-local-ca.crt /usr/local/share/ca-certificates/samwaf-local-ca.crt
sudo update-ca-certificates

Linux（RHEL/CentOS）：

sudo cp samwaf-local-ca.crt /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust

Firefox 用自己的信任库，不读系统的，需要单独导入：设置 → 隐私与安全 → 证书 → 查看证书 → 「证书颁发机构」标签 → 导入 → 勾选「信任由此 CA 标识的网站」。

续期

证书剩余不足 30 天时自动重签，卡片上常显剩余天数；
也可以随时点「重新签发/续期」手动重签（改访问地址同样点这个）；
CA 不变，所以已经导入过根证书的电脑不用再导一次。这正是采用"CA + 服务器证书"两级而不是单张自签的原因。

有效期为什么不是 10 年

CA 自身是 10 年，但服务器证书不能超过 825 天——这是 Apple 平台对任意 CA 签发的 TLS 证书的硬性上限，超了 Safari 与 iOS 会直接拒绝。所以做成"长效 CA + 短效证书自动续期"。

怎么确认"我该删哪一张根证书"

页面上「本地证书」区块会显示当前根证书的 SHA-256 指纹。

这一点在换过根证书之后很关键：信任库里会同时存在多张名字都叫 SamWaf Local CA 的证书，只有指纹能区分——指纹与页面一致的是当前在用的（删了管理端就会重新报"不安全"），指纹对不上的是换 CA 之前留下的旧证书，可以放心删。

卸载根证书

Windows：Win+R 输入 certlm.msc（当初装在"当前用户"的用 certmgr.msc）→ 展开「受信任的根证书颁发机构」→「证书」→ 找到 SamWaf Local CA → 双击核对指纹 → 右键删除。

macOS：打开「钥匙串访问」→ 在系统或登录钥匙串里搜索 SamWaf → 双击核对指纹 → 右键「删除」。

Linux：

# Debian / Ubuntu
sudo rm /usr/local/share/ca-certificates/samwaf-local-ca.crt
sudo update-ca-certificates --fresh

# RHEL / CentOS
sudo rm /etc/pki/ca-trust/source/anchors/samwaf-local-ca.crt
sudo update-ca-trust

Firefox：设置 → 隐私与安全 → 证书 → 查看证书 →「证书颁发机构」→ 选中 SamWaf Local CA → 删除或不信任。

重建根证书（相当于"吊销"）

自建 CA 没有吊销服务（CRL/OCSP），所以没有真正意义上的"吊销"。如果根证书私钥可能泄露、或者就是想换一把，做法是换一套 CA：

「本地证书」→ 展开危险操作 → 点「重建根证书」。

这是破坏性操作

新根证书与旧的没有任何关系。所有导入过旧根证书的电脑会立刻对管理端报"不安全"，必须按上面的步骤删掉旧的、再导入新的。重建后同样需要重启管理端。

清除本地证书

不想再用本地证书了（比如改用了正式证书），可以「本地证书」→ 展开危险操作 → 点「清除本地证书」，会删掉本地根证书与它签发的管理端证书。

两点说明：

如果管理端当前正在使用本地证书，接口会拒绝清除，请先关闭 SSL 或改用其它证书来源——否则删完重启会加载不到证书；
清除只动本地 CA 签发的证书。手工上传的、或从证书夹绑定的证书不会被误删。

清除之后，别忘了到导入过根证书的电脑上把它一并删掉（步骤同上）。

4 安全路径入口

为管理端增加一段「安全码」前缀路径，隐藏后台入口。开启后，所有访问都需要带上该前缀：http(s)://host:port/{安全码}/...。

注意

安全路径作用于整个 HTTP 服务的所有请求，因此不仅是管理界面——WebSocket（/api/v1/ws）、开放平台 API、任何 /api/v1/... 调用都需要改为带前缀的 URL。

打开「启用」开关并填写自定义安全码；自定义安全码留空保存时，后端会自动生成 18 位随机码。
保存后页面会显示完整访问 URL，可「复制 URL」「打开」或「重新生成」访问码。

5 通知标题前缀

设置通知消息的标题前缀，便于在多台 SamWaf 节点的告警中区分来源。填写后点击「保存」。

6 管理端可信代理网段

当 SamWaf 管理端部署在反向代理（如 Nginx）或 CDN 之后时，用于告诉 SamWaf 哪些直连来源是可信代理，从而正确识别真实客户端 IP。管理端 IP 白名单 / 登录锁定 / 令牌 IP 绑定都按识别出的这个 IP 判定。

顶部有一个总开关 管理端位于反代/CDN后：

关闭：一律按直连网络层 IP 判定（管理端未挂在反代/CDN 后时保持关闭最安全）。此时下方配置隐藏。
开启：从代理头识别真实客户端 IP，并展开下面的配置项。开关状态跟随代理头是否有值——有值即为开启。

开启后需要配置“读哪个头”和“信任哪些来源”两部分：

6.1 管理端代理头

按优先级用逗号分隔要读取的请求头，如 X-Forwarded-For,X-Real-IP,CF-Connecting-IP。留空 = 不解析代理头、直接用网络层 IP。 输入框下方提供常用头的快捷标签（点击追加，含 Cloudflare/Fastly/AWS CloudFront/EdgeOne/阿里云/Akamai 各自的真实 IP 头），仍可手动修改。

该项即“参数设置”中的 gwaf_manage_proxy_header，在此修改即时生效；与作用于业务站点的“获取访客 IP 头（gwaf_proxy_header）”是两回事。

6.2 可信来源（①引用CDN厂商 ∪ ②手填网段，两者叠加）

仅当管理请求的直连来源落在“可信代理”内，才采信上面代理头里的真实客户端 IP；否则一律回退网络层 IP，防止伪造。可信代理 = ①引用CDN厂商的回源段 ∪ ②手填网段，两者是叠加（并集）关系，任一命中即可信：

① 引用CDN厂商：若管理端也挂在 CDN 后，选择厂商即自动信任其回源段（读中心库最新值、自动跟随更新，无需手填）。回源段的下载/开启在 CDN回源IP 页统一管理；选中后此处显示该厂商中心库已下载条数。
② 手填可信代理网段：用于 CDN 中心库覆盖不到的场景（如 CDN 后又套自建 Nginx / 内网负载均衡）。CIDR 或 IP，多个用逗号分隔，如 10.0.0.0/8,192.168.0.0/16。留空 = 不额外手填（仍生效①引用的 CDN 厂商）。也可以直接填关键字 private，等价于 10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,127.0.0.0/8,::1,fc00::/7，可与具体网段混写。

只用其一时，另一项留空即可。

注意

手填网段存于 conf/config.yml。若因此被 IP 白名单挡在门外，可直接编辑该文件后重启自救。

6.3 常见部署怎么填

部署形态	代理头	手填可信代理网段
管理端直接对外，前面没有任何代理	留空（总开关关闭）	不用填
Docker / K8s（宿主机端口映射进容器）	按上游实际写的头填	`private`
自建 Nginx 反代（与管理端同机或同内网）	`X-Forwarded-For` 或 `X-Real-IP`	Nginx 所在地址，如 `10.0.0.5`；同内网可用 `private`
挂 CDN（Cloudflare 等）	该厂商的真实 IP 头，如 `CF-Connecting-IP`	留空，改用①引用CDN厂商
CDN 后再套一层自建 Nginx	按最靠近管理端的那一跳写的头填	Nginx 的地址（①②同时用）

不要填 0.0.0.0/0

这类覆盖全网的写法（0.0.0.0/0、::/0，以及把全网拆成两半的 0.0.0.0/1 + 128.0.0.0/1）无法用来判断代理头里哪个 IP 才是客户端 —— 网段把真实客户端也包含进去了，程序分不出"这是代理节点"还是"这就是客户端"。

遇到这类配置，SamWaf 不采信代理头，仍按网络层 IP 识别客户端（容器里就是网关地址，所有访问看起来都来自同一个 IP，IP 白名单与登录失败锁定也因此失去区分能力）。页面上会标红提示，启动日志里也有一条告警。

改法：填上游代理自身的地址；容器/内网部署直接填 private 即可。

6.4 检测本次访问

开启总开关后，卡片里有一个「检测本次访问」按钮，用来核对配置是否符合预期。点击后显示当前这次请求是怎么被判定的：

直连对端：TCP 层看到的地址，以及它是否被判为可信代理、命中的是哪一条（cidr:10.0.0.0/8 / private:... / ip:... / cdn:cloudflare）
代理头逐跳判定：每个配置的头的原始值，以及其中每个 IP 是"可信代理"还是"非可信"
最终采信的客户端 IP 与原因

配置改完存下来后点一下，比翻日志快。该功能只回显你这次请求自身的信息、不接受任何参数，且仅系统管理员可见。

7 CORS 跨域白名单

控制允许跨域（CORS）访问管理接口的来源，防止任意网站携带凭证对管理接口发起跨域请求。

作用：回环 / 本机来源（127.0.0.1、localhost）始终放行，因此本机访问与本地开发无需设置；此处仅需填写异地部署的前端来源。留空 = 仅放行回环。
填写：来源地址，多个用逗号分隔，如 https://waf.example.com,http://192.168.1.10:8080。
同源访问（前端与管理端同域名同端口）不涉及跨域，无需设置。

注意

配置存于 conf/config.yml。若跨域配置错误导致（异地）前端连不上，可直接编辑该文件后重启自救。