YSL语枢·盾甲 WAF 部署教程：从环境准备到上线验证

TL;DR：YSL 语枢·盾甲 WAF 以二进制或镜像方式交付，支持一键脚本 setup.sh、手动离线包、Docker compose 三种部署方式，客户侧无需编译，也不依赖任何运行环境。产品内置 30 天评估授权，装完即用，评估满意后更换授权文件即可转为正式版，配置、审计和规则全部保留。生产环境推荐使用 Docker compose 并坚持 network_mode: host，避免端口映射做 SNAT 导致真实客户端 IP 丢失，从而保证熔断、限流和指纹聚类的「每 IP」口径正常生效。部署完成后务必执行 ysl license -check 校验授权门禁，再用 ysl analyze -uri "/?id=1" 验证单请求判定链路，确认防护、授权和取证三条链路全部打通。

目录

• 三步上线
• 手动安装（离线包）
• 裸机部署
• Docker 部署
• 三种部署方式对比
• 配置文件（装完通常不用动）
• 常用命令
• 商业授权
• 安全注意事项

三步上线

YSL 以二进制或镜像方式交付，客户侧无需编译，也无需准备任何依赖环境。有 Docker 的机器，一条命令即可装完，内置 30 天评估授权，装完即用（单站点，到期自动停止；转为正式版激活后，配置、审计和规则全部保留）。

① 一条命令安装

安装脚本会自动识别 Docker 或裸机环境，安装到 /opt/ysl，重启后不会丢失：

bash -c "$(curl -fsSL https://waf.duduziy.com/dl/setup.sh)"

② 按屏幕上的清单接入业务

安装完成后，终端会打印三步清单：将域名 A 记录指向本机，用 curl 验证业务地址，再用浏览器访问确认防护已生效。本机机器码也会同时打印在屏幕上，用于申请正式授权。

③ 转为正式授权（评估满意后）

把机器码发给我们，收到 ysl.lic 后执行一条命令即可激活，配置、审计和规则全部保留：

bash -c "$(curl -fsSL https://waf.duduziy.com/dl/activate.sh)" /root/ysl.lic

评估授权说明：镜像内置的评估版不绑定机器，仅限单站点，有效期是签发时写死的绝对日期，重装镜像无法续期。转为正式版请通过 activate.sh 一条命令完成，机器码在安装完成时已打印在屏幕上。

手动安装（离线包）

安装介质也支持手动下载，并提供 SHA256 校验：

# Docker 交付：加载离线镜像包（不联网、不拉取基础镜像）
docker load -i ysl-shield-7.0.8.tar.gz
裸机交付：解压即用（Linux amd64/arm64、Windows）
tar xzf ysl-shield-7.0.8-linux-amd64.tar.gz -C /opt/ysl
验证：单请求分析（输出完整判定 JSON，包含动作、分数和证据链）
/opt/ysl/ysl analyze -uri "/?id=1"

Windows 用户注意：建议将 YSL 安装目录加入 Windows Defender 排除列表。产品的攻击检测样本特征真实，可能被安全软件误报。

Add-MpPreference -ExclusionPath 'C:\\ysl'

裸机部署

裸机部署只需一个二进制文件和一个 JSON 配置文件。以下最小配置即可将 80 端口流量反向代理到内网业务：

// /etc/ysl/config.json
{
"listen": ":80",
"upstream": "http://127.0.0.1:8080",
// 沙箱：默认开启；灰度期可用 monitor_only 先观察
"sandbox_monitor_only": false
}
# 启动（-conf 指定配置文件；-upstream、-addr 等参数可覆盖配置）
./ysl proxy -conf /etc/ysl/config.json
YSL 语枢-盾甲 WAF v7.0.8 (YSL Shield WAF)
upstream: http://127.0.0.1:8080
http: :80

业务侧无需任何改造，只需把入口流量指向 YSL 监听端口即可。

Docker 部署

一个镜像可通用所有客户，授权文件通过挂载注入，镜像内不含任何机器信息和私钥信息，体积约 33 MB。如果不想使用 compose，可以直接运行上一节的 setup.sh 一键命令，它检测到 Docker 后会自动走这条路；如需精细控制，可参考下面三步：

flowchart TD
A[加载离线镜像包<br/>docker load -i ysl-shield-7.0.8.tar.gz] –> B[放置授权文件<br/>cp 客户.lic ./ysl.lic]
B –> C[启动容器<br/>docker compose up -d]
C –> D[验证容器状态与真实 IP<br/>docker compose ps / 查看审计日志]

