Edgeweir
使用指南

访问日志与 AccessKey

流量统计、访问日志的采样、查询与导出、统计存储模式，以及 AccessKey 的创建与吊销。

概念

术语定义
统计节点按分钟汇总的全量计数：请求数、流量、缓存命中、状态码，以及估算的热门 URL 和 IP。
访问日志按采样率记录的单个请求。有上限的诊断数据，不是零丢失的审计记录。
采样率被记录的请求比例；界面为百分比，API 为万分比整数（0–10000）。
统计模式EDGEWEIR_ANALYTICS 的取值：lite（PostgreSQL，默认）或 clickhouse。
AccessKey以控制台账户的身份调用 /api/v1 的密钥（ewk_ 前缀），在 个人设置 中创建与吊销。

查看统计

位置范围
概览全部网站与节点，含「流量最高的网站」「流量最高的节点」
网站 →「统计」页签单个网站
  1. 打开上表中的页面，选择时间范围：「过去 1 小时」「过去 6 小时」「过去 24 小时」「过去 7 天」「过去 30 天」。
  2. 查看「请求总数」「数据传输」「缓存命中率」「带宽峰值」「4xx 占比」「5xx 占比」「状态码」「热门 URL（估算）」「热门 IP（估算）」；点击指标打开详情。
  3. 点击「刷新」重新读取。
  4. 需要处理某一项时，点击该行右侧的「⋯」：热门 IP 可「封禁 IP」（网站「统计」页签中预填该网站，概览中预填「全局」范围）；网站「统计」页签的热门 URL 可「刷新 URL」，路径展开到网站的每个非泛域名，确认列出的 URL 后提交刷新任务。

统计数据

项目行为
保留分钟明细 7 天，小时汇总 90 天，天汇总 365 天；统计模式为 clickhouse 时，控制台图表和告警仍使用 PostgreSQL 中的汇总
迟到数据迟到的分钟数据触发对应小时和天的重算；早于 7 天的数据被丢弃
汇总后台任务每分钟增量汇总；UTC 边界固定；长期图表读取已完成的小时汇总和尚未汇总的明细
热门 URL / IP节点端有界的 Space-Saving 近似计数，界面标明「估算」：每个 worker 每分钟最多跟踪 128 个网站桶，每桶最多 32 个候选；每桶保留前 50 项；可能遗漏低频项，不用于计费
URL 内容不含查询字符串和请求头；超过 512 字节、含 ? 或控制字符的路径不计入；路径本身仍可能包含业务标识
计数上限单个节点、网站、时间桶的累计计数上限为 9,007,199,254,740,991（Number.MAX_SAFE_INTEGER），达到后保持该值
删除删除节点保留网站的历史统计与日志；删除网站删除其统计和 PostgreSQL 中的日志

上报与去重

项目行为
批次节点把统计批次和单调序号写入状态目录的 traffic-spool.json（0600），再经节点通道（mTLS）上报
去重回执丢失、节点重启或本地回执写入失败时重发同一序号；控制台在一个事务内更新统计和该节点的游标，重复序号不重复计数；本地序号文件丢失时节点从控制台游标重新同步
离线队列最多 10000 个桶、32 MiB；溢出时丢弃并记录日志
内存计数未转存的计数 2 小时后过期；进程在首次持久化之前崩溃会丢失内存中的计数
语义可重试批次的去重，不是计费级的逐请求 exactly-once
旧节点不带序号的旧版上报被拒绝；这类节点在 集群与节点 中显示「需要升级」

启用访问日志

  1. 打开 网站，选择网站，进入「日志」页签。
  2. 在「访问日志采样率」中选择「1%」「10%」或「100%」。选择后立即保存并发布新的配置版本，提示「已保存」。
  3. 验证：产生请求后，在查询表单点击「查询」，列表出现记录。
字段取值默认值作用
访问日志采样率关闭 / 1% / 10% / 100%关闭记录请求的比例；API 接受 0–10000 的万分比整数
记录的字段不记录
时间、客户端 IP、方法、Host、路径、状态码、发送字节、耗时（毫秒）、缓存状态、采样率、节点 ID查询参数、请求头、Cookie、请求和响应正文

