前端真实 IP 请求头

前端真实 IP 请求头用于让 Dashboard 识别访问管理前端和用户前端的真实客户端 IP。在线用户、登录防爆破、OAuth2 爆破防护、API Token 爆破防护、Agent 连接密钥爆破防护、审计记录和 Web 应用防火墙（WAF）都依赖这个 IP。

此功能可在管理前端 头像 → 系统设置 → 系统配置 → 前端真实 IP 请求头 中配置；对应配置文件字段为 web_real_ip_header。

前端请求头和 Agent 请求头不同

前端真实 IP 请求头只处理浏览器或用户访问 Dashboard 时的 IP。Agent 真实 IP 请求头只处理 Agent 连接 Dashboard 时的 IP。两者的访问入口、代理链路和用途可能不同，请不要混用。

---

推荐怎么填

部署方式	推荐值	说明
Dashboard 直接公网访问	使用直连 IP	等价于 web_real_ip_header: "NZ::Use-Peer-IP"
普通反向代理	X-Real-IP 或反向代理示例中的 nz-realip	上游 Nginx、Caddy、Apache 等必须传递同名 Header
Cloudflare CDN	CF-Connecting-IP	其它 CDN 请填写对应厂商提供的真实 IP Header
不确定代理是否正确传头	先留空或使用直连 IP	确认代理日志和 Header 后再启用自定义 Header

只信任来自可信反向代理或 CDN 的真实 IP Header。如果 Dashboard 可以被用户绕过代理直接访问，用户可能伪造这个 Header，导致 WAF 误判或被绕过。

---

场景一：Dashboard 直接公网访问

如果浏览器直接访问 Dashboard，没有经过 Nginx、Caddy、Apache、Cloudflare 或其它 CDN，选择 使用直连 IP 即可。

配置文件中的等价值为：

web_real_ip_header: "NZ::Use-Peer-IP"

此模式下 Dashboard 直接使用连接 IP，不需要上游应用传递请求头。

---

场景二：使用 Nginx、Caddy、Apache 等反向代理

反向代理部署时，Dashboard 看到的连接 IP 通常是反向代理服务器的 IP。你需要让反向代理把客户端 IP 写入一个 Header，然后在 Dashboard 的 前端真实 IP 请求头 中填写同名 Header。

常见选择：

• 使用标准习惯的 X-Real-IP。
• 如果沿用本站 反向代理配置 示例，可以填写 nz-realip。
• 如果使用 X-Forwarded-For，请确保代理链路可信，并确认 Dashboard 读取到的是期望的客户端 IP。

Nginx 最小示例

location / {
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_pass http://127.0.0.1:8008;
}

Dashboard 中填写：

web_real_ip_header: "X-Real-IP"

如果你使用文档中的 nz-realip 示例：

location / {
    proxy_set_header Host $host;
    proxy_set_header nz-realip $remote_addr;
    proxy_pass http://127.0.0.1:8008;
}

Dashboard 中填写：

web_real_ip_header: "nz-realip"

Caddy 最小示例

example.com {
    reverse_proxy 127.0.0.1:8008 {
        header_up X-Real-IP {remote_host}
    }
}

Dashboard 中填写：

web_real_ip_header: "X-Real-IP"

---

场景三：使用 Cloudflare 或其它 CDN

使用 Cloudflare 代理 Dashboard 时，Dashboard 中填写：

web_real_ip_header: "CF-Connecting-IP"

其它 CDN 请填写该 CDN 提供的真实客户端 IP Header，例如厂商文档中说明的 Real IP、Client IP 或 Connecting IP Header。

请确保只有可信 CDN 或反向代理能访问 Dashboard 源站。如果源站仍可被公网直接访问，攻击者可以绕过 CDN 并伪造 Header。

---

WAF 如何使用这个 IP

Dashboard 内置 WAF 会按 IP + 封禁标识 记录风险行为。当出现以下情况时，WAF 会记录并封禁对应来源：

• 登录失败次数过多。
• OAuth2 登录爆破。
• API Token 爆破。
• Agent 连接密钥爆破。
• 管理员在“在线用户”页面手动封禁。

同一条记录的次数越多，封禁时间越长。管理员可以在 系统设置 → Web 应用防火墙 中查看封禁 IP、封禁标识、计数、封禁原因和封禁时间，也可以删除单条或批量删除封禁记录。

---

配置错误会怎样

如果填写了不存在、不可信或代理没有传递的 Header，可能出现以下问题：

• Dashboard 无法取得 IP，在线用户和审计记录不准确。
• 所有访问者都被识别为反向代理或 CDN 的 IP，导致多人共用一个封禁记录。
• 用户可以伪造 Header，绕过 WAF 或让其他 IP 被误封。
• 管理员自己的 IP 被误封，导致无法登录后台。

不确定时，先留空或选择 使用直连 IP，确认反向代理确实传递了正确 Header 后再启用自定义 Header。

---

如何验证

保存配置并重启 Dashboard 后，可以这样验证：

1. 使用浏览器访问 Dashboard。
2. 进入 系统设置 → 在线用户，查看自己的 IP 是否为真实客户端公网 IP，而不是反向代理、CDN 或内网地址。
3. 检查反向代理访问日志，确认日志中的客户端 IP 与 Dashboard 在线用户页一致。
4. 如有条件，可在反向代理临时记录传给 Dashboard 的 Header，确认 Header 名和值与 web_real_ip_header 完全一致。

请不要通过故意连续输错密码来测试 WAF，避免把自己或其他用户误封。

---

如何恢复

如果配置错误导致 IP 识别异常或无法登录：

1. 修改 Dashboard 配置文件，一般路径为 /data/config.yaml。

2. 将 web_real_ip_header 设置为空值或直连模式：

   web_real_ip_header: ""

   或：

   web_real_ip_header: "NZ::Use-Peer-IP"

3. 重启 Dashboard。

4. 重新登录后台，在 系统设置 → Web 应用防火墙 删除误封的 IP 或相关封禁记录。

如果你已经能进入后台，也可以直接在系统设置中修改 前端真实 IP 请求头 并保存，然后到 WAF 页面删除对应封禁记录。