上图是 Docker 部署的四步主流程：先离线加载镜像包，再把授权文件放到 compose 约定的 ./ysl.lic，然后以 network_mode: host 启动容器，最后确认容器处于运行状态且审计日志中记录的是真实客户端 IP，四步全部通过即可把入口流量切到 YSL。

# 1) 加载离线镜像包（由厂商侧 make-release.sh 产出，客户机无需外网）
docker load -i ysl-shield-7.0.8.tar.gz
2) 放好授权：compose 会把 ./ysl.lic 挂载到 /etc/ysl/ysl.lic
cp 客户.lic ./ysl.lic
3) 启动（network_mode: host，透传真实客户端 IP）
docker compose up -d
环境变量覆盖：YSL_UPSTREAM / YSL_LISTEN / YSL_TLS_LISTEN / YSL_LICENSE

下面是可直接使用的完整 docker-compose.yml，与 ./ysl.lic 放在同一目录即可：

services:
ysl:
image: ysl/shield-waf:7.0.8
container_name: ysl-shield
restart: unless-stopped
network_mode: host
environment:
YSL_UPSTREAM: "http://127.0.0.1:8080"
YSL_LISTEN: ":80"
volumes:
– /etc/machine-id:/etc/machine-id:ro
– ./ysl.lic:/etc/ysl/ysl.lic:ro
– ./data/audit:/var/lib/ysl/audit
– ./data/state:/var/lib/ysl/state
– ./data/learned:/var/lib/ysl/learned

逐项说明：

• image: ysl/shield-waf:7.0.8：使用 docker load 导入的本地镜像，写 image: 而不是 build:，因此 up -d 不会触发构建，也不会联网拉取。
• container_name: ysl-shield：固定容器名，便于 docker compose logs ysl-shield、docker compose restart ysl-shield 等日常运维命令直接引用。
• restart: unless-stopped：宿主机重启或进程异常退出后自动拉起，除非人为执行 docker compose stop，保证防护不因意外中断而长时间失效。
• network_mode: host：容器直接使用宿主机网络栈，不做端口映射，因此不会发生 SNAT，审计日志里记录的是真实客户端 IP，熔断、限流和指纹聚类的「每 IP」口径才能正常生效。注意此时不要再写 ports:。
• YSL_UPSTREAM: "http://127.0.0.1:8080"：上游业务地址，即 WAF 把清洗后的流量转发到哪里。host 网络下 127.0.0.1 指宿主机本机，业务跑在其它机器时改成对应内网 IP 和端口。
• YSL_LISTEN: ":80"：WAF 的监听地址，:80 表示监听宿主机所有网卡的 80 端口。业务已占用 80 时改成 :8081 之类，再把入口流量指向新端口。
• /etc/machine-id:/etc/machine-id:ro：把宿主机机器码以只读方式挂进容器，容器内据此计算机器码，保证授权与宿主机绑定一致。:ro 表示容器无法改写宿主机文件。Docker Desktop（Windows / macOS）宿主机没有该文件，可去掉这一行并改用 YSL_MACHINE_ID 指定固定串。
• ./ysl.lic:/etc/ysl/ysl.lic:ro：把当前目录下的授权文件挂载到容器内的授权路径，只读挂载避免容器内误改。换授权时替换宿主机上的 ./ysl.lic 后执行 docker compose up -d 重建容器即可。
• ./data/audit:/var/lib/ysl/audit：审计日志目录，落盘在宿主机，容器重建或升级镜像都不会丢，便于取证和对接 SIEM。
• ./data/state:/var/lib/ysl/state：运行时状态目录，保存限流计数、熔断状态等，持久化后重启不会把统计口径清零。
• ./data/learned:/var/lib/ysl/learned：自学习与指纹聚类产出的模型数据，持久化后升级镜像可继续沿用，不必重新训练。

三个数据目录由容器入口自动补建并交给 uid 1100，主进程不以 root 身份运行；首次启动前也可以手动 mkdir -p data/audit data/state data/learned 预建目录。

为什么推荐 host 网络：端口映射会做 SNAT，客户端真实 IP 会全部变成网桥地址，导致熔断、限流和指纹聚类的「每 IP」口径全部失效。因此 compose 中写的是 network_mode: host，而不是 ports:。

完全不联网，三条保证：

• 镜像包是 docker save 打包的整包，基础层都在里面；
• docker load 之后执行 up -d 不会再拉取任何内容；
• compose 中写的是 image: 而不是 build:，不会触发构建。

默认挂载与配置：默认挂载 deploy/ysl.container.json（单站点，入口和上游通过环境变量配置）；ysl.prod.json 是多站点与证书的参考样例，其中写了示例证书路径，套用前必须先准备好证书文件，否则启动会直接失败。

