YSL语枢-盾甲WAF 部署文档｜反向代理接入与私有化离线部署

获取与安装

YSL 以二进制/镜像交付，客户侧无需编译、无需任何依赖环境。安装介质随商务交付提供：

# 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 部署

一个镜像通用所有客户，授权文件挂载注入，镜像内不含任何机器与私钥信息。推荐 docker compose + host 网络：端口映射会做 SNAT，客户端真实 IP 全变成网桥地址——熔断、限流、指纹聚类的「每 IP」口径会全部失效。

# 1) 加载离线镜像包（商业交付形态） docker load -i ysl-shield-7.0.8.tar.gz # 2) 放好授权 + 配置（路径与镜像内 CMD 一致：/etc/ysl/ysl.prod.json） cp 客户.lic ./ysl.lic cp ./deploy/ysl.prod.json /etc/ysl/ysl.prod.json # 3) 拉起（network_mode: host，透传真实客户端 IP） docker compose up -d # 环境变量覆盖：YSL_UPSTREAM / YSL_LISTEN / YSL_TLS_LISTEN / YSL_LICENSE

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

核心配置项

配置项按组管理（监听/审计/熔断/封禁/上传/AI/响应/蜜罐/检测开关/协议/聚类/同步/DNA/大屏/蜘蛛/多站点/消融等 17 组），完整配置手册见 docs/CONFIG.md，以下为最常用项：

配置项	说明	默认
`listen` / `upstream`	监听地址 / 上游业务 URL（带 scheme，如 `http://127.0.0.1:8080`）	必填
`sandbox_monitor_only`	沙箱仅观察模式：判定照跑、证据留档、不参与拦截	false
`upload_scan`	上传文件体 webshell 签名扫描 + 图像魔数校验	开（显式 false 关闭）
`upload_dirs` / `upload_block_ext`	上传目录后门探测 / 扩展名黑名单（内置 php/phtml/jsp/asp 全家族）	内置
`ai_remote_url`	远程 AI 补充判定端点（空 = 只用内嵌模型，离线可用）	空
`geoip_file`	离线 GeoIP 定位库路径（空 = 大屏光弧回落 IP 指纹示意方位），格式见 GeoIP 专题	空
`sites`	多站点：每站 `domains` + `upstream` + 证书 + 自定义拦截页	空 = 单站点

内置常量（不可配置）：图片像素上限 1e8、PDF 解压预算（单流 500KB / 总量 8MB）、zip 采样（单条 256KB / 总量 16MB）、OLE 宏判据词表——这些是防「用自己的参数把防线调穿」的硬边界。

三态开关惯例

全产品配置遵循统一的三态契约，无隐式行为：

类型	开启	关闭
布尔指针	缺省（默认开）	显式 `false`
数值型	正数（=上限值）	负数
字符串/数组	非空	空

设计理由：常规配置面不给语法级防线留开关——语法事实没有"关掉"的正当理由，这是误报率的底线。唯一的例外是引擎调试口 YSL_ABLATE（层消融，用于「关掉某层看还能不能拦」的对照实验）：它是验证工具，不是运维开关，生产环境不要动。

CLI 命令

命令	用途
`ysl proxy -conf config.json`	反向代理模式（生产主入口；`-addr/-tls/-upstream/-audit` 可覆盖配置）
`ysl analyze -uri "…" [-body …] [-ip …]`	单请求分析：输出动作/分数/证据链完整 JSON（调参与申诉取证）
`ysl replay 语料.jsonl` / `ysl verify 语料.jsonl`	语料回放 / 与期望判定比对（回归自检）
`ysl bench -n 20000`	微基准（吞吐与单请求时延）
`ysl train -corpus …`	训练原生语义模型（写回内嵌模型，热载生效）
`ysl learn -audit ysl_audit.jsonl`	从审计语料挖掘可学习规则（自生长闭环 + FP 回灌）
`ysl clusters -state state.json`	指纹簇巡检（分布式代理池取证）
`ysl license -show / -check / -info / -web`	授权状态查询、离线激活校验、图形化签发台
`ysl audit`	审计日志查询与统计

商业授权

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

授权文件由签发方 Ed25519 私钥签发，与机器指纹绑定。到期后防护停止，续期更换授权文件即可，无需重装产品。申请试用请联系我们。

安全注意事项

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