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

快速上手

五分钟跑起来，十分钟完成防护

两条官方路径：用自带 compose 快速评估，或自行构建二进制用于生产环境。

方式 A Docker Compose 方式 B 源码构建 耗时 约 5 分钟 存储 PostgreSQL 14+

开始之前

compose 方式只需要 Docker；源码构建还需要 Rust、Node 工具链与 protoc。

Docker

Engine 24+ 与 Compose v2

一次启动控制面、一个 Agent 与 PostgreSQL。

PostgreSQL

14+（推荐 16）

控制面用它保存站点、规则与版本。

端口

9080 · 9090 · 80 · 443

9080 提供 API 与控制台，9090 是 gRPC 控制面。

TLS

首次启动使用自签证书

对外暴露控制台前请替换证书或先行信任。

快速上手

Docker Compose

compose 文件会以 all-in-one 模式启动 PingWAF，并同时拉起 PostgreSQL。

  1. 克隆仓库

    compose 文件与示例 TOML 配置都在仓库根目录。

    bash 
    git clone https://github.com/shuaiZend/PingWAF.git
cd PingWAF

  2. 启动服务

    如果这台主机可被他人访问，请先设置 JWT_SECRET 与 ADMIN_PASSWORD。

    bash 
    export JWT_SECRET="$(openssl rand -hex 32)"
export ADMIN_PASSWORD="$(openssl rand -hex 16)"
docker compose up -d

  3. 打开控制台

    控制台使用首次启动生成的自签证书提供 HTTPS，浏览器会告警，直到你在设置中信任或上传自己的证书。

    bash 
    curl --connect-timeout 2 --max-time 3 http://localhost:9080/healthz
# {"status":"ok","database":"up"}

  4. 添加第一个站点

    用准备解析到 Agent 的域名创建站点，然后只为这个域名开启需要的防护。

预编译二进制目前只发布 Linux amd64/arm64；Docker 镜像同时支持两种架构。
localhost:9080/sites
PingWAF 控制台站点列表，展示流量与防护状态
站点列表是执行的起点：每个域名一行。

快速上手

源码构建

需要自定义构建、不同特性组合或可审计二进制时使用这条路径。

  1. 安装工具链

    protoc 是必需项：缺失时 proto crate 会退化为占位文件，后续 crate 编译失败。

    bash 
    # macOS
brew install protobuf

# Debian / Ubuntu
sudo apt install protobuf-compiler cmake

  2. 构建控制台

    控制台会被嵌入二进制，因此必须先构建。

    bash 
    cd web && npm ci && npm run build && cd ..

  3. 构建二进制

    full 特性包含 WAF 引擎、挑战与证书自动化。

    bash 
    cargo build --release --bin pingwaf --features full

  4. 以 all-in-one 运行

    指向一个 PostgreSQL 实例即可，首次启动会自动建表。

    bash 
    ./target/release/pingwaf all-in-one \
  --db-url "postgres://pingwaf:pingwaf@localhost:5432/pingwaf"
在 Linux 上可以跳过构建：curl -fsSL https://raw.githubusercontent.com/shuaiZend/PingWAF/main/install.sh | sudo bash -s -- --mode all-in-one
localhost:9080/agents
Agent 集群页面，列出已接入的边缘 Agent 与心跳状态
源码构建可以先作为控制面运行，再从集群页面纳管 Agent。

首次登录

控制面首次启动会创建管理员账号，控制台会在可用前强制要求修改密码。

defaults.env

控制台 https://localhost:9080
邮箱 admin@pingwaf.local
密码 pingwaf123
JWT 密钥 ≥ 16 个字符

对外暴露前务必修改默认值

PINGWAF_JWT_SECRET 与 PINGWAF_ADMIN_PASSWORD 都有可用默认值。请同时设置它们、把 PINGWAF_ALLOW_REGISTRATION 设为 false，并让 9080 只在内网或 VPN 内可达。
bash 
export PINGWAF_JWT_SECRET="$(openssl rand -hex 32)"
export PINGWAF_ADMIN_PASSWORD="$(openssl rand -hex 16)"
export PINGWAF_ALLOW_REGISTRATION=false
localhost:9080/login
PingWAF 登录页，包含邮箱与密码输入框
使用初始管理员账号登录；之后可在设置中绑定 Passkey。

后续步骤

控制面能响应之后，剩下的都是配置工作。

创建站点

站点把域名与源站池、路由以及你启用的防护绑定在一起。

站点模型

接入边缘 Agent

控制节点运行 pingwaf server，边缘节点运行 pingwaf agent，Agent 通过 gRPC :9090 注册。

分布式部署

开启防护

按站点启用 WAF 引擎、CC 盾或 Bot 策略——在你开启之前不会有任何拦截。

能力总览

把日志接出去

请求日志写入 Elasticsearch，原始报文留在 PostgreSQL 以便重放。

可观测性

启动不顺利时

构建在 pingwaf-proto 阶段失败

缺少 protoc。安装 protobuf-compiler（或 brew install protobuf）后重新构建——没有它时该 crate 会静默退化为占位文件。

浏览器不信任控制台证书

控制台默认使用自签证书提供 HTTPS。信任下载的证书，或在设置 → 控制面 HTTPS 上传自己的证书；用 PINGWAF_TLS_SANS 指定实际访问的主机名。

Agent 一直不出现在集群里

确认 Agent 能访问 :9090 的 gRPC 控制面（PINGWAF_SERVER_URL），且没有被防火墙或 TLS 终止代理拦截。

443 端口没有监听

只有当站点签发或上传证书后 443 才会开放；在此之前 Agent 只提供 80 端口的 HTTP。

需要更完整的说明？

部署与架构文档覆盖 systemd、分布式拓扑、配置优先级以及完整的环境变量清单。

部署指南 GitHub