# waf-platform 编译、部署、升级策略（WSL Ubuntu 22.04）

## 1. 适用范围

- 主基线：`E:\AI_PRODUCT\waf-platform`（不是 `waf-platform-1.4.5/1.4.6`）。
- 本手册覆盖：
  - `EdgeAdmin` / `EdgeAPI` / `EdgeNode` / `EdgeDNS`
  - HTTP + DNS 访问日志策略
  - Fluent Bit + ClickHouse 日志链路

---

## 2. 关键结论（先看）

1. 用 `EdgeAdmin/build/build.sh` 编译时，会联动编译 `EdgeAPI`，并由 `EdgeAPI` 联动编译 `EdgeNode`。  
2. `EdgeDNS` 只有在 `plus` 模式下才会被 `EdgeAPI/build/build.sh` 自动编译并放入 deploy。  
3. 当前脚本已临时关闭自动 `arm64` 编译，只保留 `amd64` 自动链路。  
3. 如果你要发布“本次所有改动”（含 DNS/ClickHouse），建议统一用：
   ```bash
   cd /mnt/e/AI_PRODUCT/waf-platform/EdgeAdmin/build
   bash build.sh linux amd64 plus
   ```
4. DNS 节点与 Node 节点分离部署时，两边都要有 Fluent Bit（各自采集本机日志）。

---

## 3. 编译前检查

在 WSL Ubuntu 22.04 执行：

```bash
cd /mnt/e/AI_PRODUCT/waf-platform
git rev-parse --short HEAD
go version
which zip unzip go find sed
```

建议：

- 线上 Ubuntu 22.04，尽量也在 Ubuntu 22.04 编译，避免 `GLIBC`/`GLIBCXX` 不兼容。
- 若 Node plus 使用 cgo/libpcap/libbrotli，请确保构建机依赖完整。

---

## 4. 一键编译（推荐）

```bash
cd /mnt/e/AI_PRODUCT/waf-platform/EdgeAdmin/build
bash build.sh linux amd64 plus
```

### 4.1 此命令会做什么

- 编译 `EdgeAdmin`
- 自动调用 `EdgeAPI/build/build.sh`
- `EdgeAPI` 自动编译并打包 `EdgeNode`（当前仅 linux/amd64）
- `plus` 模式下，`EdgeAPI` 自动编译并打包 `EdgeDNS`（当前仅 linux/amd64）
- 把 node/dns 包放入 API 的 `deploy` 目录用于远程安装

### 4.2 主要产物位置

- Admin 包：`EdgeAdmin/dist/edge-admin-linux-amd64-v*.zip`
- API 包：`EdgeAPI/dist/edge-api-linux-amd64-v*.zip`
- Node 包：`EdgeNode/dist/edge-node-linux-*.zip`
- DNS 包：`EdgeDNS/dist/edge-dns-linux-*.zip`（plus 时）
- API deploy 安装包目录：`EdgeAPI/build/deploy/`

---

## 5. 是否需要单独编译 API / DNS / Node

### 5.1 不需要单独编译 API 的场景

- 你已经执行 `EdgeAdmin/build/build.sh ... plus`，且要发布整套改动。

### 5.2 需要单独编译的场景

- 只改了 API，不想重新打 Admin：
  ```bash
  cd /mnt/e/AI_PRODUCT/waf-platform/EdgeAPI/build
  bash build.sh linux amd64 plus
  ```
- 只改了 Node：
  ```bash
  cd /mnt/e/AI_PRODUCT/waf-platform/EdgeNode/build
  bash build.sh linux amd64 plus
  ```
- 只改了 DNS：
  ```bash
  cd /mnt/e/AI_PRODUCT/waf-platform/EdgeDNS/build
  bash build.sh linux amd64
  ```

---

## 6. 升级顺序（生产建议）

## 6.1 第一步：先改 ClickHouse（DDL）

先在 ClickHouse 建/改表，至少包含：

- `logs_ingest`（HTTP）
- `dns_logs_ingest`（DNS）

