菜单

设置

配置 Docker 镜像

Enterprise 开源

配置 Grafana Docker 镜像

本主题解释了如何在需要满足以下条件的复杂环境中在 Docker 上运行 Grafana：

使用不同的镜像
更改日志级别
在 Cloud 上定义秘密
配置插件

注意：本主题中的示例使用 Grafana Enterprise Docker 镜像。您可以通过将 Docker 镜像更改为 grafana/grafana-oss 来使用 Grafana 开源版。

支持的 Docker 镜像变体

您可以使用以下官方 Docker 镜像安装和运行 Grafana。

Grafana Enterprise: grafana/grafana-enterprise
Grafana 开源版: grafana/grafana-oss

每个版本都有两种变体：Alpine 和 Ubuntu。

Alpine 镜像（推荐）

Alpine Linux 是一个不隶属于任何商业实体的 Linux 发行版。它是一个多功能的操作系统，适合优先考虑安全性、效率和用户友好性的用户。Alpine Linux 比其他发行版基础镜像小得多，可以创建更轻量、更安全的镜像。

默认情况下，这些镜像使用广泛使用的 Alpine Linux 项目基础镜像构建，该镜像可以在 Alpine docker 仓库中找到。如果您优先考虑安全性并希望最小化镜像大小，建议使用 Alpine 变体。但是，需要注意的是，Alpine 变体使用 musl libc 而不是 glibc 和其他 libc。因此，某些软件可能会根据其 libc 要求遇到问题。尽管如此，大多数软件应该不会遇到任何问题，因此 Alpine 变体通常是可靠的。

Ubuntu 镜像

基于 Ubuntu 的 Grafana Enterprise 和 OSS 镜像使用 Ubuntu 基础镜像构建，该镜像可以在 Ubuntu docker 仓库中找到。对于偏好基于 Ubuntu 的镜像或需要 Alpine 上不可用的特定工具的用户来说，基于 Ubuntu 的镜像是一个不错的选择。

Grafana Enterprise: grafana/grafana-enterprise:<version>-ubuntu
Grafana 开源版: grafana/grafana-oss:<version>-ubuntu

运行特定版本的 Grafana

您还可以运行特定版本的 Grafana 或基于 grafana/grafana GitHub 仓库主分支的 Beta 版本。

注意：如果您使用 Debian 或 Ubuntu 等 Linux 操作系统，并且在运行 Docker 命令时遇到权限错误，您可能需要在命令前加上 sudo 或将您的用户添加到 docker 组。Docker 官方文档提供了关于如何在非 root 用户下运行 Docker 的说明。

要运行特定版本的 Grafana，请在命令中添加版本号部分

docker run -d -p 3000:3000 --name grafana grafana/grafana-enterprise:<version number>

示例

以下命令运行 Grafana Enterprise 容器并指定版本 9.4.7。如果您想运行其他版本，请修改版本号部分。

docker run -d -p 3000:3000 --name grafana grafana/grafana-enterprise:9.4.7

运行 Grafana 主分支

主分支的每次成功构建后，会更新两个标签：grafana/grafana-oss:main 和 grafana/grafana-oss:main-ubuntu。此外，还会创建两个新标签：grafana/grafana-oss-dev:<version><build ID>-pre 和 grafana/grafana-oss-dev:<version><build ID>-pre-ubuntu，其中 version 是 Grafana 的下一个版本，build ID 是相应的 CI 构建 ID。这些标签提供了访问最新 Grafana 主分支构建的途径。有关更多信息，请参阅 grafana/grafana-oss-dev。

为确保稳定性和一致性，强烈建议在生产环境中运行 Grafana 主分支时使用 grafana/grafana-oss-dev:<version><build ID>-pre 标签。此标签可确保您使用的是 Grafana 的特定版本，而不是最新的提交，因为最新的提交可能会引入 Bug 或问题。它还可以避免用数千个预发布标签污染主 Grafana 镜像的标签命名空间。

