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。