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

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

---

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

```mermaid
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`：
   ```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`）。

### 3.3 本地日志轮转（默认开启）
从当前版本开始，EdgeNode / EdgeDNS 使用内建 `lumberjack` 轮转，不再依赖系统 `logrotate`。

默认值：
- `maxSizeMB=256`
- `maxBackups=14`
- `maxAgeDays=7`
- `compress=false`
- `localTime=true`

可在策略 `file.rotate` 中配置，例如：

```json
{
  "path": "/var/log/web-access-${date}.log",
  "autoCreate": true,
  "rotate": {
    "maxSizeMB": 256,
    "maxBackups": 14,
    "maxAgeDays": 7,
    "compress": false,
    "localTime": true
  }
}
```

---

## 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. 配置生效链路图

```mermaid
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 写入链路

```mermaid
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 查询链路

```mermaid
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`）有写权限。