部署 & 安装

• 1: Linux 部署（systemd）
• 2: Docker Compose 部署
• 3: Windows 部署
• 4: macOS 部署

1 - Linux 部署（systemd）

本指南适用于 Linux 物理机、云服务器和虚拟机。在线安装会自动选择语言、识别 CPU 架构、拉取最新稳定版发行包、校验校验和文件、在可用时安装 systemd 服务并输出初始化地址；无法访问 GitHub 时，请使用文末的离线流程。

1. 一键安装（推荐）

只需复制并粘贴以下命令。脚本会在交互终端中询问语言，随后自动完成下载、校验和安装：

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

如果当前用户已经是 root，可以省略 sudo：

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

脚本需要从 /dev/tty 读取语言、安装根目录和安全入口输入，因此即使脚本内容通过标准输入传入，也不会把交互输入误当作脚本内容。无人值守环境请设置文档列出的 CHEESEWAF_* 环境变量后运行已下载的脚本；不要把密码或安装 Token 写入命令行历史。

如需安装指定的稳定版或 Beta 版本，可设置 CHEESEWAF_RELEASE（v 前缀可省略）：

curl -fsSL https://github.com/LaokeQwQ/CheeseWAF/releases/latest/download/install-linux.sh \
  | sudo env CHEESEWAF_RELEASE=v0.4.2-beta bash

选择语言后，交互流程会询问应用安装根目录。例如输入 /opt/cheesewaf，二进制、Web 资源、运行时配置、数据和日志会分别放在该目录下的 bin/、web/、config/、data/、logs/ 子目录。直接回车则保留下面列出的分散式 FHS 默认布局。除非显式设置 CHEESEWAF_UNIT_DIR，systemd 单元仍安装在 /etc/systemd/system。

自动化部署时，可在调用安装器前设置 CHEESEWAF_INSTALL_DIR。如果同时设置 CHEESEWAF_PREFIX、CHEESEWAF_WEB_DIR、CHEESEWAF_CONFIG_DIR、CHEESEWAF_DATA_DIR 或 CHEESEWAF_LOG_DIR，对应的单独目录覆盖根目录派生值：

curl -fsSL https://github.com/LaokeQwQ/CheeseWAF/releases/latest/download/install-linux.sh \
  | sudo env CHEESEWAF_INSTALL_DIR=/opt/cheesewaf bash

安装根目录必须是绝对路径，并且每个路径段只能使用 ASCII 字母、数字、.、_ 或 -；共享系统目录以及含 Shell 元字符的路径会被拒绝。

安装过程会依次完成：

1. 选择中文或 English，并检测 Linux、架构、磁盘空间、curl、tar、sha256sum、awk 和 od 等前置条件。
2. 从 GitHub Releases 拉取指定服务器发行包，校验对应的唯一 SHA256SUMS 条目；校验失败会立即停止，不会启动旧或未知来源的程序。
3. 将二进制、Web 控制台、运行时配置和 systemd 单元安装到标准路径，并创建无登录权限的 cheesewaf 系统用户。
4. 生成 HTTPS 管理监听、一次性初始化 Token 和安全入口。入口路径只允许 ASCII 字母和数字；脚本会默认生成随机值，也允许你输入自定义值，不符合规则时会拒绝继续。
5. 在可用时启动 systemd 服务，检查端口和健康状态，并打印版本、架构、安装路径、配置/数据/日志路径、服务状态、公网管理地址、检测到的内网管理地址、Token 有效期和后续操作。没有 systemd 时只安装文件，并明确报告服务未启动。

安装结束时请保存终端输出中的完整初始化地址。交互终端会打印公网初始化地址和安全入口，也会打印每个检测到的内网地址；非交互运行默认不向标准输出回显敏感信息，而是写入仅 root 可读的 install-secrets.txt 回执，只有在输出环境受保护时才设置 CHEESEWAF_SHOW_SECRETS=1。Token 只在首次初始化阶段有效，默认短期有效且完成初始化后立即撤销；不要把完整地址提交到工单、截图、Shell 历史或日志。

2. 首次初始化与公网入口

