argus/build

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 产出阶段追加，我可以按需补齐。