# ARGUS 统一构建脚本使用说明（build/build_images.sh）

本目录提供单一入口脚本 `build/build_images.sh`，覆盖常见三类场景：
- 系统集成测试（src/sys/tests）
- Swarm 系统集成测试（src/sys/swarm_tests）
- 构建离线安装包（deployment_new：Server/Client‑GPU）

文档还说明 UID/GID 取值规则、镜像 tag 策略、常用参数与重试机制。

## 环境前置
- Docker Engine ≥ 20.10（建议 ≥ 23.x/24.x）
- Docker Compose v2（`docker compose` 子命令）
- 可选：内网构建镜像源（`--intranet`）

## UID/GID 规则（用于容器内用户/卷属主）
- 非 pkg 构建（core/master/metric/web/alert/sys/gpu_bundle/cpu_bundle）：
  - 读取 `configs/build_user.local.conf` → `configs/build_user.conf`；
  - 可被环境变量覆盖：`ARGUS_BUILD_UID`、`ARGUS_BUILD_GID`；
- pkg 构建（`--only server_pkg`、`--only client_pkg`）：
  - 读取 `configs/build_user.pkg.conf`（优先）→ `build_user.local.conf` → `build_user.conf`；
  - 可被环境变量覆盖；
- CPU bundle 明确走“非 pkg”链（不读取 `build_user.pkg.conf`）。
- 说明：仅依赖 UID/GID 的 Docker 层会因参数变动而自动重建，不同构建剖面不会“打错包”。

## 镜像 tag 策略
- 非 pkg 构建：默认输出 `:latest`。
- `--only server_pkg`：所有镜像直接输出为 `:<VERSION>`（不覆盖 `:latest`）。
- `--only client_pkg`：GPU bundle 仅输出 `:<VERSION>`（不覆盖 `:latest`）。
- `--only cpu_bundle`：默认仅输出 `:<VERSION>`；可加 `--tag-latest` 同时打 `:latest` 以兼容 swarm_tests 默认 compose。

## 不加 --only 的默认构建目标
不指定 `--only` 时，脚本会构建“基础镜像集合”（不含 bundle 与安装包）：
- core：`argus-elasticsearch:latest`、`argus-kibana:latest`、`argus-bind9:latest`
- master：`argus-master:latest`（非 offline）
- metric：`argus-metric-ftp:latest`、`argus-metric-prometheus:latest`、`argus-metric-grafana:latest`
- web：`argus-web-frontend:latest`、`argus-web-proxy:latest`
- alert：`argus-alertmanager:latest`
- sys：`argus-sys-node:latest`、`argus-sys-metric-test-node:latest`、`argus-sys-metric-test-gpu-node:latest`

说明：默认 tag 为 `:latest`；UID/GID 走“非 pkg”链（`build_user.local.conf → build_user.conf`，可被环境变量覆盖）。

## 通用参数
- `--intranet`：使用内网构建参数（各 Dockerfile 中按需启用）。
- `--no-cache`：禁用 Docker 层缓存。
- `--only <list>`：逗号分隔目标，例：`--only core,master,metric,web,alert`。
- `--version YYMMDD`：bundle/pkg 的日期标签（必填于 cpu_bundle/gpu_bundle/server_pkg/client_pkg）。
- `--client-semver X.Y.Z`：all‑in‑one‑full 客户端语义化版本（可选）。
- `--cuda VER`：GPU bundle CUDA 基镜版本（默认 12.2.2）。
- `--tag-latest`：CPU bundle 构建时同时打 `:latest`。

## 自动重试
- 构建单镜像失败会自动重试（默认 3 次，间隔 5s）。
- 最后一次自动使用 `DOCKER_BUILDKIT=0` 再试，缓解 “failed to receive status: context canceled”。
- 可调：`ARGUS_BUILD_RETRIES`、`ARGUS_BUILD_RETRY_DELAY` 环境变量。

---

## 场景一：系统集成测试（src/sys/tests）
构建用于系统级端到端测试的镜像（默认 `:latest`）。

示例：
```
# 构建核心与周边
./build/build_images.sh --only core,master,metric,web,alert,sys
```
产出：
- 本地镜像：`argus-elasticsearch:latest`、`argus-kibana:latest`、`argus-master:latest`、`argus-metric-ftp:latest`、`argus-metric-prometheus:latest`、`argus-metric-grafana:latest`、`argus-alertmanager:latest`、`argus-web-frontend:latest`、`argus-web-proxy:latest`、`argus-sys-node:latest` 等。

