PingWAF WAF
简体中文
English EN 简体中文 ZH Español ES Français FR 日本語 JA
GitHub
概览 核心特性 快速上手 安装部署 文档 GitHub ↗

安装部署

一条命令，从零到一个运行中的节点

推荐使用 Docker Compose：一条命令启动控制面、内嵌 Agent 与 PostgreSQL。需要 systemd 托管二进制的场景，可继续使用脚本安装。

运行 一条命令 模式 all-in-one · server · agent 平台 Linux amd64 / arm64 耗时 约 2 分钟
bash 
curl -fsSL https://raw.githubusercontent.com/shuaiZend/PingWAF/main/deploy/compose/install.sh | bash

命令生成器

拼装你的安装命令

默认推荐 Docker Compose——一条命令，自带数据库。字段已预填文档默认值，只需修改需要自定义的部分；脚本安装保留在第二个页签。

Docker Compose

使用 Docker Compose 部署

Docker Compose 是官方推荐方式：一条命令启动控制面、内嵌 Agent 与 PostgreSQL，数据与证书保存在命名卷里；升级只需更换镜像标签。

  • Docker Engine 24+，并安装 Compose v2 插件（docker compose，而非旧的 docker-compose 命令）。
  • 宿主机 80、443、9080、9090 端口空闲——或在下方字段中改用其他端口。
  • 无需外部数据库：compose 文件自带 PostgreSQL 16 容器，并使用命名卷持久化。
  • 控制台首次启动以自签名证书提供 HTTPS。可在「设置 → Control plane HTTPS」上传正式证书，或设置 TLS_ENABLED=false 改用纯 HTTP。
一键安装命令 
curl -fsSL https://raw.githubusercontent.com/shuaiZend/PingWAF/main/deploy/compose/install.sh | bash

在空目录执行即可：安装器会下载 docker-compose.yml、写入仅本人可读的 .env、拉取镜像并启动。已有 .env 不会被覆盖——升级时重跑同一条命令即可。

  1. 1

    执行一键命令

    在空目录运行上面的命令。安装器会创建 ./pingwaf、下载 compose 文件并写入仅本人可读的 .env。

  2. 2

    等待服务就绪

    Compose 拉取镜像后启动 PostgreSQL，健康检查通过再启动 PingWAF；首次启动约需 1–2 分钟。

  3. 3

    登录控制台

    打开 https://<主机>:9080，用 ADMIN_EMAIL / ADMIN_PASSWORD 登录（默认密码会在首次登录时强制修改），然后添加站点。

需要自定义？生成带参数的命令

只填写需要改动的项；命令只会追加与默认值不同的参数。管理员密码不会写入命令，首次登录时控制台会强制修改。

启动命令 
curl -fsSL https://raw.githubusercontent.com/shuaiZend/PingWAF/main/deploy/compose/install.sh | bash

首次登录：https://<你的主机>:9080，使用上方的 ADMIN_EMAIL / ADMIN_PASSWORD（上传正式证书前请先接受自签名证书警告）。Agent 通过 :9090 连接控制面。

升级

拉取 .env 中指定标签的镜像并按原有卷重建容器——配置、数据与证书在重启后全部保留。需要可控升级时请固定镜像标签。

bash 
docker compose pull && docker compose up -d
终端显示 docker compose up -d 创建网络与卷、启动 PostgreSQL 与 PingWAF 并打印控制台地址
docker compose up -d 拉取镜像、启动 PostgreSQL，等待健康检查通过后拉起控制台。

已预填安装器默认值——只有你修改过的值才会写进命令。

生成的安装命令 
curl -fsSL https://raw.githubusercontent.com/shuaiZend/PingWAF/main/deploy/compose/install.sh | bash

只有与默认值不同的项才会以参数形式追加，因此不做任何修改时生成的就是最短的一行命令。参数通过 bash -s -- 传给管道中的脚本。

交互式安装

或者让安装器来提问

在终端不带参数运行脚本，它会依次询问模式、账号、数据库与证书名称，打印解析后的计划并等待确认。

  1. 选择部署模式

    1 all-in-one、2 server 或 3 agent——直接回车接受方括号中的默认值。

  2. 填写参数

    Agent 会询问控制面地址与注册密钥；server 模式会询问管理员账号、PostgreSQL 连接串与证书名称。密码输入时不会回显。

  3. 确认摘要

    在写入任何内容之前，安装器会先打印解析后的计划——模式、版本、平台、路径、systemd 状态与脱敏后的数据库 URL。

  4. 完成并验证

    server 模式会打印启动命令；agent 会被自动启用并启动。到控制台的「节点」页面确认节点已上线。

