Grafana文档本地测试镜像

镜像概述

Grafana文档本地测试镜像是一款用于在本地环境中测试Grafana文档网站的Docker镜像。其核心用途是帮助开发者、文档贡献者及技术编写者在本地快速搭建与线上环境一致的文档预览环境，实现在修改文档内容后实时预览效果、验证文档格式及功能，无需依赖远程服务器或线上资源。

核心功能与特性

1. 本地环境快速部署：无需手动配置文档网站依赖（如Node.js、 Hugo等），通过Docker一键启动完整文档预览环境。
2. 文档实时预览：支持文档内容修改后自动刷新预览页面，提升开发效率。
3. 与Grafana文档源文件兼容：无缝对接Grafana官方文档仓库（如grafana/grafana-docs）的目录结构及构建规则。
4. 轻量级运行：基于Alpine或精简基础镜像构建，资源占用低，适合本地开发环境。
5. 多版本文档支持：可通过配置指定文档版本，支持同时测试不同版本的文档内容。

使用场景与适用范围

适用人群

• Grafana文档贡献者（需验证文档修改效果）
• 技术文档编写者（编写Grafana相关教程/指南）
• 前端开发者（优化文档网站UI/UX或交互逻辑）

典型场景

• 本地修改Grafana文档内容后，实时预览渲染效果；
• 测试新功能文档的格式、链接有效性及兼容性；
• 在无网络环境下开发或修改文档；
• 验证文档网站在不同版本（如v9.x、v10.x）下的展示差异。

使用方法与配置说明

获取镜像

通过Docker Hub或私有仓库拉取镜像（假设镜像名称为grafana/docs-test）：

docker pull grafana/docs-test:latest

基本使用步骤

1. 准备本地文档源文件：克隆Grafana文档仓库至本地（如~/projects/grafana-docs）；
2. 启动容器：通过docker run或docker-compose启动镜像，挂载本地文档目录并映射端口；
3. 访问预览页面：通过浏览器访问本地服务地址，实时预览文档内容。

配置参数说明

端口映射

• 默认端口：容器内文档服务默认监听3000端口，需通过-p参数映射至宿主机端口（如8080:3000）。

目录挂载

• 文档源目录：需将本地Grafana文档仓库目录挂载至容器内/app/docs路径，实现文档内容的实时同步。
  • 本地目录示例：~/projects/grafana-docs（需包含content/、config/等文档核心目录）。

环境变量

访问与预览

容器启动后，通过宿主机映射的端口访问文档预览页面：

• 默认地址：http://localhost:<宿主机映射端口>（如http://localhost:8080）；
• 页面功能：支持导航菜单、搜索、版本切换（若配置DOCS_VERSION）及内容实时刷新。

Docker部署示例

docker run命令示例

基础用法（挂载本地文档目录并映射端口）：

docker run -d \
  --name grafana-docs-test \
  -p 8080:3000 \
  -v ~/projects/grafana-docs:/app/docs \
  -e LIVE_RELOAD_ENABLED=true \
  -e DOCS_VERSION=v10.2 \
  grafana/docs-test:latest

• 参数说明：
  • -d：后台运行容器；
  • --name：指定容器名称；
  • -p 8080:3000：将宿主机8080端口映射至容器3000端口；
  • -v ~/projects/grafana-docs:/app/docs：挂载本地文档目录至容器内文档路径；
  • -e：设置环境变量（启用热重载、指定文档版本）。

docker-compose配置示例

创建docker-compose.yml文件，配置如下：

version: '3'
services:
  grafana-docs:
    image: grafana/docs-test:latest
    container_name: grafana-docs-test
    ports:
      - "8080:3000"  # 宿主机端口:容器端口
    volumes:
      - ./grafana-docs:/app/docs  # 本地文档目录（相对路径）挂载
    environment:
      - DOCS_VERSION=v10.2
      - LIVE_RELOAD_ENABLED=true
      - PREVIEW_THEME=dark
    restart: unless-stopped  # 容器退出时自动重启（除非手动停止）

启动命令：

docker-compose up -d

注意事项

1. 文档目录结构：本地挂载的文档目录需符合Grafana文档仓库标准结构（包含content/、themes/、config.toml等核心文件），否则可能导致预览异常。
2. 资源占用：文档构建过程（首次启动或修改配置时）可能占用较高CPU/内存，建议根据宿主机配置调整MAX_MEMORY_LIMIT。
3. 版本兼容性：不同版本的镜像可能对应不同版本的Grafana文档构建工具，建议通过DOCS_VERSION环境变量匹配文档版本与镜像版本。