Grafana 构建环境镜像文档

镜像概述

本镜像为 Grafana 构建专用环境镜像，旨在提供标准化、可重复的 Grafana 编译构建环境。镜像集成了 Grafana 源码构建所需的完整依赖工具链（如 Go 编译器、Node.js、npm/yarn、Make 等），确保开发者或 CI/CD 系统能够在一致的环境中完成 Grafana 从源码到可执行程序/安装包的构建过程。

核心功能与特性

• 完整依赖集成：预装 Grafana 构建所需的全部工具链（Go 1.20+、Node.js 18+、npm、yarn、GCC、Make、git 等），无需额外配置依赖。
• 多平台支持：支持 Linux/amd64、Linux/arm64 等主流架构的构建目标。
• 缓存优化：内置构建缓存机制（如 Go 模块缓存、npm 依赖缓存），加速重复构建过程。
• 灵活构建参数：支持通过环境变量或命令行参数定制构建目标（如指定 Grafana 版本、构建类型、输出格式）。
• 源码兼容性：兼容官方 Grafana 源码仓库（grafana/grafana）的标准构建流程。

使用场景

• 本地开发构建：开发者在本地快速构建 Grafana 源码，验证代码修改效果。
• CI/CD 流水线集成：作为自动化构建环节的基础环境，在 Jenkins、GitLab CI、GitHub Actions 等平台中执行构建任务。
• 定制化版本构建：基于 Grafana 源码修改（如添加自定义插件、调整默认配置）后，构建专属版本。
• 多版本并行构建：通过指定版本参数，在同一环境中构建不同 Grafana 版本。

使用方法与配置说明

前置条件

• 已安装 Docker Engine（20.10+）或 Docker Desktop。
• 本地或远程可访问 Grafana 源码（可通过 git clone 获取官方源码，或挂载本地修改后的源码目录）。

基本使用流程

1. 拉取镜像

docker pull [镜像仓库地址]/grafana-build:latest  # 替换为实际镜像仓库地址

2. 本地构建示例（docker run）

通过挂载 Grafana 源码目录到容器内，执行构建命令：

docker run -it --rm \
  -v /path/to/local/grafana-source:/src/grafana  `# 挂载本地源码目录到容器内/src/grafana` \
  -v /path/to/build-output:/dist                `# 挂载输出目录，存储构建产物` \
  -e GRAFANA_VERSION=10.2.0                    `# 指定构建版本（可选，默认读取源码内版本）` \
  -e BUILD_TARGET=linux-amd64                  `# 指定构建目标平台（可选，默认 linux-amd64）` \
  [镜像仓库地址]/grafana-build:latest          `# 镜像名称` \
  make build-all                               `# 执行构建命令（默认命令，可省略）`

参数说明：

• /path/to/local/grafana-source：本地 Grafana 源码目录绝对路径。
• /path/to/build-output：本地输出目录，构建后的二进制文件、安装包等将保存至此。
• GRAFANA_VERSION：覆盖源码内的版本号（如 10.2.0-custom），默认读取源码 package.json 或 CHANGELOG.md 中的版本。
• BUILD_TARGET：支持的目标平台格式为 <os>-<arch>，如 linux-arm64、darwin-amd64（需源码支持）。

3. docker-compose 配置示例

创建 docker-compose.yml：

version: '3.8'

services:
  grafana-build:
    image: [镜像仓库地址]/grafana-build:latest
    volumes:
      - ./grafana-source:/src/grafana       # 本地源码目录（相对路径）
      - ./build-output:/dist                # 构建产物输出目录
    environment:
      - GRAFANA_VERSION=10.2.0
      - BUILD_TARGET=linux-amd64
      - CACHE_ENABLED=true                  # 启用构建缓存（默认 true）
    command: make build-go                  # 仅构建 Go 后端（可选，默认 make build-all）

启动构建：

docker-compose up

4. 构建命令说明

容器默认执行 make build-all（完整构建，包括前端、后端、文档），也可指定其他构建命令：

环境变量配置

构建产物说明

构建完成后，输出目录（/dist）下的典型产物结构：

/dist
├── grafana-server                # Go 后端二进制文件（对应 BUILD_TARGET 平台）
├── public                        # 前端静态资源（JS/CSS/HTML）
├── packages                      # 前端 npm 包（若执行 `make build-js`）
└── dist                          # 安装包（如 .tar.gz、.deb，若执行 `make package`）

注意事项

• 源码权限：挂载本地源码目录时，需确保容器内用户（通常为 builder，UID 1000）对源码目录有读写权限，避免因权限不足导致构建失败。
• 缓存清理：若需强制重新构建（忽略缓存），可添加环境变量 CACHE_ENABLED=false 或执行 make clean 命令。
• 网络依赖：构建过程需拉取 Go/Node.js 依赖，建议通过 GO_PROXY、NPM_REGISTRY 配置国内镜像加速。
• 版本兼容性：镜像版本需与 Grafana 源码版本匹配（如构建 Grafana 9.x 需使用对应版本的构建镜像，避免工具链不兼容）。