初始化期间，使用安装器输出的 https:// 地址打开向导。初始化地址固定使用 /setup 路径：

https://PUBLIC_IP:9443/setup#setup_token=ONE_TIME_TOKEN

其中 ONE_TIME_TOKEN 是一次性初始化 Token。浏览器会从 URL fragment 读取 Token，随后清理地址栏，并通过 X-CheeseWAF-Setup-Token 请求头提交；Token 不会放在查询参数、Cookie 或 localStorage 中。

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

该安装路径默认使用 HTTPS 并公开绑定管理面。安装器会将检测到的公网主机写入 admin.env；如果服务器位于 NAT 或反向代理之后且没有直接公网地址，请设置 CHEESEWAF_ADMIN_PUBLIC_HOST。生产环境应进一步限制安全组、防火墙和反向代理来源，只允许受信管理网络访问 9443；不要把初始化地址分享给其他人。若证书由本机临时生成，浏览器首次访问会显示证书警告，生产环境请替换为受信证书。

向导完成后，初始化 Token 立即失效。遗失地址时，可在服务器上查看权限为 0600 的运行时文件，或在管理员尚未创建前重置 Token：

sudo -u cheesewaf cheesewaf setup token reset

重置后必须使用命令输出的新地址；旧地址不可恢复。

对已有配置再次运行安装器会执行升级：现有监听地址、TLS、站点、策略和安全入口会保留。请使用同一安装根目录，或再次设置相同的 CHEESEWAF_*_DIR 覆盖项，确保升级的是预期实例。

3. 安装后检查

systemctl status cheesewaf --no-pager
ss -ltnp | grep ':9443'
sudo journalctl -u cheesewaf -n 100 --no-pager

检查输出中的版本和架构是否与目标服务器匹配，并确认管理端口只由预期进程监听。完成初始化后，再到控制台接入第一个站点和配置数据面监听。

默认 FHS 路径如下：

当设置 CHEESEWAF_INSTALL_DIR=/opt/cheesewaf 时，对应的应用路径为 /opt/cheesewaf/bin/cheesewaf、/opt/cheesewaf/web、/opt/cheesewaf/config/cheesewaf.yaml、/opt/cheesewaf/data 和 /opt/cheesewaf/logs。

4. 离线或手动安装

在可联网机器上，从 GitHub Releases 下载与服务器架构匹配的完整 .tar.gz、SHA256SUMS 和（发布时提供的）签名文件，再将它们传到目标服务器。在下载目录先校验并解压，然后进入解压目录执行安装器：

sha256sum --check SHA256SUMS --ignore-missing
tar -xzf cheesewaf-*-linux-*.tar.gz
cd cheesewaf-*-linux-*
sudo ./install-linux.sh

离线脚本仍会在本地交互选择语言、生成安全入口并启动服务，但不会尝试重新下载发行包。若系统没有 systemd，请改用手动方式复制二进制和 web/dist，并由现有进程管理器启动；必须保留运行时配置副本与数据目录，不能直接修改仓库中的 configs/cheesewaf.yaml 模板。

不要使用未经校验的二进制、第三方镜像或旧版安装脚本。完整安装包包含 cheesewaf、Web 资源、配置模板、systemd 单元和本安装脚本；缺少其中任一项时应停止并重新下载。

2 - Docker Compose 部署

本方案适用于容器化云原生基础设施。仓库提供经过加固的 Dockerfile 与 Compose 示例，示例会在本地构建镜像；除非另行核对镜像来源，否则不要把 cheesewaf:dev 当作厂商签名或已发布到可信仓库的镜像。运行时默认使用专用非 root 用户（UID 10001）并启用只读根文件系统。

容器资源由宿主机和容器限制共同决定。逻辑核数不超过 2 或内存不超过 2 GB 时，初始化向导会推荐 low；探测失败或超时也会回退到 low。Compose 示例只把管理端口绑定到宿主机回环地址 127.0.0.1:9443。storage.profile: production 当前仍会因生产接线不完整而拒绝启动，不会回退到 SQLite。

编排配置（Compose 文件）

参考项目仓库中的 deploy/docker/docker-compose.yml：