网站在「安全 → 挑战设置」打开「访问日志记录 JA4」后，日志另记录 JA4 TLS 客户端指纹（明文 HTTP 为空），列表出现「JA4」列，CSV 增加 ja4 列。关闭后控制台不再保存该字段。JA4 的格式见 JA4。

网站开启 OWASP CRS 后，命中规则的请求另记录命中的规则 ID（每个请求最多 16 个，升序）与是否被拦截：列表出现「CRS」列（规则 ID 与「已拦截」标记），CSV 增加 wafRuleIds（空格分隔）与 wafBlocked 列。

配置阶段的规则可用「日志采样率（%）」为匹配的请求设置采样率；网站采样率为「关闭」时，这些请求的日志同样保存，见覆盖设置。

启用访问日志需要节点能力 access-logs-v1，记录 JA4 另需 ja4-v1。配置回滚保留当前采样率与 JA4 设置，不会重新启用已关闭的日志。

查询与导出日志

  1. 在「日志」页签填写「开始时间」「结束时间」，按需填写「状态码」「客户端 IP」「路径前缀」「请求 ID」。

  2. 点击「查询」。

  3. 需要文件时点击「导出 CSV」。

  4. 需要处理某条请求时，点击该行右侧的「⋯」，操作在当前页完成：

    操作行为
    封禁 IP打开封禁对话框，已填好本网站与客户端 IP；「范围」可改为「全局」，见封禁
    刷新 URL确认后为该请求的 Host 与路径创建 URL 刷新任务，见刷新与预热
    排除 CRS 规则 N只在命中 CRS 规则的行出现，每条命中的规则一项；确认后把规则 ID 追加到网站的排除列表，见OWASP CRS。初始化、拦截判定与关联类规则（901xxx、949xxx、959xxx、980xxx）不提供，排除它们等于关闭拦截

    完成后的提示带有链接，打开封禁列表、刷新任务或 CRS 设置。

项目行为
时间范围默认最近 1 小时；最早为 6 天前的 UTC 零点，最晚为当前时间后 5 分钟；结束时间须晚于开始时间
过滤状态码精确匹配；客户端 IP 精确匹配；路径按前缀匹配；请求 ID 精确匹配
请求 ID每条日志显示节点给出的请求 ID（与响应头 X-Request-Id 和错误页上的相同），CSV 的 requestId 列；更早的节点上报的日志为空
条数界面最多显示 100 条，超出时提示「显示前 100 条，请缩小查询范围」；CSV 最多 1000 条，超出时提示「已导出前 1000 条，请缩小时间范围以获取其他记录」
CSV每个单元格加双引号并转义引号；以 =、+、-、@ 开头的值前加 '，避免被电子表格当作公式
调用方控制台会话或 AccessKey，只读 AccessKey 也可以查询与导出；服务账号不能调用

日志的采集与存储

项目行为
采集节点通过 mTLS 按批次上报，每批最多 1000 条；控制台用每个节点的持久游标防止重试重复写入
节点内存队列约 2000 条（8 MiB）；满时新日志被丢弃
节点磁盘队列状态目录的 logs-spool.json（0600），最多 10000 条、32 MiB；满时丢弃最旧的未发送批次并记录警告
丢失请求结束到批次落盘之间，进程或主机崩溃会丢失日志
lite 存储PostgreSQL 按 UTC 日期分区，保留今天及前 6 天；后台任务每分钟维护分区
clickhouse 存储按天分区的 ReplacingMergeTree，7 天 TTL，查询时用 FINAL 去重；ClickHouse 写入失败时不确认批次，节点重试，不改写入 PostgreSQL

使用 ClickHouse 存储

  1. 在控制台的 .env 中启用 analytics profile，设置统计模式和 ClickHouse 密码：

    .env
    COMPOSE_PROFILES=analytics
EDGEWEIR_ANALYTICS=clickhouse
EDGEWEIR_CLICKHOUSE_PASSWORD=<密码>

  2. 启动 Compose 部署；COMPOSE_PROFILES 让此后的每条 docker compose 命令都包含 ClickHouse：

    docker compose up -d

  3. 验证：系统设置 的「系统信息」中「统计模式」显示 clickhouse。