有关可用标签列表，请参阅 grafana/grafana-oss 和 grafana/grafana-oss-dev。

默认路径

Grafana 附带默认配置参数，这些参数在不同版本之间保持不变，无论操作系统或环境（例如，虚拟机、Docker、Kubernetes 等）如何。您可以参阅配置 Grafana 文档查看所有默认配置设置。

启动 Grafana Docker 容器时，默认设置以下配置。在 Docker 中运行时，您不能通过编辑 conf/grafana.ini 文件来更改配置。相反，您可以使用环境变量修改配置。

设置	默认值
GF_PATHS_CONFIG	/etc/grafana/grafana.ini
GF_PATHS_DATA	/var/lib/grafana
GF_PATHS_HOME	/usr/share/grafana
GF_PATHS_LOGS	/var/log/grafana
GF_PATHS_PLUGINS	/var/lib/grafana/plugins
GF_PATHS_PROVISIONING	/etc/grafana/provisioning

在 Docker 容器中安装插件

您可以安装公开可用的插件以及组织内部使用或私有的插件。有关插件安装说明，请参阅在 Docker 容器中安装插件。

从其他来源安装插件

要从其他来源安装插件，必须定义自定义 URL 并在 GF_PLUGINS_PREINSTALL 环境变量中紧接在插件名称之前指定它：GF_PLUGINS_PREINSTALL=<plugin ID>@[<plugin version>]@<url to plugin zip>。

示例

以下命令以分离模式在端口 3000 上运行 Grafana Enterprise，并安装自定义插件，该插件在 GF_PLUGINS_PREINSTALL 环境变量中以 URL 参数指定。

docker run -d -p 3000:3000 --name=grafana \
  -e "GF_PLUGINS_PREINSTALL=custom-plugin@@http://plugin-domain.com/my-custom-plugin.zip,grafana-clock-panel" \
  grafana/grafana-enterprise

构建自定义 Grafana Docker 镜像

在 Grafana GitHub 仓库中，packaging/docker/custom/ 文件夹包含一个可用于构建自定义 Grafana 镜像的 Dockerfile。此 Dockerfile 接受 GRAFANA_VERSION、GF_INSTALL_PLUGINS 和 GF_INSTALL_IMAGE_RENDERER_PLUGIN 作为构建参数。

GRAFANA_VERSION 构建参数必须是有效的 grafana/grafana Docker 镜像标签。默认情况下，Grafana 构建基于 Alpine 的镜像。要构建基于 Ubuntu 的镜像，请在 GRAFANA_VERSION 构建参数后附加 -ubuntu。

示例

以下示例展示了如何构建并运行基于最新官方 Ubuntu 版 Grafana Docker 镜像的自定义 Grafana Docker 镜像

# go to the custom directory
cd packaging/docker/custom

# run the docker build command to build the image
docker build \
  --build-arg "GRAFANA_VERSION=latest-ubuntu" \
  -t grafana-custom .

# run the custom grafana container using docker run command
docker run -d -p 3000:3000 --name=grafana grafana-custom

预安装 Image Renderer 插件构建 Grafana

注意：此功能为实验性功能。

目前，Grafana Image Renderer 插件需要一些 Grafana Docker 镜像中不提供的依赖项（详情请参阅 GitHub Issue#301）。然而，您可以使用 GF_INSTALL_IMAGE_RENDERER_PLUGIN 构建参数作为解决方案来创建定制的 Docker 镜像。这将安装 Grafana Image Renderer 插件运行所需的依赖项。

示例

以下示例展示了如何构建一个包含 Image Renderer 插件的定制 Grafana Docker 镜像。

# go to the folder
cd packaging/docker/custom

# running the build command
docker build \
  --build-arg "GRAFANA_VERSION=latest" \
  --build-arg "GF_INSTALL_IMAGE_RENDERER_PLUGIN=true" \
  -t grafana-custom .

# running the docker run command
docker run -d -p 3000:3000 --name=grafana grafana-custom

构建预安装插件的 Grafana Docker 镜像