services:
  cheesewaf:
    image: cheesewaf:dev
    build:
      context: ../..
      dockerfile: deploy/docker/Dockerfile
    user: "10001:10001"
    restart: unless-stopped
    read_only: true
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    tmpfs:
      - /tmp:size=32m,mode=1777,noexec,nosuid,nodev
    ports:
      - "8080:8080"
      - "127.0.0.1:9443:9443"
    volumes:
      - cheesewaf-data:/var/lib/cheesewaf
      - cheesewaf-logs:/var/log/cheesewaf
    healthcheck:
      test: ["CMD", "/usr/local/bin/cheesewaf-entrypoint", "healthcheck"]
      interval: 30s
      timeout: 5s
      retries: 3

volumes:
  cheesewaf-data:
  cheesewaf-logs:

启动与初始化

执行以下命令在后台启动容器并观察日志：

docker compose -f deploy/docker/docker-compose.yml up -d
docker compose -f deploy/docker/docker-compose.yml logs -f cheesewaf

容器首次启动时会自动在持久化目录生成初始管理员配置，并为管理平面签发自签名证书。本 Compose 文件将管理端口仅绑定到 Docker 宿主机回环地址（127.0.0.1:9443），请在宿主机浏览器中打开 https://127.0.0.1:9443/setup。从其他机器访问时，请先将 CHEESEWAF_SSH_TARGET 设置为 SSH 目标，再执行 ssh -N -L 9443:127.0.0.1:9443 "$CHEESEWAF_SSH_TARGET" 建立隧道，之后仍使用同一回环地址；如需直接暴露端口，请显式修改绑定并配置相应的访问控制。亦可执行以下命令通过容器终端进行 CLI 初始化：

首次初始化尚未完成时，容器日志不会打印初始化 Token 或完整地址，只显示基础 /setup 地址、受保护的 /var/lib/cheesewaf/setup.url 路径和不含秘密的随机回执。请在 10 分钟有效期内从权限为 0600 的文件读取完整地址。初始化完成后，Token 会被撤销；过期的 setup.url 文件会被清理。

docker compose -f deploy/docker/docker-compose.yml exec -it cheesewaf \
  cheesewaf --config /var/lib/cheesewaf/config/cheesewaf.yaml \
  --data-dir /var/lib/cheesewaf setup

停止容器（docker compose -f deploy/docker/docker-compose.yml down）时，SQLite 数据、证书、自定义规则和日志会保存在命名卷 cheesewaf-data 与 cheesewaf-logs 中。配置 storage.postgresql 时，它接收外部访问日志；默认 storage.profile: temporary 下，Docker 卷仍保存管理数据库。预留的 production 配置当前会在启动时拒绝。

3 - Windows 部署

在 Windows 操作系统中，CheeseWAF 提供三种运行分发形态，底层核心功能与防护引擎完全一致：

初始化向导会根据本机资源推荐档位。逻辑核数不超过 2 或内存不超过 2 GB 时使用 low；探测失败或超时也会回退到 low。管理面默认只监听 127.0.0.1:9443，本地辅助控制器另监听 127.0.0.1:17943。

1. 单文件 CLI 与原生 Windows 服务

适用于快速调试、脚本调用或注册为 Windows 系统服务：

# 前台交互式启动 WAF 转发与管理服务
.\cheesewaf.exe serve --config .\data\config\cheesewaf.yaml --data-dir .\data

# 查询服务运行状态与 PID 租约
.\cheesewaf.exe status

# 安全终止运行中的服务
.\cheesewaf.exe stop

原生 Windows 系统服务感知

cheesewaf serve 内置了原生 Windows 服务状态机（基于 golang.org/x/sys/windows/svc）：

• 当被 Windows 服务控制管理器（SCM）拉起时，程序会自动识别为服务运行模式，无缝响应 SCM 的停止（Stop）与关机（Shutdown）信号并执行优雅退出。
• 服务名称默认注册为 CheeseWAF，无需借助第三方包装工具（如 NSSM 或 WinSW）。

2. 便携 Zip 压缩包

