🚀 使用 Docker Compose 部署 UUWAF（NanQiang Web 应用防火墙）

🚀 使用 Docker Compose 部署 uuWAF（南墙）

uuWAF（又称"南墙"）是一款国产的、由社区驱动的免费Web应用防火墙（WAF）。它旨在为网站和Web应用提供全方位的安全防护，帮助抵御常见的网络攻击。

📦 项目简介

uuWAF 具备以下核心特点：

特点类别	具体说明
核心技术	先进语义引擎：采用基于语义分析的检测引擎（支持SQL、XSS、RCE、LFI），结合深度解码技术，有效抵御绕过WAF的攻击，具有高准确率、低误报的特点。智能0day防御：运用机器学习技术，自动学习正常流量特征，建立白名单规则库，可在面对突发0day漏洞时无需添加规则即可拦截攻击。高级规则引擎：支持Lua脚本编写高级防护规则，扩展性强。
部署与管理	容器化部署：支持Docker部署，本次部署即采用此方式。友好管理界面：提供Web管理后台，配置无需重启即可生效。
安全防护	多种攻击防护：防护SQL注入、XSS跨站脚本、WebShell上传、命令注入、非法HTTP协议请求、常见Web服务器漏洞攻击、核心文件非授权访问、路径穿越等。 CC攻击防护：支持对单一源IP的访问频率控制，支持重定向跳转验证、人机识别等。访问控制：支持IP、URL、Referer、User-Agent等HTTP字段的条件组合，实现精准访问控制策略。

📋 部署前准备

1.环境要求 * 确保服务器已安装 Docker 和 Docker Compose。 * uuWAF 对配置要求不高，建议内存不小于 2GB，磁盘空间不小于 16GB 。确保安装目录有足够空间。

2.端口与网络 * 端口：确保宿主机上的 80、443、4443 端口未被占用。如果已被占用，需在 .env 文件中修改映射端口。 * 网络：配置文件使用外部网络 1panel-network。部署前需先创建此网络：

        docker network create 1panel-network

⚙️ 配置 Docker Compose

1.创建项目目录创建一个目录（例如 uuwaf-docker）存放所有相关文件，并进入该目录。

    mkdir uuwaf-docker && cd uuwaf-docker

编写 docker-compose.yml 文件

networks:
    # 引用外部 1panel-network（需提前创建）
    1panel-network:
        external: true
services:
    # 1. UUWAF 核心服务
    uuwaf:
        command:
            - /run.sh  # 启动脚本（固定，无需修改）
        container_name: ${CONTAINER_NAME}  # 从 .env 读取容器名
        depends_on:
            - wafdb  # 依赖数据库服务启动后再启动 WAF
        environment:
            - TZ=Asia/Shanghai  # 时区同步（固定，确保日志时间正确）
        image: uusec/nanqiang:v5.5.0  # 官方指定版本镜像（不建议随意升级）
        links:
            - wafdb  # 链接到数据库容器，便于内部访问
        networks:
            - 1panel-network  # 加入 1panel 外部网络
        ports:
            # 端口映射：从 .env 读取端口，格式为 "主机端口:容器端口"
            - ${PANEL_APP_PORT_HTTP1}:80
            - ${PANEL_APP_PORT_HTTPS2}:443
            - ${PANEL_APP_PORT_HTTPS}:4443
        ulimits:
            # 优化文件句柄数（支持高并发，固定配置）
            nofile:
                hard: 102400
                soft: 102400
            # 优化进程数（固定配置）
            nproc: 65535
        volumes:
            # 共享配置卷：存储 WAF 规则、初始化脚本（自动创建）
            - wafshared:/uuwaf

    # 2. Percona 数据库服务（存储 WAF 数据）
    wafdb:
        container_name: ${CONTAINER_NAME}-db  # 数据库容器名（基于主容器名，自动加 -db）
        deploy:
            resources:
                # 资源限制（从 .env 读取 CPU 和内存限制）
                limits:
                    cpus: ${CPUS}
                    memory: ${MEMORY_LIMIT}
        environment:
            - TZ=Asia/Shanghai  # 时区同步
            - INIT_ROCKSDB  # 初始化 RocksDB（WAF 依赖的数据库引擎，固定）
            - MYSQL_ROOT_PASSWORD=Safe3.WAF  # 数据库 root 密码（固定！不要修改，WAF 内置该密码）
        image: percona:8  # Percona 8 镜像（固定版本，确保兼容性）
        networks:
            - 1panel-network  # 加入外部网络，与 WAF 通信
        volumes:
            # 共享配置卷：挂载初始化脚本到数据库（与 WAF 共享）
            - wafshared:/docker-entrypoint-initdb.d
            # 数据库数据卷：存储 Percona 数据（自动创建，持久化关键）
            - wafdata:/var/lib/mysql

