这是本节的多页打印视图。 .

快速上手

三步快速完成 CheeseWAF 系统初始化、首个站点接入及大模型异步审查配置。

1: 系统初始化向导
2: 接入首个业务站点
3: 接入大语言模型

先执行 Linux 一键安装。脚本会询问语言、拉取并校验最新稳定版、生成公网 HTTPS 管理入口并输出短期初始化地址，然后按照以下三个核心步骤完成防护：

BASH

curl -fsSL https://github.com/LaokeQwQ/CheeseWAF/releases/latest/download/install-linux.sh | sudo bash

语言选择后，安装器会询问应用安装根目录。输入 /opt/cheesewaf 可将二进制、Web 资源、配置、数据和日志集中在同一目录；直接回车则使用标准 FHS 布局。安装完成后会输出公网和检测到的内网初始化地址；需要指定版本时设置 CHEESEWAF_RELEASE=vX.Y.Z[-beta]。自动化变量、升级行为和安全入口说明请参考 Linux 安装指南。

1. 系统初始化

访问 /setup 向导，创建首个系统管理员账号，妥善保存初始化密钥并确认管理网络边界。

2. 接入首个站点

配置对外业务域名、后端上游源站地址，设定初始防护等级为推荐的智能标准等级（3 级）。

3. 接入大模型审查

配置兼容 OpenAI 或 Anthropic 协议的大模型接口，为 ALAP 启用异步智能研判与规则闭环沉淀。

请妥善保管完整 HTTPS 初始化地址。URL fragment 中包含一次性 Token，浏览器会将它转换为 X-CheeseWAF-Setup-Token 请求头，初始化完成后立即撤销。目标服务器无法访问 GitHub 时，请从发行页下载带签名的发行包和校验文件，再按离线安装章节操作。

即使尚未配置大模型接入，CheeseWAF 的数据平面依然能基于内置 AST 语义引擎提供全量实时的攻击检测与阻断。未配置 ai 参数前，ALAP 异步审查队列将保持待机状态。

1 - 系统初始化向导

使用 Web 初始化向导或终端 cheesewaf setup 命令完成硬件探测、画像适配、管理员凭证创建与管理边界配置。

首次安装 CheeseWAF 后，系统尚未生成管理员凭证与业务站点配置。CheeseWAF 提供 Web 图形向导 与 终端 CLI 向导 两种初始化方式，用户可根据部署场景自由选择。

方式一：终端命令行初始化向导（推荐运维使用）

在终端中执行以下命令即可启动轻量级交互式向导：

BASH

cheesewaf setup

1. 自动化硬件探测与画像适配

向导启动时会自动探测主机的计算与存储资源（CPU 核心数、物理可用内存及磁盘挂载容量），并智能推荐最适配的运行画像（Hardware Profile）：

low（轻量模式）：适合 1～2 核 CPU / 1～2 GB 内存的轻量云服务器或小内存 VPS；请求检测超时自动降级到此档。
smart（智能模式，默认）：推荐 2～4 核 CPU / 4～8 GB 内存的普通云服务器使用；根据请求风险动态分配检测深度。
medium（均衡模式）：手动指定，固定检测深度 2，单请求耗时上限 50 ms。
high（强力模式）：适合 4 核以上 CPU / 8 GB 以上内存的核心业务网关，执行全量深度语义分析。
custom（自定义模式）：手动精确调优各项检测深度与超时预算。

探测最长运行 30 秒。探测超时或失败时，向导会自动回退推荐 low 档，后续也可在管理后台随时调整。

2. 交互式凭据录入与安全事务保障

