waf-platform/访问日志策略配置手册.md

访问日志策略配置手册（默认安装 / 仅MySQL / 仅ClickHouse / 双写）

1. 适用范围

• 代码基线：e:\AI_PRODUCT\waf-platform
• 页面入口：系统设置 -> 访问日志 -> 日志策略
• 查询入口：网站 -> 站点 -> 日志（/servers/server/log）

---

2. 默认安装后的行为（什么都不配）

flowchart TD
  A[EdgeNode 产生日志] --> B[写本地文件 /var/log/edge/edge-node/*.log]
  A --> C[上报 EdgeAPI]
  C --> D[写 MySQL 访问日志表]
  E[日志查询页] --> D

• 默认即可写日志，不会因为没配 ClickHouse 就停写。
• 查询默认走 MySQL。
• 是否有“独立日志数据库节点”会影响写到哪个 MySQL：
  • 有日志库节点：优先写日志库节点池。
  • 没有日志库节点：回退写默认数据库。

---

3. 必须设置项（上线最小集）

3.1 基础必需（任何模式都建议）

1. EdgeAPI 数据库连接可用（db.yaml / .db.yaml）。
2. EdgeNode 与 EdgeAPI 通信正常（节点在线，可上报日志）。
3. 建议创建并启用一个公用访问日志策略（避免多环境行为不一致）。

3.2 仅 ClickHouse / MySQL+ClickHouse 额外必需

1. EdgeAPI 配置 ClickHouse 读取：
   • EdgeAPI/configs/api.yaml：

   clickhouse:
     host: 127.0.0.1
     port: 8123
     user: default
     password: "xxxxxx"
     database: default
   

2. Fluent Bit 已部署并运行，采集：
   • /var/log/edge/edge-node/*.log
3. ClickHouse 已建表：logs_ingest（见 deploy/fluent-bit/README.md）。

---

4. 三种目标模式怎么配

4.1 只写入 MySQL

在“日志策略”中：

1. 新建或修改策略，存储类型 选 文件+MySQL。
2. 设为 公用，并确保 启用。
3. 日志文件路径 填一个 API 可写路径（必填校验项）：
   • 示例：/var/log/edge/edge-api/http-access-${date}.log

结果：

• 写入：MySQL（主路径）+ Node 本地日志文件
• 查询：MySQL
• 不依赖 ClickHouse

---

4.2 只写入 ClickHouse

在“日志策略”中：

1. 存储类型 选 文件+ClickHouse。
2. 设为 公用，并确保 启用。
3. 日志文件路径 仍需填写（策略校验要求）：
   • 示例：/var/log/edge/edge-api/http-access-${date}.log
4. 确保 Fluent Bit 正在采集 Node 目录并写入 ClickHouse。
5. 确保 EdgeAPI 的 ClickHouse 连接已配置。

结果：

• 写入：Node 本地文件 -> Fluent Bit -> ClickHouse
• API 不写 MySQL
• 查询优先 ClickHouse（无 CH 时可能查不到数据）

---

4.3 同时写入 MySQL + ClickHouse

在“日志策略”中：

1. 存储类型 选 文件+MySQL+ClickHouse。
2. 设为 公用，并确保 启用。
3. 日志文件路径 填写有效路径（同上）。
4. ClickHouse + Fluent Bit 同 4.2 要求。

结果：

• 写入：MySQL + ClickHouse（并行）
• 查询：优先 ClickHouse，失败可回退 MySQL

---

5. 配置生效链路图

flowchart LR
  P[公用日志策略 type/writeTargets] --> C[EdgeAPI 解析 writeTargets]
  C --> N[下发到 EdgeNode GlobalServerConfig.HTTPAccessLog.WriteTargets]
  N --> W1[NeedWriteFile]
  N --> W2[NeedReportToAPI]
  W1 --> F[Node本地日志文件]
  F --> FB[Fluent Bit]
  FB --> CH[(ClickHouse.logs_ingest)]
  W2 --> API[CreateHTTPAccessLogs]
  API --> MYSQL[(MySQL访问日志表)]

---

6. 验证清单（建议上线前逐项过）

1. 打开 /servers/server/log，持续压测 1~2 分钟。
2. 检查最新日志是否持续上顶（不是停在旧时间段）。
3. 错误日志筛选是否只显示 status>=400。
4. 仅 CH 模式下，停掉 Fluent Bit 后确认告警和查询表现符合预期。
5. MySQL+CH 模式下，临时断 CH，确认页面可回退 MySQL。

---

7. 常见问题

Q1：策略里的“日志文件路径”是干嘛的？

• 这是策略 file 配置的必填项（API 侧校验）。
• 即使你用 ClickHouse 链路，当前实现仍要求该字段有值。
• 真正给 Fluent Bit 采集的是 Node 目录：/var/log/edge/edge-node/*.log。

Q2：不勾“停用默认数据库存储”，会不会同时写默认库和独立日志库？

• 正常不会双写同一条。
• 有独立日志库节点时优先写节点池；节点池不可用时才回退默认库。

Q3：修改策略后要不要重启？

• 通常 1 分钟内自动刷新生效。
• 若要立即生效：重启 edge-api，并在需要时重启 edge-node、fluent-bit。

---

8. DNS 日志与 HTTP 策略联动（新增）

从当前版本开始，DNS 访问日志与 HTTP 访问日志共享同一套公用策略语义（writeTargets）：

• WriteMySQL=true：DNS 节点上报 API，API 写入 MySQL 分表。
• WriteClickHouse=true：DNS 节点写本地 JSONL，Fluent Bit 采集写入 ClickHouse dns_logs_ingest。
• 双开即双写；双关即不写（仅保留内存处理，不入库）。

8.1 DNS 写入链路

flowchart LR
  A[EdgeDNS 产生日志] --> B{writeTargets}
  B -->|MySQL=true| C[CreateNSAccessLogs]
  C --> D[(MySQL edgeNSAccessLogs_YYYYMMDD)]
  B -->|ClickHouse=true| E[/var/log/edge/edge-dns/access.log]
  E --> F[Fluent Bit]
  F --> G[(ClickHouse dns_logs_ingest)]

8.2 DNS 查询链路

flowchart TD
  Q[/ns/clusters/accessLogs] --> R{策略是否启用ClickHouse且CH可用}
  R -->|是| CH[(dns_logs_ingest)]
  R -->|否| M{策略是否启用MySQL}
  CH -->|查询失败| M
  M -->|是| MY[(MySQL edgeNSAccessLogs_YYYYMMDD)]
  M -->|否| E[返回空列表]

8.3 组合场景说明（DNS）

策略	写入	读取
仅 MySQL	API -> MySQL	MySQL
仅 ClickHouse	本地文件 -> Fluent Bit -> ClickHouse	ClickHouse
MySQL + ClickHouse	API -> MySQL + 本地文件 -> Fluent Bit -> ClickHouse	优先 ClickHouse，失败回退 MySQL

8.4 DNS 相关必须配置

1. EdgeAPI 配置 ClickHouse 连接（仅读 CH 时必须）。
2. deploy/fluent-bit/fluent-bit.conf 已包含 DNS 输入：/var/log/edge/edge-dns/*.log。
3. ClickHouse 已创建 dns_logs_ingest 表。
4. EdgeDNS 运行用户对 EDGE_DNS_LOG_DIR（默认 /var/log/edge/edge-dns）有写权限。