交互模式需要本地终端。curl | bash 场景下 stdin 是脚本本身——请先下载脚本，再用 bash install.sh 运行以进入交互引导。
交互式安装器依次询问模式、管理员账号、PostgreSQL 连接串与证书名称，最后打印安装计划
交互式安装器按顺序提问，并在写入任何内容前打印解析后的计划。
安装成功的横幅，列出二进制、配置、数据与服务路径以及后续步骤
安装成功后会注册 pingwaf.service，并打印各文件的落点。

参数速查

安装器参数一览

install.sh 支持的全部参数，每个参数都有对应的 PINGWAF_* 环境变量。

--mode

运行模式：all-in-one、server 或 agent。默认 all-in-one。

--version

安装指定版本（自动去掉前导 v）。留空或填 latest 则解析最新的 GitHub 发布。

--db-url

server/all-in-one 模式的 PostgreSQL 连接串。默认 postgres://pingwaf:pingwaf@localhost:5432/pingwaf。

--server-url

agent 模式的控制面 gRPC 地址。请使用 https://——gRPC 默认以 TLS 提供服务。

--api-key

Agent 注册令牌。也可通过 PINGWAF_API_KEY 传入，避免留在命令行上。

--admin-email

初始化的管理员邮箱（server/all-in-one）。默认 admin@pingwaf.local。

--admin-password

初始化的管理员密码（server/all-in-one）。留空保留 pingwaf123，控制台会在首次登录时强制修改。

--tls-sans

逗号分隔的主机名，生成的控制台证书会覆盖这些名称。

--no-systemd

跳过创建 systemd 服务——适用于容器、升级或自行管理进程的场景。

--interactive / --non-interactive

强制进入提问（即使已传参），或永不提问、直接使用给定值与默认值。管道方式且不带参数时保持非交互。

--dry-run

只打印解析后的计划——模式、版本、平台、路径——然后退出，不做任何安装。

GitHub 上的 CLI 手册

故障排查

安装没有顺利收尾时

支持中最常见的五类失败，以及定位各自问题所需的命令。

安装器连不上 PostgreSQL

all-in-one 与 server 模式在首次启动前需要 PostgreSQL 14+。脚本在 psql 无法连接时会给出警告——请先安装数据库，创建 pingwaf 用户与数据库（createuser / createdb），然后重新运行安装器，或编辑 /etc/pingwaf/pingwaf.toml 后执行 systemctl restart pingwaf。

bind() failed on 0.0.0.0:80 或 :443

数据面以非特权用户 pingwaf 绑定 80/443，这依赖服务单元授予的 CAP_NET_BIND_SERVICE。如果绑定仍然失败，先执行 systemctl show pingwaf -p AmbientCapabilities 检查，再用 drop-in 补上：sudo systemctl edit pingwaf → [Service] AmbientCapabilities=CAP_NET_BIND_SERVICE。在授予该能力之前写入的旧单元，会一直失败直到补上 drop-in。

二进制报版本化 glibc 符号错误

发布产物在 Ubuntu 24.04 上构建，需要 glibc 2.39 或更新。在更老的发行版（Debian 11、Ubuntu 20.04、CentOS/RHEL、Alpine 等）上，安装器的冒烟测试会报错停止——请改为源码构建。

systemd 服务启动失败

用 journalctl -u pingwaf -e 查看单元日志，并检查 /etc/pingwaf/pingwaf.toml。没有 reload 机制：任何修改都通过 systemctl restart pingwaf 应用，之后用 systemctl status pingwaf 确认。

容器启动失败，报 "bind() failed on 0.0.0.0:443" / Permission denied

镜像已在构建时为二进制授予 CAP_NET_BIND_SERVICE，因此在默认桥接模式下，非特权用户 pingwaf 用普通 docker run 或 docker compose up -d 即可绑定 80/443。如果仍然失败，说明运行时剥离了文件能力——加上 --cap-add=NET_BIND_SERVICE（仓库自带的 compose 文件已设置 cap_add 兜底），或切换到 host 网络 network_mode: host（此时必须同时注释掉 ports: 与 networks:；9080/9090 将直接监听宿主机）。可用 docker exec pingwaf getcap /usr/local/bin/pingwaf（预期输出 cap_net_bind_service=ep）和 docker exec pingwaf id -u（非零）验证。完整说明：https://github.com/shuaiZend/PingWAF/blob/main/docs/deployment.md#binding-ports-80443-in-containers

装好了？接下来添加第一个站点。

文档会带你了解站点模型、分布式拓扑、配置优先级与完整的环境变量参考。

阅读文档 GitHub Releases