用户名：输入 3–32 个 ASCII 字符的用户名。用户名必须以 ASCII 字母开头、以 ASCII 字母或数字结尾，只能包含 ASCII 字母、数字、.、_ 和 -。非 ASCII 字符、Unicode 空白字符、控制字符（Cc）和格式/不可见字符（Cf）都会被拒绝；服务端保留原始值，不会自动去除空格或转小写。
密码：新密码至少需要 10 个字符，并满足大写字母、小写字母、不重复数字、特殊字符 4 类中的至少 3 类。常见密码和简单模式会被拒绝，密码也不能等于或包含用户名。Web 向导的确认步骤只显示密码已设置，不显示密码、密码哈希、系统主加密密钥或管理员凭证摘要。
可选集成：交互式终端向导在提交配置时可以应用 GeoIP、Prometheus /metrics 和 VictoriaLogs 设置。Web 向导只会把集成选择记录在初始化草稿中供核对，不会直接应用到运行配置；完成初始化后，还要到对应的系统设置、存储或监控页面配置支持的集成。PostgreSQL 选项只是异步访问日志 Sink，不是管理数据库。
事务性安全承诺：配置、数据库、证书和管理员状态在最终步骤前只保存在内存中，只有最终提交才会写入。中断不会留下部分初始化状态。CLI 语言选择是单独的用户偏好，可能写入 data/cli.lang；这个文件不是运行时配置，也不是管理数据库。

3. 脚本无交互自动化（Headless Mode）

在 CI/CD 自动化流水线或云主机批量装机时，可传入命令行标志实现全自动无人值守初始化：

BASH

cheesewaf setup --yes \
  --username admin \
  --password-stdin < /etc/cheesewaf/secrets/admin_pass.txt \
  --admin-listen 0.0.0.0:9443 \
  --skip-probe

注意：无人值守模式下 --yes 必须与 --password-stdin 联合使用，确保初始密码满足安全策略要求；向导执行完成后会根据管理端 TLS 状态自动输出正确的 http:// 或 https:// 访问面板链接。

方式二：Web 浏览器图形向导

1. 打开初始化向导网页

初始化期间，使用安装器输出的 https://PUBLIC_IP:9443/setup#setup_token=ONE_TIME_TOKEN 地址。初始化路由固定为 /setup；Token 只允许短期使用一次。

一键安装路径默认启用 HTTPS 并允许从公网访问管理面。投入生产前，请使用云安全组、主机防火墙和管理员 IP 白名单限制 9443，并将临时自签名证书替换为受信证书。若你明确需要仅本机管理，可将 server.admin_listen 改为 127.0.0.1:9443 并使用 SSH 隧道；这是主动加固选项，不是一键安装默认行为。

URL fragment 中携带短期一次性 Token。浏览器读取后会清理地址栏，并且只通过 X-CheeseWAF-Setup-Token 请求头提交；Token 不会放在查询参数、Cookie 或 localStorage 中。初始化完成后 Token 会撤销，受保护的 setup.url 文件会被删除或失效。

初始化完成后，访问 https://PUBLIC_IP:9443/SECURITY_ENTRY。安全入口只包含 ASCII 字母和数字，由安装器默认生成，也可以使用通过校验的自定义值；入口会签发访问 Cookie 并跳转到登录页。初始化路由与完成后的安全入口是两个独立路径。

初始化完成后，初始化 Token 也会失效。如果启动前设置了 CHEESEWAF_SETUP_TOKEN，也不要把它写入日志或 Shell 历史。浏览器从 URL fragment 读取 setup_token，立即清除地址栏内容，并且只通过 X-CheeseWAF-Setup-Token Header 发送。

如果直接打开裸 /setup，请从受保护文件复制 Token。它只保留在页面内存中，提交后会清空。不要把 Token 放入查询参数或提交到工单、截图和日志。

2. 创建管理员账号与安全凭据

根据图形页面步骤指引：

输入符合上述用户名规则的用户名。
输入至少 10 个字符、满足 4 类密码要求中至少 3 类，且不包含用户名的密码。
核对配置摘要。摘要会显示用户名、密码已设置、环境检查结果和所选集成；不会显示密码、密码哈希、系统主加密密钥或管理员凭证摘要。

3. 配置管理网络边界

请保持 server.admin_tls 启用，并使用云安全组、主机防火墙和 IP 白名单限制管理入口。
如确需仅本机管理，可显式将 server.admin_listen 改为 127.0.0.1:9443，再通过 SSH 隧道访问；这不是一键安装的默认路径。