说明：
- UID/GID 读取 `build_user.local.conf → build_user.conf`（或环境变量覆盖）。
- sys/tests 的执行见 `src/sys/tests/README.md`。

---

## 场景二：Swarm 系统集成测试（src/sys/swarm_tests）
需要服务端镜像 + CPU 节点 bundle 镜像。

步骤：
1) 构建服务端镜像（默认 `:latest`）
```
./build/build_images.sh --only core,master,metric,web,alert
```
2) 构建 CPU bundle（直接 FROM ubuntu:22.04）
```
# 仅版本 tag 输出
./build/build_images.sh --only cpu_bundle --version 20251114
# 若要兼容 swarm_tests 默认 latest：
./build/build_images.sh --only cpu_bundle --version 20251114 --tag-latest
```
3) 运行 Swarm 测试
```
cd src/sys/swarm_tests
# 如未打 latest，可先指定：
export NODE_BUNDLE_IMAGE_TAG=argus-sys-metric-test-node-bundle:20251114
./scripts/01_server_up.sh
./scripts/02_wait_ready.sh
./scripts/03_nodes_up.sh
./scripts/04_metric_verify.sh   # 验证 Prometheus/Grafana/nodes.json 与日志通路
./scripts/99_down.sh            # 结束
```
产出：
- 本地镜像：`argus-*:latest` 与 `argus-sys-metric-test-node-bundle:20251114`（或 latest）。
- `swarm_tests/private-*`：运行态持久化文件。

说明：
- CPU bundle 构建用户走“非 pkg”链（local.conf → conf）。
- `04_metric_verify.sh` 已内置 Fluent Bit 启动与配置修正逻辑，偶发未就绪可重跑一次即通过。

---

## 场景三：构建离线安装包（deployment_new）
Server 与 Client‑GPU 安装包均采用“版本直出”，只输出 `:<VERSION>` 标签，不改动 `:latest`。

1) Server 包
```
./build/build_images.sh --only server_pkg --version 20251114
```
产出：
- 本地镜像：`argus-<模块>:20251114`（不触碰 latest）。
- 安装包：`deployment_new/artifact/server/20251114/` 与 `server_20251114.tar.gz`
- 包内包含：逐镜像 tar.gz、compose/.env.example、scripts（config/install/selfcheck/diagnose 等）、docs、manifest/checksums。

2) Client‑GPU 包
```
# 同步构建 GPU bundle（仅 :<VERSION>，不触碰 latest），并生成客户端包
./build/build_images.sh --only client_pkg --version 20251114 \\
  --client-semver 1.44.0 --cuda 12.2.2
```
产出：
- 本地镜像：`argus-sys-metric-test-node-bundle-gpu:20251114`
- 安装包：`deployment_new/artifact/client_gpu/20251114/` 与 `client_gpu_20251114.tar.gz`
- 包内包含：GPU bundle 镜像 tar.gz、busybox.tar、compose/.env.example、scripts（config/install/uninstall）、docs、manifest/checksums。

说明：
- pkg 构建使用 `configs/build_user.pkg.conf` 的 UID/GID（可被环境覆盖）。
- 包内 `.env.example` 的 `PKG_VERSION=<VERSION>` 与镜像 tag 严格一致。

---

## 常见问题（FAQ）
- 构建报 `failed to receive status: context canceled`？
  - 已内置单镜像多次重试，最后一次禁用 BuildKit；建议加 `--intranet` 与 `--no-cache` 重试，或 `docker builder prune -f` 后再试。
- 先跑非 pkg（latest），再跑 pkg（version）会不会“打错包”？
  - 不会。涉及 UID/GID 的层因参数变化会重建，其它层按缓存命中复用，最终 pkg 产物的属主与运行账户按 `build_user.pkg.conf` 生效。
- swarm_tests 默认拉取 `:latest`，我只构建了 `:<VERSION>` 的 CPU bundle 怎么办？
  - 在运行前 `export NODE_BUNDLE_IMAGE_TAG=argus-sys-metric-test-node-bundle:<VERSION>`，或在构建时加 `--tag-latest`。

---

如需进一步自动化（例如生成 BUILD_SUMMARY.txt 汇总镜像 digest 与构建参数），可在 pkg 产出阶段追加，我可以按需补齐。