系统初始化向导

使用 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 下载或安装规则、二进制。请保持该功能禁用；在全隔离内网环境中，也可以将地址置空。