便携包内包含预设的配置文件模板与编译好的 Web 控制台静态资源：

1. 将 cheesewaf-amd64-windows-*.zip 解压至指定目录（如 D:\CheeseWAF）。
2. 在该目录下通过 PowerShell 执行初始化与启动：

# 首次运行推荐通过交互式向导配置凭证
.\cheesewaf.exe setup

# 启动 WAF 守护进程
.\cheesewaf.exe serve --config .\data\config\cheesewaf.yaml --data-dir .\data

首次初始化尚未完成时，进程日志只显示基础 /setup 地址、受保护的 data\setup.url 路径和不含秘密的随机回执。请在 10 分钟有效期内从权限为 0600 的文件读取完整地址。初始化完成后，Token 会被撤销；过期的 setup.url 文件会被清理。

3. NSIS 图形安装向导 (推荐)

适用于需要图形化引导、注册 Windows 服务与创建系统快捷方式的生产或办公桌面环境：

1. 下载并运行 cheesewaf-amd64-windows-*-setup.exe 安装包（Windows ARM64 请使用 arm64 版本）。
2. 按照向导提示选择安装路径。安装程序会注册 CheeseWAF Windows 服务，并设置为手动启动（start= demand）；需要时可通过服务管理器或 sc.exe 显式启动/停止。
3. 卸载程序时，系统将默认保留 data\ 目录中的业务数据库与配置文件，防止误删历史数据。

本地辅助控制器（GUI）

cheesewaf-gui 是面向桌面环境的轻量级浏览器本地控制器，用于便捷管理主服务进程的生命周期：

• 网络边界：严格限制仅监听本地回环地址 127.0.0.1:17943，杜绝局域网未授权探测。
• 核心功能：启动/停止/重启服务、显示运行状态与 PID、直达 Web 管理控制台及快捷打开配置目录。
• 运行模型：按需调用本地 cheesewaf serve 进程，不是第二套管理后台；控制器仅监听本机回环地址。

.\cheesewaf-gui.exe --config .\data\config\cheesewaf.yaml --data-dir .\data

启动后可在浏览器中直接打开 http://127.0.0.1:17943/ 进入桌面控制器界面。

4 - macOS 部署

在 macOS 系统下，CheeseWAF 支持桌面图形包与命令行压缩包两种运行方式：

初始化向导会根据本机资源推荐档位。逻辑核数不超过 2 或内存不超过 2 GB 时使用 low；探测失败或超时也会回退到 low。管理面默认只监听 127.0.0.1:9443。

1. DMG 桌面安装包

适用于本地开发调试与桌面工作站环境：

1. 根据芯片架构下载安装包：Apple Silicon（M 系列芯片）选择 cheesewaf-arm64-darwin-*.dmg，Intel 芯片选择 cheesewaf-amd64-darwin-*.dmg。
2. 双击打开 DMG 镜像，将 CheeseWAF 拖拽至 Applications（应用程序） 文件夹。
3. 从启动台或应用程序文件夹中启动 CheeseWAF。

程序启动后将拉起基于浏览器的本地控制器服务（监听回环地址 http://127.0.0.1:17943/），支持一键启动/停止主服务、查看运行状态及快速直达 Web 管理控制台。默认运行时数据目录为 ~/Library/Application Support/CheeseWAF。

2. 命令行压缩包（tar.gz）

适用于纯终端操作或无图形界面环境：

# 解压对应架构的压缩包
tar -xzf cheesewaf-arm64-darwin-*.tar.gz
cd cheesewaf-*

# 运行终端初始化向导
./cheesewaf setup

# 启动 WAF 守护服务
./cheesewaf serve --config ./data/config/cheesewaf.yaml --data-dir ./data

如果首次 Web 初始化尚未完成，进程输出只显示基础 /setup 地址、受保护的 data/setup.url 路径和不含秘密的随机回执。请在 10 分钟有效期内从权限为 0600 的文件读取完整地址。初始化完成后，Token 会被撤销；过期的 setup.url 文件会被清理。

服务启动后，使用浏览器访问 http://127.0.0.1:9443/ 进入 Web 管理控制台登录页。