如果您运行多个 Grafana 实例且使用相同的插件，您可以通过构建一个包含 Grafana 插件下载页面上可用插件的定制镜像来节省时间。构建定制镜像后，Grafana 启动时无需每次都安装插件，从而提高启动效率。

注意：要指定插件版本，您可以使用 GF_INSTALL_PLUGINS 构建参数并添加版本号。如果您未指定版本号，将使用最新版本。例如，您可以使用 --build-arg "GF_INSTALL_PLUGINS=grafana-clock-panel 1.0.1,grafana-simple-json-datasource 1.3.5" 来指定两个插件的版本。

示例

以下示例展示了如何构建并运行一个预安装插件的自定义 Grafana Docker 镜像。

# go to the custom directory
cd packaging/docker/custom

# running the build command
# include the plugins you want e.g. clock planel etc
docker build \
  --build-arg "GRAFANA_VERSION=latest" \
  --build-arg "GF_INSTALL_PLUGINS=grafana-clock-panel,grafana-simple-json-datasource" \
  -t grafana-custom .

# running the custom Grafana container using the docker run command
docker run -d -p 3000:3000 --name=grafana grafana-custom

构建从其他来源预安装插件的 Grafana Docker 镜像

您可以创建一个包含组织专属插件（即使该插件未公开可用）的 Docker 镜像。只需使用 GF_INSTALL_PLUGINS 构建参数指定插件的 URL 和安装文件夹名称，例如 GF_INSTALL_PLUGINS=<url to plugin zip>;<plugin install folder name>。

以下示例演示了如何创建一个定制的 Grafana Docker 镜像，其中包含一个来自 URL 链接的自定义插件、时钟面板插件和 simple-json-datasource 插件。您可以使用 Grafana 插件环境变量在构建参数中定义这些插件。

# go to the folder
cd packaging/docker/custom

# running the build command
docker build \
  --build-arg "GRAFANA_VERSION=latest" \
  --build-arg "GF_INSTALL_PLUGINS=http://plugin-domain.com/my-custom-plugin.zip;my-custom-plugin,grafana-clock-panel,grafana-simple-json-datasource" \
  -t grafana-custom .

# running the docker run command
docker run -d -p 3000:3000 --name=grafana grafana-custom

日志记录

默认情况下，Docker 容器日志会输出到 STDOUT，这是 Docker 社区的常见做法。您可以通过设置不同的日志模式（例如 console、file 或 syslog）来更改此行为。您可以使用空格分隔的方式指定一个或多个模式，例如 console file。默认情况下，同时启用 console 和 file 模式。

示例

以下示例使用 GF_LOG_MODE 环境变量中设置的 console file 日志模式运行 Grafana。

# Run Grafana while logging to both standard out
# and /var/log/grafana/grafana.log

docker run -p 3000:3000 -e "GF_LOG_MODE=console file" grafana/grafana-enterprise

使用 Docker Secrets 配置 Grafana

您可以使用配置文件将登录凭据和秘密等机密数据输入到 Grafana 中。此方法与 Docker Secrets 配合良好，因为秘密会自动映射到容器内的 /run/secrets/ 位置。

您可以将此技术应用于 conf/grafana.ini 中的任何配置选项，方法是将 GF_<SectionName>_<KeyName>__FILE 设置为包含秘密信息的文件路径。有关 Docker secret 命令用法的更多信息，请参阅 docker secret。

以下示例演示了如何设置管理员密码

管理员密码秘密: /run/secrets/admin_password
环境变量: GF_SECURITY_ADMIN_PASSWORD__FILE=/run/secrets/admin_password

为 AWS CloudWatch 配置 Docker secrets 凭据

Grafana 内置支持 Amazon CloudWatch 数据源。要配置该数据源，您必须提供 AWS ID-Key、秘密访问密钥、区域等信息。您可以使用 Docker secrets 作为提供这些信息的一种方式。

示例

以下示例展示了如何通过 Docker Secrets 使用 Grafana 环境变量来设置 AWS ID-Key、秘密访问密钥、区域和配置文件。