# 定义数据卷（自动创建，无需手动管理）
volumes:
    wafdata: null  # 数据库数据卷（核心，不可删除）
    wafshared: null  # 共享配置卷（不可删除）

2. 关键配置说明（新手）

2.创建 docker-compose.yml 文件将提供的配置内容保存至 docker-compose.yml 文件中。该配置定义了两个服务：uuwaf（主应用）和 wafdb（数据库）。

    version: '3'  # 建议明确指定版本号，例如 '3.8'

    services:
      uuwaf:
        command: [ "/run.sh" ]
        container_name: "${CONTAINER_NAME}"  # 容器名称通过环境变量指定
        depends_on:
          - wafdb  # 表明uuwaf服务依赖于wafdb服务
        environment:
          - TZ=Asia/Shanghai  # 设置容器时区
        image: uusec/nanqiang:v5.5.0  # 使用特定的南墙镜像版本
        networks:
          - 1panel-network  # 连接到自定义网络
        ports:
          - "${PANEL_APP_PORT_HTTP1}:80"    # HTTP服务端口
          - "${PANEL_APP_PORT_HTTPS2}:443"  # HTTPS服务端口
          - "${PANEL_APP_PORT_HTTPS}:4443"  # 管理后台端口
        ulimits:  # 设置资源限制
          nofile:  # 文件描述符数量限制
            hard: 102400
            soft: 102400
          nproc: 65535  # 进程数限制
        volumes:
          - wafshared:/uuwaf  # 挂载共享卷

      wafdb:
        container_name: "${CONTAINER_NAME}-db"
        environment:
          - TZ=Asia/Shanghai
          - INIT_ROCKSDB           # 初始化RocksDB
          - MYSQL_ROOT_PASSWORD=Safe3.WAF  # 设置数据库root密码
        image: percona:8  # 使用Percona数据库镜像
        networks:
          - 1panel-network
        volumes:
          - wafshared:/docker-entrypoint-initdb.d  # 挂载共享卷到数据库初始化目录
          - wafdata:/var/lib/mysql  # 挂载数据卷持久化数据库数据

    volumes:
      wafdata:    # 持久化数据库数据
      wafshared:  # 用于服务间共享数据

    networks:
      1panel-network:
        external: true  # 使用已存在的外部网络

**关键配置说明**：
*   **镜像**：`uuwaf` 服务使用官方镜像 `uusec/nanqiang:v5.5.0`。`wafdb` 服务使用 `percona:8` 镜像作为数据库。
*   **数据持久化**：使用名为 `wafdata` 的卷持久化数据库数据，防止容器重启后数据丢失。`wafshared` 卷用于 `uuwaf` 和 `wafdb` 服务间的数据共享。
*   **网络**：使用外部网络 `1panel-network`，便于与其他容器服务（如1Panel）通信。
*   **环境变量**：大量配置参数通过环境变量文件（`.env`）管理，提高了配置的灵活性和可维护性。

3.创建 .env 配置文件将提供的环境变量内容保存到 .env 文件中。此文件为 docker-compose.yml 中的变量提供值。

# 容器名称（自定义，建议保留默认，便于识别）
CONTAINER_NAME="1Panel-uuwaf-H38W"
# CPU 资源限制（0 表示不限制，推荐设为 1 或 2，如 CPUS=2）
CPUS=0
# 内存限制（0 表示不限制，推荐设为 2G 或 4G，如 MEMORY_LIMIT=2G）
MEMORY_LIMIT=0
# HTTP 端口映射：主机端口 → 容器 80（默认 80，冲突可改 8080）
PANEL_APP_PORT_HTTP1=80
# HTTPS 端口映射1：主机端口 → 容器 443（默认 443，冲突可改 4433）
PANEL_APP_PORT_HTTPS2=443
# HTTPS 端口映射2：主机端口 → 容器 4443（默认 4443，冲突可改 4444）
PANEL_APP_PORT_HTTPS=4443

**关键配置说明**：
*   **端口**：`PANEL_APP_PORT_HTTP1`、`PANEL_APP_PORT_HTTPS2` 和 `PANEL_APP_PORT_HTTPS` 分别对应HTTP服务、HTTPS服务和管理后台的宿主机端口。若宿主机这些端口已被占用，可修改为其他可用端口，例如 `8080:80`、`8443:443`、`14443:4443`。
*   **资源限制**：`CPUS` 和 `MEMORY_LIMIT` 设为 `0` 表示不施加限制。在生产环境中，建议根据实际情况设置合理的上限。

