TL;DRYSL 语枢·盾甲 WAF 以二进制或镜像方式交付支持一键脚本setup.sh、手动离线包、Docker compose 三种部署方式客户侧无需编译也不依赖任何运行环境。产品内置 30 天评估授权装完即用评估满意后更换授权文件即可转为正式版配置、审计和规则全部保留。生产环境推荐使用 Docker compose 并坚持network_mode: host避免端口映射做 SNAT 导致真实客户端 IP 丢失从而保证熔断、限流和指纹聚类的「每 IP」口径正常生效。部署完成后务必执行ysl license -check校验授权门禁再用ysl analyze -uri /?id1验证单请求判定链路确认防护、授权和取证三条链路全部打通。目录三步上线手动安装离线包裸机部署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 /?id1Windows 用户注意建议将 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.jsonYSL 语枢-盾甲 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[验证容器状态与真实 IPbr/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: :80WAF 的监听地址:80表示监听宿主机所有网卡的 80 端口。业务已占用 80 时改成:8081之类再把入口流量指向新端口。/etc/machine-id:/etc/machine-id:ro把宿主机机器码以只读方式挂进容器容器内据此计算机器码保证授权与宿主机绑定一致。:ro表示容器无法改写宿主机文件。Docker DesktopWindows / 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-idcompose 已将宿主机上的这一个文件以只读方式挂载进去Docker DesktopWindows / macOS宿主机没有这个文件可改用YSL_MACHINE_ID指定固定串。挂载卷中的 audit、state、learned 目录由容器入口自动补建并交给 uid 1100审计日志照常落盘取证主进程不以 root 身份运行。升级新版本镜像 load 后执行docker compose up -d重建容器即可配置、授权与审计数据都在宿主机挂载卷中不受镜像更换影响。以下为进阶参考装完能用就不用往下看。三种部署方式对比三种方式交付的是同一套引擎差别主要在落地成本和可控粒度上下表按五个维度做个对照对比维度一键脚本 setup.sh手动离线包Docker compose适用场景首次试用、快速验证或不想关心底层是 Docker 还是裸机的场景内网离线环境、需要自行校验安装介质或要按二进制方式精细控制部署目录已有容器化运维体系需要多站点、证书挂载、环境变量覆盖等精细配置是否需要外网需要脚本通过curl从官网拉取安装脚本不需要安装包可离线拷贝配合 SHA256 校验不需要docker load加载整包镜像up -d不再拉取任何内容授权注入方式安装后执行activate.sh一条命令激活机器码在安装完成时打印手动执行ysl license -activate ./客户.lic授权落到/etc/ysl/ysl.lic把./ysl.lic挂载到/etc/ysl/ysl.lic或用YSL_LICENSE环境变量指定升级方式重新执行setup.sh脚本按当前环境走对应升级路径替换二进制或解压新版本包配置文件与审计数据保留在原目录加载新镜像后docker compose up -d重建容器数据在宿主机挂载卷中不受影响真实客户端 IP 是否保留保留脚本按环境生成默认配置裸机直接监听端口保留二进制直接监听端口无额外网络层保留前提是使用network_mode: host若改用ports:端口映射会做 SNAT真实 IP 会变成网桥地址选型建议只想尽快跑起来验证效果直接用setup.sh一条命令生产环境且已有容器化运维体系选 Docker compose 并坚持 host 网络完全离线或需要按二进制方式掌控部署细节则用手动离线包。配置文件装完通常不用动绝大多数客户装完什么都不用改setup.sh已生成默认配置并直接启动。只有以下场景才需要打开配置文件你想做的事改哪里更换监听端口或上游业务不在 8080listen/upstream安装时已自动生成灰度期先只看不拦跑稳后再切换拦截sandbox_monitor_only: true网站有上传功能想关闭上传文件扫描upload_scan: false默认开启多个网站共用同一台 WAFsites每站填写域名、上游和证书默认空表示单站点大屏地图要显示真实访客经纬度geoip_file指向离线 GeoIP 库格式见 GeoIP 专题留空则显示示意方位接入企业自建 AI 判定服务ai_remote_url留空则只用内嵌模型离线可用配置开关读法全产品统一不写表示默认开启显式写false表示关闭数值为正数表示开启即上限值负数表示关闭字符串非空表示开启空字符串表示关闭。完整手册在安装包内docs/CONFIG.md共 17 个配置组。内置常量不可调图片像素上限、PDF/zip 解压预算等是防止「参数把防线调穿」的硬边界在配置文件中无法修改这是误报率的底线。引擎调试口YSL_ABLATE是验证工具而非运维开关生产环境不要改动。常用命令日常真正用到的只有这五条其余都是回归调优工具见本节末尾做什么命令启动 WAF生产主入口ysl proxy -conf /etc/ysl/config.json获取机器码申请授权用ysl license -show激活收到的授权文件ysl license -activate ./客户.lic授权出问题时逐道门禁体检ysl license -check测试某个 URL 是否会被拦截输出判定 JSON 和证据链ysl analyze -uri /?id1其余命令ysl audit用于审计查询统计replay、verify、bench、train、learn、clusters是语料回放、基准测试、模型训练、指纹巡检等回归调优工具日常运维用不到详见安装包内docs/。常见问题排查下面五条是部署过程中最常遇到的故障按「现象 / 可能原因 / 排查命令或改法」三列给出定位思路命令与上文保持一致现象可能原因排查命令或改法执行bash -c $(curl -fsSL https://waf.duduziy.com/dl/setup.sh)报curl: (6) Could not resolve host或长时间无响应客户机无外网出口、DNS 未配置或代理拦截了 HTTPS 请求先确认连通性curl -I https://waf.duduziy.com/dl/setup.sh内网环境改用离线包执行docker load -i ysl-shield-7.0.8.tar.gz或tar xzf ysl-shield-7.0.8-linux-amd64.tar.gz -C /opt/ysldocker load成功但docker compose up -d后容器立即退出授权文件未放到./ysl.lic、配置文件路径写错或宿主机端口已被占用查看退出原因docker compose logs --tail100确认授权已就位ls -l ./ysl.lic检查端口占用ss -lntp | grep :80ysl license -check报机器码不匹配授权文件是在另一台机器上签发的或容器内缺少/etc/machine-id导致机器码变化先取当前机器码ysl license -show与申请授权时提供的机器码比对容器场景确认已只读挂载宿主机/etc/machine-idDocker Desktop 可改用YSL_MACHINE_ID指定固定串已使用 host 网络但审计日志里客户端 IP 仍是网桥地址compose 中仍保留了ports:端口映射或流量前面还有一层反向代理/NAT检查 compose 文件grep -nE network_mode|ports docker-compose.yml确认写的是network_mode: host且没有ports:再逐层确认上游代理是否透传真实 IP套用ysl.prod.json后启动直接失败日志提示证书相关错误样例中的证书路径是示例值实际证书文件不存在或路径未挂载进容器核对配置中的证书路径grep -n cert /etc/ysl/ysl.prod.json确认文件存在ls -l /etc/ysl/certs/容器场景还需把证书目录挂载进容器后再执行docker compose up -d排查顺序建议先看进程是否起来docker compose logs或ysl proxy -conf /etc/ysl/config.json前台输出再看授权是否通过ysl license -check最后用ysl analyze -uri /?id1验证单请求判定链路是否正常。商业授权一句话概括授权文件与机器绑定由 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 /?id1验证单请求判定链路确认能输出完整的动作、分数和证据链第三确认审计日志已正常落盘容器场景检查宿主机挂载卷中的audit目录需要集中留存时再开启 CEF 输出对接 SIEM。这三步都通过说明防护、授权和取证三条链路已经打通可以放心把入口流量切到 YSL。