先做 DDL 的原因：避免新版本写入时目标表不存在。

## 6.2 第二步：部署 Fluent Bit 配置

### Node 节点（HTTP）

- 配置文件目录一般是 `/etc/fluent-bit/`
- 至少更新：
  - `fluent-bit.conf`（或你实际启用的 `fluent-bit-http.conf`）
  - `clickhouse-upstream.conf`
  - `parsers.conf`（通常可复用）

### DNS 节点（DNS）

- DNS 节点若之前没装 Fluent Bit，需要先安装并创建 service。
  - `curl https://raw.githubusercontent.com/fluent/fluent-bit/master/install.sh | sh`
  - `sudo apt-get update`
  - `sudo apt-get install -y fluent-bit`
- 建议同样用 `/etc/fluent-bit/`，放：
  - `fluent-bit.conf`（DNS 版本或含 DNS INPUT/OUTPUT 的统一版本）
  - `clickhouse-upstream.conf`
  - `parsers.conf`

重启：

```bash
sudo systemctl restart fluent-bit
sudo systemctl status fluent-bit
```

## 6.3 第三步：升级管理面（API + Admin）

在管理节点更新 `edge-api`、`edge-admin` 包并重启对应服务。
./bin/edge-api status
./bin/edge-api restart

## 6.4 第四步：升级数据面（Node / DNS）

- 通过 API 的远程安装/升级流程分批升级 Node、DNS
- 或手工替换二进制后重启服务

## 6.5 第五步：最后切换日志策略

在页面启用目标策略（MySQL only / ClickHouse only / 双写），并验证读写链路。

---

## 7. 日志策略与读写行为（当前实现）

## 7.1 HTTP / DNS 共用语义

- `WriteMySQL=true`：写 MySQL（通过 API）
- `WriteClickHouse=true`：写本地日志文件，由 Fluent Bit 异步采集进 CH
- 两者都开：双写
- 两者都关：不写

## 7.2 查询侧优先级

- 优先读 ClickHouse（可用且策略允许）
- ClickHouse 异常时按策略回退 MySQL
- 若两边都不可读，返回空

## 7.3 关于“日志文件路径”

- 现在前端已调整：当存储类型包含 ClickHouse 时，创建/编辑页隐藏“日志文件路径”输入。
- 但 Fluent Bit 的 `Path` 必须匹配实际日志目录；若你改了日志目录，需要同步改 Fluent Bit 配置并重启。

---

## 8. 服务检查与常用命令

## 8.1 检查 Fluent Bit 服务名

```bash
systemctl list-unit-files | grep -Ei 'fluent|td-agent-bit'
systemctl status fluent-bit.service
```

## 8.2 查看 Fluent Bit 实际使用的配置文件

```bash
systemctl status fluent-bit.service
```

重点看 `ExecStart`，例如：

```text
/opt/fluent-bit/bin/fluent-bit -c /etc/fluent-bit/fluent-bit.conf
```

## 8.3 验证 ClickHouse 是否有数据

```sql
SELECT count() FROM default.logs_ingest;
SELECT count() FROM default.dns_logs_ingest;
```

---

## 9. 回滚策略（最小影响）

1. 先把页面日志策略切回 MySQL-only。  
2. 回滚 API/Admin 到上一版本。  
3. Node/DNS 分批回滚。  
4. Fluent Bit 保留运行不影响主业务（只停止 CH 写入即可）。  

---

## 10. 一次发布的最简执行清单

```bash
# 1) 构建
cd /mnt/e/AI_PRODUCT/waf-platform/EdgeAdmin/build
bash build.sh linux amd64 plus

# 2) 上传产物
# EdgeAdmin/dist/*.zip
# EdgeAPI/dist/*.zip
# EdgeAPI/build/deploy/* (node/dns installer zip)

# 3) 线上先执行 CH DDL
# 4) 更新 fluent-bit 配置并重启
sudo systemctl restart fluent-bit

# 5) 升级 edge-api / edge-admin 并重启
# 6) 升级 edge-node / edge-dns
# 7) 切日志策略并验证
```