netdata/static-builder

Netdata 静态构建基础镜像文档

1. 镜像概述和主要用途

1.1 概述

Netdata 静态构建基础镜像是 Netdata 官方提供的专用基础镜像，用于标准化、自动化构建 Netdata 的官方静态二进制版本。该镜像预配置了构建所需的完整工具链、依赖库及环境，确保静态构建过程的一致性和可靠性。

1.2 主要用途

作为 Netdata 静态构建的“底层环境”，提供编译、链接、打包等全流程支持，最终生成不依赖系统动态库（如 libc、libssl）的独立静态二进制文件，可直接在各类 Linux 系统中部署运行。

2. 核心功能和特性

• 完整工具链集成：内置 GCC、GNU Make、CMake 等编译工具，以及静态版本的依赖库（如 libmnl、libuuid、zlib），无需额外安装构建依赖。
• 静态链接优化：通过编译选项强制静态链接所有依赖，确保输出的 Netdata 二进制文件具备跨系统兼容性（如在不同 Linux 发行版、内核版本中运行）。
• 版本对齐：与 Netdata 官方发布版本严格同步，支持指定版本构建（如 v1.44.0、v1.45.0），避免版本兼容性问题。
• 精简镜像体积：基于 Alpine 或最小化 Debian 基础镜像构建，剔除冗余组件，降低存储和传输成本。
• 多架构支持：提供 x86_64、armv7、arm64 等主流架构的镜像变体，覆盖服务器、嵌入式设备等场景。

3. 使用场景和适用范围

3.1 使用场景

• 官方版本构建：Netdata 维护团队用于生成发布到官网的静态二进制包。
• 自定义静态构建：用户需修改 Netdata 源码（如新增插件、调整配置）后，生成个性化静态版本。
• 跨平台部署测试：在单一环境中构建多架构静态产物，验证其在不同目标系统（如 CentOS、Ubuntu、嵌入式 Linux）的兼容性。

3.2 适用范围

• 运行环境：Linux 操作系统（支持 docker 或 podman 的环境）。
• 用户群体：Netdata 开发者、系统管理员、需要离线/无依赖部署 Netdata 的场景。

4. 使用方法和配置说明

4.1 获取镜像

镜像托管于 Docker Hub 的 Netdata 官方仓库，通过标签区分版本和架构。

bash
# 拉取最新版本（默认 x86_64 架构）
docker pull netdata/static-build-base:latest

# 拉取指定版本（如 v1.44.0）
docker pull netdata/static-build-base:v1.44.0

# 拉取特定架构（如 arm64）
docker pull netdata/static-build-base:latest-arm64

4.2 基础构建流程

1. 准备源码：本地克隆 Netdata 源码仓库（或下载指定版本源码包）。
2. 挂载源码目录：通过容器挂载本地源码，确保构建过程可访问源码文件。
3. 执行构建命令：运行容器并调用内置构建脚本，生成静态二进制。
4. 提取产物：从容器中复制构建完成的静态二进制到本地。

4.3 核心配置参数

4.3.1 环境变量

4.4 部署示例

4.4.1 基础静态构建（x86_64 架构）

bash
# 假设本地 Netdata 源码路径为 /opt/netdata-src，构建产物输出到 /opt/netdata-static
docker run --rm \
  -v /opt/netdata-src:/netdata-src \  # 挂载源码目录
  -v /opt/netdata-static:/netdata-static \  # 挂载产物输出目录
  -e TARGET_ARCH=x86_64 \  # 指定目标架构
  netdata/static-build-base:latest \  # 使用最新基础镜像
  /bin/bash -c "cd /netdata-src && ./packaging/static/build.sh"  # 执行官方构建脚本

4.4.2 自定义构建选项（禁用云功能+ARM64架构）

bash
docker run --rm \
  -v /opt/netdata-src:/netdata-src \
  -v /opt/netdata-static-arm64:/netdata-static \
  -e TARGET_ARCH=arm64 \
  -e STATIC_BUILD_OPTS="--disable-cloud --enable-plugin=diskspace" \  # 禁用云功能，启用磁盘空间插件
  netdata/static-build-base:v1.44.0 \  # 使用指定版本镜像
  /bin/bash -c "cd /netdata-src && ./packaging/static/build.sh"

4.4.3 产物提取与验证

构建完成后，静态二进制 netdata 位于容器的 /netdata-static 目录（或用户指定的 OUTPUT_DIR），通过挂载的本地目录直接获取：

bash
# 验证产物是否为静态链接（无动态依赖）
file /opt/netdata-static/netdata
# 输出示例：/opt/netdata-static/netdata: ELF 64-bit LSB executable, x86-64, version 1 (GNU/Linux), statically linked, ...

5. 注意事项

• 源码完整性：确保挂载的 Netdata 源码目录包含完整文件（尤其是 packaging/static/build.sh 构建脚本），否则可能导致构建失败。
• 架构匹配：构建非 x86_64 架构时，需使用对应架构的基础镜像标签（如 arm64 架构使用 netdata/static-build-base:latest-arm64）。
• 兼容性验证：静态产物虽具备跨系统兼容性，但建议在目标系统（如老旧 CentOS 7）中测试，避免因内核版本差异导致功能异常。
• 镜像更新：基础镜像会随 Netdata 版本迭代更新，建议定期拉取最新标签以获取工具链和依赖库的安全补丁。