常见问题排查

1. 脚本下载失败：curl: (92) HTTP/2 stream error

原因：服务器对 HTTPS / HTTP2 兼容性较差。

解决：本节命令已加入 --http1.1 参数，重新复制命令执行即可：

curl -k --http1.1 -o /root/ginwaf-install https://www.ginwaf.cn/download/ubuntu/ginwaf-install

2. 报错 unzip: command not found

原因：系统缺少解压工具。

解决：

apt update && apt install unzip -y

3. 安装后无法访问管理后台（运行失败）

可能原因：

• 管理后台地址填写错误
• 8080 端口未通
• 安全组 / 防火墙未放行

排查步骤：

ping 服务器IP
telnet 服务器IP 8080

如 telnet 不通，请检查云服务器安全组是否放行 8080 端口，以及本机防火墙（ufw / iptables）是否拦截。

4. 授权校验失败导致服务无法启动

原因：服务器无法访问授权服务器，或服务器 IP 未授权。

解决：

1. 确认服务器可访问公网
2. 确认已在官网 www.ginwaf.cn 完成授权
3. 检查服务器出网是否被拦截

5. 服务未在后台运行 / 开机未自启

排查：

sudo ./ginwaf-install status

可查看 MySQL、Redis、OpenResty、GinWAF 各服务的运行状态。

如需手动重启：

systemctl restart ginwaf

6. 端口被占用

GinWAF 需要 80、443、8080 等端口。若服务器上已安装 Nginx / Apache / MySQL / Redis，会产生冲突。

建议：使用干净的服务器安装，或先停止并卸载冲突服务。

检查端口占用：

ss -lntp | grep -E ':80|:443|:8080|:3306|:6379'

7. 站点接入后无法访问

请依次检查：

1. 域名解析是否已指向 GinWAF 服务器 IP
2. 源站服务是否正常（直接在源站服务器上访问是否可通）
3. 站点是否处于「启用」状态
4. 回源协议与回源端口是否与源站一致
5. 查看站点访问日志，确认请求是否到达

8. 正常业务被误拦截

解决：

1. 将对应检测项从「标准 / 严格」降为「观察」模式：仍会拦截恶意注入请求，但不再拉黑来源 IP，便于判断是规则误报还是真实攻击
2. 将可信 IP 加入站点白名单
3. 在 CC 规则组中调整匹配条件，缩小拦截范围

9. 忘记管理员密码

若已配置邮箱，可通过登录页的「找回密码」使用邮箱验证码重置。

若未配置邮箱，可参考官方安装文档或联系官方支持。

10. 需要单独重装某个组件

安装器支持单独执行：

sudo ./ginwaf-install mysql      # 仅安装 MySQL
sudo ./ginwaf-install redis      # 仅安装 Redis
sudo ./ginwaf-install openresty  # 仅安装 OpenResty
sudo ./ginwaf-install ssl        # 仅生成 SSL 证书
sudo ./ginwaf-install sql        # 仅导入 SQL 数据

11. 人机验证频繁弹出

现象：正常用户访问站点时反复出现验证页。

排查与处理：

1. 检查站点「CC 防护配置」中是否开启了「默认防护」。默认防护会对首次访问强制验证，可按需关闭或改为「自动切换」。
2. 适当调高「自动切换」的触发 QPS 阈值，避免正常流量峰值触发切换。
3. 将信任 IP 或网段加入「更多设置」中的白名单，并适当延长「白名单时长」。
4. 检查是否命中自定义规则，可在「自定义规则」列表中逐条停用后验证。

详见 CC 防护。

12. 自定义 CC 规则不生效

排查与处理：

1. 确认规则的「状态」为「开启」。
2. 确认新增规则后已点击页面左下角的「保存修改」；仅点击「确定」不会下发配置。
3. 检查匹配项、操作符、匹配值填写是否规范，例如正则匹配需填写合法正则表达式。
4. 检查是否超出规则数量上限（自定义规则至多 5 条）。
5. 确认三层防护中其他层未提前命中并「停止匹配」。

详见 CC 防护。

13. 站点 IP 被误拉黑

处理方式：

1. 进入「黑名单管理」，按被拉黑的 IP 检索记录。
2. 点击该记录右侧的「解禁」，或勾选多条后「批量解禁」。
3. 解封立即生效，无需重启服务。

详见 日志管理。

14. 如何开启强制 HTTPS

进入站点的「HTTPS 配置」标签页，将「强制 HTTPS」设为「开启」并保存，此后所有 HTTP 请求会以 301 状态码跳转至 HTTPS。

前置条件

开启前请确认站点已正确配置证书，否则跳转后仍会因无证书而无法访问。详见 SSL 证书。

15. 配置修改后 WAF 未生效

排查与处理：

1. 确认页面是否点击了「保存修改」，配置未保存时不会写入任何文件。
2. 确认管理端已成功写入对应站点的 JSON 配置文件（CC 防护为 waf/sites/cc/site_{站点ID}.json，攻击防护为 waf/sites/attack/site_{站点ID}.json）。
3. 查看站点访问日志与拦截日志，确认请求是否经过 WAF 引擎处理。
4. 若为站点级 Nginx 配置变更，确认平滑重载是否成功；重载失败时系统会自动回滚到变更前配置。

16. Redis 连接失败

排查与处理：

1. 检查 Redis 服务是否正常运行：systemctl status redis。
2. 确认 Redis 配置文件中的监听地址、端口与密码与管理端配置一致。
3. 确认 Redis 所在磁盘未写满，避免持久化失败导致只读。

降级行为

Redis 不可用时 WAF 会降级到本地共享内存运行，基本防护仍然生效，但跨节点黑名单共享与统计数据会受影响，建议尽快恢复。

仍需帮助

• 官方网站：www.ginwaf.cn
• 邮箱：ginwaf@qq.com
• QQ：48548598