完成初始化向导后，访问管理地址将自动重定向至 Web 控制台登录页。后续可通过终端交互工具 waf-cli 或命令行 cheesewaf user 随时重置管理员密码。

初始化向导生成的配置中，update.ota.server 可能预填更新服务地址，但 OTA 默认保持禁用状态（update.ota.enabled: false），当前二进制也没有更新 Worker，不能通过 OTA 下载或安装规则、二进制。请保持该功能禁用；在全隔离内网环境中，也可以将地址置空。

2 - 接入首个业务站点

为 CheeseWAF 配置业务域名、后端上游源站并设定初始防护等级。

1. 配置业务域名

在域名列表中填入对外提供服务的主机名（如 app.example.com）。CheeseWAF 将使用配置的 sites[].domains 列表匹配入站请求的 HTTP Host 请求头。

2. 配置上游源站

填入后端真实的源站服务器地址与端口（如 10.0.0.10:8000）。当配置多个上游源站时，系统将默认采用轮询算法（round_robin）执行负载均衡分发。

3. 设置初始防护等级

新建站点默认使用防护等级 3（智能标准模式）；如果当前版本的向导显示该选项，请保持为 3。该等级会当场阻断高置信度的独立攻击载荷，对夹杂在长文本中的可疑特征执行放行并异步投递 ALAP 审查，兼顾安全性与业务连续性。

4. 保存与热加载配置

点击保存站点。CheeseWAF 支持站点配置的动态热加载，规则生效无需重启主服务进程。

配置完成后，修改本地 hosts 文件或调整 DNS 解析，将域名指向 CheeseWAF 数据平面的监听地址（默认 http://127.0.0.1:8080），验证业务流量能否正常回源代理。

关于健康检查、SSL 证书自动申请及路径重写等高级配置，请参考站点与反向代理配置。

3 - 接入大语言模型

配置兼容 OpenAI 或 Anthropic 协议的大模型接口，为 ALAP 启用异步智能研判与威胁自学习能力。

CheeseWAF 的 ALAP（AI Large-Language-Model Auto Pilot）支持接入主流大语言模型服务，对边界可疑流量进行异步深度语义研判。

在 Web 管理控制台中进入 AI 配置 模块，填写以下参数：

配置项	配置键名	参数说明与示例
启用 AI	`ai.enabled`	ALAP 功能总开关（布尔值）
模型提供方	`ai.provider`	支持 `openai` 或 `anthropic`
接口地址	`ai.api_base`	API Base URL（如 `https://api.openai.com/v1`）
允许私网地址	`ai.allow_private_api_base`	是否允许指向内网/本地模型网关（如 Ollama、LocalAI，布尔值，默认 `false`）
API 密钥	`ai.api_key`	对应模型服务商提供的访问密钥（API Key）
模型名称	`ai.model`	调用的模型标识（如 `gpt-4o-mini`、`claude-3-5-sonnet-latest`）
自动采纳	`sites[].waf.semantic_policy.auto_agree`	站点级配置：开启后，模型判定的高危与严重威胁将自动沉淀为该站点的防护规则

旧配置迁移： 当前版本不会读取旧的 ai.base_url 与 ai.auto_agree。请将 ai.base_url 手动迁移为 ai.api_base，并将审批开关分别迁移到各站点的 sites[].waf.semantic_policy.auto_agree；保存后按需 reload/restart 服务。

运行与安全建议

坚持异步模式：确保配置中 ai.async: true 保持开启状态，严禁在同步实时转发路径中同步等待外部模型返回。
连通性校验：保存配置前，建议点击控制台中的 测试连接 按钮，验证网络连通性与 API 密钥有效性。
渐进式启用自动采纳：在接入初期建议保持 sites[].waf.semantic_policy.auto_agree 关闭，在人工观察审查队列研判质量稳定后，再评估是否开启自动规则沉淀。

关于 ALAP 的工具调用权限、自动化研判流程及定时自学习机制，请参考 ALAP 与审查队列。