🚀 启动与验证

1.启动服务在 docker-compose.yml 和 .env 文件所在目录，执行以下命令后台启动服务：

    docker-compose up -d

2.检查服务状态使用以下命令查看容器状态：

    docker-compose ps

若所有服务的 State 栏均为 Up，则表示启动成功。

3.查看日志若容器启动异常，可通过日志排查：

    docker-compose logs uuwaf  # 查看uuwaf服务日志
    docker-compose logs wafdb  # 查看数据库服务日志

4.访问管理后台在浏览器中输入 https://你的服务器IP:4443。使用默认用户名 admin 和密码 wafadmin 登录。注意：首次登录后请立即修改默认密码。

（2）访问 UUWAF 管理界面

打开浏览器，输入 http://服务器IP（若修改 HTTP 端口，需加端口，如 http://192.168.1.100:8080）；
首次访问会进入 UUWAF 登录界面（默认账号密码需参考官方文档，通常为 admin/Safe3@UUWAF，若不一致需查容器日志获取初始密码）；
登录成功后进入管理后台（显示 “站点管理”“规则配置”“日志审计” 等菜单），说明服务正常。

🔧 基础配置与使用

初始登录与安全设置
- 使用默认账号（admin/wafadmin）登录管理后台（https://你的服务器IP:4443）。
- 强烈建议立即修改管理员密码，并启用动态口令（2FA）以增强安全性。
添加防护站点
- 在管理后台，进入 站点管理 菜单，点击 添加站点。
- 输入要防护的域名，并填写该域名对应的源站服务器IP地址和端口。
配置SSL/TLS证书
- 进入 证书管理 菜单，点击 添加证书。
- 为已添加的站点上传对应的SSL证书和私钥文件。若未配置证书，uuWAF 可能会尝试自动申请 Let's Encrypt 免费证书（取决于配置）。
修改DNS解析
- 到您的域名服务商处，将站点的DNS A记录解析指向部署了 uuWAF 的服务器IP地址。这样，访问您网站的流量才会先经过 uuWAF 进行检测和过滤。
测试防护效果
- 访问您的站点域名，确认网站能正常打开。
- 可通过浏览器开发者工具或 curl -I 命令检查HTTP响应头，确认 Server 字段包含 uuWAF 标识，表示流量已成功经过WAF。

🔧 基础配置与使用2

UUWAF 核心使用流程是 “添加防护站点→配置防护规则→查看防护日志”，新手可按以下步骤操作：

1. 步骤 1：添加防护站点（核心功能）

登录管理后台，点击左侧「站点管理」→「添加站点」；
填写站点信息：
- 站点域名：输入需防护的 Web 服务域名（如 www.example.com）；
- 后端地址：填写真实 Web 服务的 IP: 端口（如 192.168.1.200:8080，WAF 会转发流量到该地址）；
- 协议类型：选择 HTTP 或 HTTPS（若选 HTTPS，需后续上传 SSL 证书）；
点击「保存」，站点会显示在列表中，状态为「已启用」。

2. 步骤 2：配置防护规则

UUWAF 内置基础防护规则，可按需启用 / 自定义：

点击左侧「规则管理」→「基础防护规则」；
启用常用规则（推荐全部启用）：
- SQL 注入防护：拦截 union select、and 1=1 等恶意语句；
- XSS 防护：过滤 <script> 等跨站脚本标签；
- CSRF 防护：验证请求来源，防止跨站请求；
- 爬虫防护：拦截常见爬虫（如百度爬虫可加入白名单）；
点击「保存生效」，规则立即应用到所有防护站点。

3. 步骤 3：配置 HTTPS（可选）

若防护站点需 HTTPS，需上传 SSL 证书：

点击左侧「SSL 证书管理」→「添加证书」；
选择对应站点，上传证书文件（cert.pem 公钥、key.pem 私钥）；
保存后，访问 https://站点域名（如 https://www.example.com），确认证书生效（无安全警告）。

4. 步骤 4：查看防护日志

通过日志审计攻击情况：

点击左侧「日志管理」→「防护日志」；
可按时间、攻击类型（如 SQL 注入、XSS）筛选日志，查看攻击 IP、请求内容、拦截结果；
对频繁攻击的 IP，可加入「IP 黑名单」（左侧「黑白名单管理」），禁止其访问。

🔄 维护与管理