授权绑定机器码：容器内默认没有 /etc/machine-id，compose 已将宿主机上的这一个文件以只读方式挂载进去；Docker Desktop（Windows / macOS）宿主机没有这个文件，可改用 YSL_MACHINE_ID 指定固定串。挂载卷中的 audit、state、learned 目录由容器入口自动补建，并交给 uid 1100，审计日志照常落盘取证，主进程不以 root 身份运行。

升级：新版本镜像 load 后，执行 docker compose up -d 重建容器即可；配置、授权与审计数据都在宿主机挂载卷中，不受镜像更换影响。

以下为进阶参考，装完能用就不用往下看。

三种部署方式对比

三种方式交付的是同一套引擎，差别主要在落地成本和可控粒度上，下表按五个维度做个对照：

选型建议：只想尽快跑起来验证效果，直接用 setup.sh 一条命令；生产环境且已有容器化运维体系，选 Docker compose 并坚持 host 网络；完全离线或需要按二进制方式掌控部署细节，则用手动离线包。

配置文件（装完通常不用动）

绝大多数客户装完什么都不用改，setup.sh 已生成默认配置并直接启动。只有以下场景才需要打开配置文件：

配置开关读法（全产品统一）：不写表示默认开启；显式写 false 表示关闭；数值为正数表示开启（即上限值），负数表示关闭；字符串非空表示开启，空字符串表示关闭。完整手册在安装包内 docs/CONFIG.md（共 17 个配置组）。

内置常量不可调：图片像素上限、PDF/zip 解压预算等是防止「参数把防线调穿」的硬边界，在配置文件中无法修改，这是误报率的底线。引擎调试口 YSL_ABLATE 是验证工具而非运维开关，生产环境不要改动。

常用命令

日常真正用到的只有这五条，其余都是回归调优工具，见本节末尾：

其余命令：ysl audit 用于审计查询统计；replay、verify、bench、train、learn、clusters 是语料回放、基准测试、模型训练、指纹巡检等回归调优工具，日常运维用不到，详见安装包内 docs/。

常见问题排查

下面五条是部署过程中最常遇到的故障，按「现象 / 可能原因 / 排查命令或改法」三列给出定位思路，命令与上文保持一致：

排查顺序建议：先看进程是否起来（docker compose logs 或 ysl proxy -conf /etc/ysl/config.json 前台输出），再看授权是否通过（ysl license -check），最后用 ysl analyze -uri "/?id=1" 验证单请求判定链路是否正常。

商业授权

一句话概括：授权文件与机器绑定，由 Ed25519 私钥签发，离线激活，不需要联网。

# 查看本机机器码（申请授权时提供）
./ysl license -show
激活：校验并安装授权到系统位置（默认从 ./ysl.lic 安装到 /etc/ysl/ysl.lic）
./ysl license -activate ./客户.lic
逐道门禁校验（签名、机器、有效期、时钟）
./ysl license -check

到期会怎样：防护停止，业务本身不受影响；续期后更换一份新授权文件即可，无需重装产品，配置、审计和规则全部保留。

换机器或重装系统：机器码会变化，联系我们重新签发一份即可，这就是「一机一码」。评估版转正式版同样只需更换授权文件。档位与价格见版本与授权，申请试用请联系我们。

安全注意事项

• 私钥绝不落服务器：授权签发私钥只在签发端，产品包与客户机均不包含。
• 管理台限内网：大屏和管理接口建议只对内网或 VPN 开放。
• 审计日志外送：开启 CEF 输出，可同步至企业 SIEM 集中留存。
• DNA 保护清单：将静态页面和关键配置纳入 DNA 基线，获得篡改还原能力。

总结

三种部署方式交付的是同一套引擎，选型结论可以一句话记住：只想尽快验证效果就用 setup.sh 一键脚本，完全离线或需要按二进制方式掌控部署细节就用手动离线包，生产环境且已有容器化运维体系则选 Docker compose 并坚持 network_mode: host，这样既能保留真实客户端 IP，也能让熔断、限流和指纹聚类的「每 IP」口径正常生效。部署完成后，建议按顺序做完三件事再交给业务方：第一，执行 ysl license -check 逐道门禁校验签名、机器码、有效期和时钟，确认授权状态正常；第二，执行 ysl analyze -uri "/?id=1" 验证单请求判定链路，确认能输出完整的动作、分数和证据链；第三，确认审计日志已正常落盘（容器场景检查宿主机挂载卷中的 audit 目录，需要集中留存时再开启 CEF 输出对接 SIEM）。这三步都通过，说明防护、授权和取证三条链路已经打通，可以放心把入口流量切到 YSL。