企业官网建设流程全解析

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。