1.更新服务当有新版本发布时，可按以下步骤更新：

    # 进入项目目录
    cd /path/to/your/uuwaf-docker
    # 拉取最新镜像 (注意：请关注官方镜像版本更新信息)
    docker-compose pull
    # 重新创建并启动容器
    docker-compose up -d
    # 清理无用镜像
    docker image prune

**注意**：更新前建议备份数据。关注官方发布说明，了解版本变更和兼容性。

2.数据备份 * 定期备份 Docker 卷 wafdata 和 wafshared 中的数据。可使用 docker volume inspect <volume_name> 查找卷在宿主机上的实际路径并进行备份。 * 备份 uuWAF 管理后台中导出的配置规则。

3.服务卸载如需卸载 uuWAF，在项目目录下执行：

    docker-compose down

若需彻底删除所有数据（包括数据库和配置），可加上 -v 参数：

    docker-compose down -v

注意：此操作不可逆，请确保已备份重要数据。

🐛 常见问题排查

问题现象	可能原因与解决方案
容器启动失败	1. 检查 `docker-compose.yml` 和 `.env` 文件语法、格式是否正确。 2. 执行 `docker-compose logs [服务名]` 查看具体错误日志。
无法访问管理后台 (`https://IP:4443`)	1. 确认防火墙/安全组已开放 `4443` 端口。 2. 检查 `docker-compose ps` 确认容器状态为 `Up`。 3. 验证 `.env` 文件中 `PANEL_APP_PORT_HTTPS` 映射的宿主机端口是否正确。
网站显示"Bad Gateway"或其他错误	1. 检查 uuWAF 站点管理中配置的源站IP和端口是否正确，确保uuWAF能连接到源站。 2. 确认数据库容器 `wafdb` 运行正常。
防护规则不生效	1. 检查DNS解析是否已成功指向uuWAF服务器IP。 2. 在管理后台确认相应站点的防护规则是否已启用。 3. 清理浏览器缓存或使用无痕模式测试。
忘记管理后台密码	1. 可尝试通过容器内命令重置（具体方法请参考官方文档）。 2. 若无法重置，可能需要重置整个环境（需备份数据）。

希望这篇教程能帮助你顺利部署和使用 uuWAF，为你的 Web 应用提供坚实的安全防护！如果在使用过程中遇到更复杂的问题，uuWAF 的官方文档和用户社区是寻求帮助的好去处。

🐛 常见问题排查2

1. 防护站点无法访问（提示 “502 Bad Gateway”）

原因 1：后端 Web 服务未启动或地址错误。解决：
1. 验证后端地址：curl http://后端IP:端口，确认能正常访问；
2. 进入 UUWAF 管理后台，修改站点的「后端地址」为正确 IP: 端口。
3. 原因 2：WAF 与后端服务网络不通（如跨网段）。解决：确保 UUWAF 所在服务器能 ping 通后端服务，关闭后端服务器防火墙（或开放 WAF 服务器 IP 访问）。

2. HTTPS 证书生效后仍提示 “不安全”

原因 1：证书未包含完整链（如缺少中间证书）。解决：重新获取完整证书（从域名服务商下载，包含 fullchain.pem），重新上传。
原因 2：浏览器缓存旧证书。解决：清除浏览器缓存（Ctrl+Shift+Delete），或使用隐私模式访问。

3. 数据库连接失败（日志显示 “Can't connect to MySQL server”）

原因 1：数据库容器未启动。解决：重启数据库容器：docker start 1Panel-uuwaf-H38W-db。
原因 2：MYSQL_ROOT_PASSWORD 被修改。解决：编辑 docker-compose.yml，恢复密码为 Safe3.WAF，重启服务：docker compose up -d。

4. 高并发时 WAF 卡顿（规则匹配慢）

原因 1：内存不足，数据库查询缓慢。解决：修改 .env 文件，设置 MEMORY_LIMIT=4G，重启服务：docker compose up -d。
原因 2：防护规则过多，匹配效率低。解决：进入管理后台，禁用不必要的规则（如不使用的爬虫防护规则），保留核心规则（SQL 注入、XSS）。

5. 1Panel 面板无法管理 UUWAF

原因：UUWAF 未加入 1panel-network 网络。

解决： 1. 停止服务：docker compose down； 2. 确认网络配置：docker-compose.yml 中 networks 已配置 - 1panel-network； 3. 重启服务：docker compose up -d，在 1Panel 面板「容器管理」中刷新，即可看到 UUWAF 容器。

通过以上步骤，新手可成功部署 UUWAF 并实现 Web 应用防护。UUWAF 适合中小规模 Web 服务（如个人博客、企业官网），后续可根据流量规模调整资源配置或扩展防护规则，具体参考 UUWAF 官方文档（若有）。