本示例使用以下值配置 AWS Cloudwatch 数据源

AWS_default_ACCESS_KEY_ID=aws01us02
AWS_default_SECRET_ACCESS_KEY=topsecret9b78c6
AWS_default_REGION=us-east-1

为上面提到的每个值创建一个 Docker secret。

echo "aws01us02" | docker secret create aws_access_key_id -

echo "topsecret9b78c6" | docker secret create aws_secret_access_key -

echo "us-east-1" | docker secret create aws_region -

运行以下命令以确认秘密已创建。

$ docker secret ls

命令的输出应该类似于以下内容

ID                          NAME           DRIVER    CREATED              UPDATED
i4g62kyuy80lnti5d05oqzgwh   aws_access_key_id             5 minutes ago        5 minutes ago
uegit5plcwodp57fxbqbnke7h   aws_secret_access_key         3 minutes ago        3 minutes ago
fxbqbnke7hplcwodp57fuegit   aws_region                    About a minute ago   About a minute ago

其中

ID = 将在 docker run 命令中使用的秘密唯一 ID

NAME = 为每个秘密定义的逻辑名称

运行 Docker 时，将秘密添加到命令行中。

docker run -d -p 3000:3000 --name grafana \
  -e "GF_DEFAULT_INSTANCE_NAME=my-grafana" \
  -e "GF_AWS_PROFILES=default" \
  -e "GF_AWS_default_ACCESS_KEY_ID__FILE=/run/secrets/aws_access_key_id" \
  -e "GF_AWS_default_SECRET_ACCESS_KEY__FILE=/run/secrets/aws_secret_access_key" \
  -e "GF_AWS_default_REGION__FILE=/run/secrets/aws_region" \
  -v grafana-data:/var/lib/grafana \
  grafana/grafana-enterprise

您还可以为 GF_AWS_PROFILES 指定多个配置文件（例如，GF_AWS_PROFILES=default another）。

以下列表包含支持的环境变量

GF_AWS_${profile}_ACCESS_KEY_ID: AWS 访问密钥 ID（必需）。
GF_AWS_${profile}_SECRET_ACCESS_KEY: AWS 秘密访问密钥（必需）。
GF_AWS_${profile}_REGION: AWS 区域（可选）。

排除 Docker 部署故障

默认情况下，Grafana 日志级别设置为 INFO，但当您想重现问题时，可以将日志级别提高到 DEBUG 模式。

有关日志记录的更多信息，请参阅日志。

使用 Docker run (CLI) 命令提高日志级别

要将日志级别提高到 DEBUG 模式，请在命令行中添加环境变量 GF_LOG_LEVEL。

docker run -d -p 3000:3000 --name=grafana \
  -e "GF_LOG_LEVEL=debug" \
  grafana/grafana-enterprise

使用 Docker Compose 提高日志级别

要将日志级别提高到 DEBUG 模式，请将环境变量 GF_LOG_LEVEL 添加到 docker-compose.yaml 文件中。

version: '3.8'
services:
  grafana:
    image: grafana/grafana-enterprise
    container_name: grafana
    restart: unless-stopped
    environment:
      # increases the log level from info to debug
      - GF_LOG_LEVEL=debug
    ports:
      - '3000:3000'
    volumes:
      - 'grafana_storage:/var/lib/grafana'
volumes:
  grafana_storage: {}

验证 Docker Compose YAML 文件

YAML 文件越复杂，出现语法错误的几率就越大。您可以使用以下命令检查语法错误。

# go to your docker-compose.yaml directory
cd /path-to/docker-compose/file

# run the validation command
docker compose config

如果 YAML 文件中存在错误，命令输出会突出显示包含错误的行。如果 YAML 文件中没有错误，输出将以详细的 YAML 格式包含 docker-compose.yaml 文件的内容。

此页面是否有帮助？

在 GitHub 中建议编辑

创建 GitHub Issue

发送邮件至 docs@grafana.com

帮助与支持

社区