Dashboard and Statistics

📊 Dashboard 与统计

运行统计默认关闭。启用后注册：

/dashboard
/dashboard/data

启用统计

[statistics]
enabled = true
data_dir = "stats"
flush_interval = 5

• data_dir：按程序工作目录解析的持久化目录；
• flush_interval：两次持久化写入之间的最短秒数；值越小，写盘越频繁。

Docker 部署挂载：

volumes:
  - "./stats:/base/stats"

如果未挂载，删除容器会丢失历史统计。

统计内容

Dashboard 可以展示：

• 本次启动时间、运行时长、历史累计运行时间和启动次数；
• 成功 /sub 转换请求和规则转换计数；
• 最近 24 小时请求/规则转换趋势；
• 不同时间窗口的国家/地区分布和排行；
• 可信边缘提供地区头时的中国地区聚合。

统计从启用后开始，不回补启用前请求。

隐私边界

统计模块不保存：

• 订阅 URL；
• 节点或配置正文；
• 访问者 IP。

地理统计来自配置的请求头，并保存聚合结果。无法识别时归为未知。

地理请求头

[statistics.geo]
provider = "header"
country_headers = ["CF-IPCountry", "X-Geo-Country", "X-Vercel-IP-Country", "CloudFront-Viewer-Country"]

可选 provider：

• header：依次读取配置的国家码请求头；
• none：所有来源记为未知。

只有在边缘代理会覆盖和清洗这些头时才可信。客户端可以自行伪造未被代理覆盖的请求头。

YAML/TOML 还支持 china_region_headers；INI 使用 [statistics] 中的同名逗号列表。未配置时使用程序内置候选头。

Basic Auth

[statistics.dashboard_auth]
enabled = true
username = "admin"
password = "replace-with-a-strong-password"
max_failures = 5
window_seconds = 300
lock_seconds = 900

启用认证时用户名和密码不能为空。Basic Auth 必须配合 HTTPS；HTTP 会让凭据暴露在传输路径中。

三个限速数值小于 1 时按 1 处理。

可信代理客户端地址

默认：

[statistics.dashboard_auth.client_ip]
header = "none"
trusted_proxy_cidrs = []

此时防爆破按 TCP socket peer 分桶，忽略客户端提供的转发头。

只有应用端口无法绕过反向代理，并且代理会覆盖所选头时，才设置：

[statistics.dashboard_auth.client_ip]
header = "x-forwarded-for"
trusted_proxy_cidrs = ["172.18.0.0/16"]

允许的头名：

none
x-forwarded-for
forwarded
x-real-ip
cf-connecting-ip
true-client-ip

可信代理最多 64 个 CIDR，拒绝 IPv4/IPv6 /0。header 和 trusted_proxy_cidrs 必须配套配置。

访问

https://sub.example.com/dashboard
https://sub.example.com/dashboard/data

如果返回 404，先确认 statistics.enabled=true 并已重启服务。401 表示认证缺失或失败；429 表示当前客户端的认证失败次数达到锁定阈值，应等待响应中的 Retry-After，并检查客户端地址识别和反向代理配置；503 表示已启用认证，但用户名或密码为空。

备份和恢复

备份前应确保统计数据已完成刷新，或在可控窗口停止服务后复制 data_dir。恢复时：

1. 停止服务；
2. 恢复到相同或已确认兼容的统计目录；
3. 检查文件权限；
4. 启动服务；
5. 检查 Dashboard 历史和启动次数。