EDGEWEIR_CLICKHOUSE_URL、EDGEWEIR_CLICKHOUSE_DATABASE、EDGEWEIR_CLICKHOUSE_USER 的默认值与外部 ClickHouse 的配置见环境变量。

项目行为
切换只影响新写入；不迁移历史日志和统计
分钟统计同步写入 ClickHouse 的 minute_stats 表（ReplacingMergeTree，以节点批次序号为版本），直接分析时使用 FINAL
图表与告警仍使用 PostgreSQL 的精确分钟、小时、天汇总，两种模式计数口径一致；采样日志不用于统计全量流量
删除网站控制台立即停止对该网站日志的查询授权；ClickHouse 中的原始数据按 7 天 TTL 清除

创建 AccessKey

  1. 在用户菜单（侧栏底部）中打开 个人设置，找到「AccessKey」卡片。

  2. 填写「名称」（1–64 字符；留空时为 default），选择「权限范围」。

  3. 点击「创建」。

  4. 复制显示的密钥。密钥只显示一次（「仅显示一次」）。

  5. 验证：

    curl -s -o /dev/null -w '%{http_code}\n' -H 'x-api-key: <密钥>' https://console.example.com/api/v1/sites

    输出 200。

字段取值默认值作用
名称1–64 字符default列表中的显示名
权限范围只读 / 读写读写只读密钥只能调用 GET 接口与 rules.validate，其他接口返回 403（ACCESS_KEY_READ_ONLY）

请求格式与接口列表见 API 与端点。

吊销 AccessKey

  1. 在 个人设置 的「AccessKey」卡片中，对目标密钥点击「吊销密钥」并确认。
  2. 验证：密钥显示「已吊销」；使用该密钥的请求返回 401。
项目行为
列表「AccessKey」卡片列出全部密钥，含权限范围和「最后使用：…」
身份密钥以控制台账户的身份调用 API，审计日志中的操作者类型为 AccessKey
签发只能在已登录的控制台会话中创建（个人设置 页，或经 /rpc 调用 accessKeys.create）；任何 AccessKey（包括读写密钥和旧版密钥）都不能创建新密钥：POST /api/v1/access-keys 返回 403（ACCESS_KEY_SESSION_REQUIRED）
旧版密钥未设置权限范围的旧版密钥保持读写权限；按用途吊销并重建

限制

项目说明
采样率界面只提供关闭、1%、10%、100%；其他比例通过 API 设置
日志保留两种存储模式都约为 7 天，不可配置
完整性访问日志有队列上限且可能丢失，不能作为审计账本；统计不是计费级精确计数
热门 URL / IP近似值，可能遗漏低频项
历史迁移切换统计模式不迁移历史数据

故障排查

现象原因处理
「没有匹配的日志」采样率为关闭或过低；时间范围早于保留期；节点未应用启用日志的版本或缺少 access-logs-v1检查采样率、时间范围和节点「已应用版本」
「结束时间必须晚于开始时间」时间范围无效调整时间
「显示前 100 条，请缩小查询范围」匹配超过 100 条缩小时间范围或增加过滤条件，或导出 CSV
「已导出前 1000 条，…」匹配超过 1000 条分段导出
统计图表为空网站没有流量，或节点未上报检查节点心跳和网站域名是否已发布
节点显示「需要升级」节点不支持带序号的统计上报或当前配置要求的能力升级节点，见节点升级
「请登录控制台后创建密钥」用 AccessKey 调用了创建接口在已登录的控制台中创建
「此密钥只有只读权限」只读密钥调用写接口创建读写密钥
在 GitHub 上编辑

四层转发

TCP / UDP 端口转发：端口池、L4 应用、PROXY protocol、DNS、统计与节点端口。

节点升级

分批升级节点：试运行、推进、节点侧验签与自动回滚，以及节点能力。

本页目录

概念查看统计统计数据上报与去重启用访问日志查询与导出日志日志的采集与存储使用 ClickHouse 存储创建 AccessKey吊销 AccessKey限制故障排查