yuyr
7430896fab
Co-authored-by: sundapeng <sundp@mail.zgclab.edu.cn> Co-authored-by: xuxt <xuxt@zgclab.edu.cn> Reviewed-on: #52
151 lines
7.2 KiB
Markdown
151 lines
7.2 KiB
Markdown
# 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 产出阶段追加，我可以按需补齐。
|