hashicorp/consul-docs-builder

概述

hashicorp/consul-docs-builder 是用于构建 Consul 文档网站的专用 Docker 镜像。该镜像集成了 Consul 文档构建所需的全套工具链（基于 Hugo 静态站点生成器），支持文档源文件编译、本地预览及静态资源生成，旨在简化 Consul 文档的开发、测试与部署流程。

核心功能与特性

• 文档构建：支持将 Markdown 格式的文档源文件编译为可直接部署的静态 HTML 资源。
• 本地预览：内置开发服务器，支持热重载（Hot Reload），可实时预览文档修改效果。
• 依赖管理：自动安装 Hugo 及 Consul 文档专用主题、插件等依赖，无需手动配置环境。
• 多版本支持：可指定文档版本，构建不同版本的 Consul 文档（如 1.15.x、1.16.x）。
• 标准化输出：生成符合 Consul ***文档规范的静态文件结构，兼容主流部署平台（如 Netlify、AWS S3）。

使用场景与适用范围

• 文档开发：开发人员本地修改文档后，通过镜像快速预览效果，验证格式与内容正确性。
• CI/CD 集成：在持续集成流程中自动构建文档，确保代码提交后文档同步更新。
• 静态资源生成：生成静态 HTML 文件，用于部署至 CDN 或静态站点托管服务（如 GitHub Pages）。
• 多环境一致性：统一开发、测试、生产环境的文档构建工具版本，避免环境差异导致的构建问题。

使用方法

前置条件

• 已安装 Docker Engine（20.10+）或 Docker Desktop。
• 本地已克隆 Consul 文档源文件（通常位于 consul 仓库的 website 目录）。

docker run 命令示例

1. 本地预览文档（开发模式）

挂载本地文档源目录，启动开发服务器并映射端口至本地，实时预览修改：

bash
docker run -it --rm \
  -v /path/to/local/consul/website:/docs/source \  # 挂载本地文档源目录
  -p 1313:1313 \                                   # 映射开发服务器端口（默认 1313）
  -e DOCS_VERSION=1.17.x \                         # 指定构建的文档版本
  hashicorp/consul-docs-builder \
  hugo server --bind 0.0.0.0 --source /docs/source  # 启动 Hugo 开发服务器

执行后，访问 http://localhost:1313 即可预览文档，修改本地源文件后页面将自动刷新。

2. 构建静态文件（生产模式）

生成静态 HTML 文件并输出到本地目录，用于部署：

bash
docker run -it --rm \
  -v /path/to/local/consul/website:/docs/source \    # 挂载源文件目录
  -v /path/to/output:/docs/output \                  # 挂载输出目录（静态文件将生成至此）
  -e OUTPUT_DIR=/docs/output \                       # 指定容器内输出路径（需与挂载路径一致）
  -e DOCS_VERSION=latest \                           # 构建 "latest" 版本文档
  hashicorp/consul-docs-builder \
  hugo --source /docs/source --destination ${OUTPUT_DIR}  # 执行构建命令

构建完成后，静态文件将生成至本地 /path/to/output 目录。

docker-compose 配置示例

创建 docker-compose.yml，简化本地开发环境启动：

yaml
version: '3.8'

services:
  consul-docs:
    image: hashicorp/consul-docs-builder
    volumes:
      - ./consul/website:/docs/source  # 本地文档源目录（需替换为实际路径）
      - ./docs-output:/docs/output     # 静态文件输出目录（可选）
    ports:
      - "1313:1313"                    # 开发服务器端口映射
    environment:
      - DOCS_VERSION=1.17.x            # 文档版本
      - PORT=1313                      # 开发服务器端口（默认 1313）
    command: hugo server --bind 0.0.0.0 --source /docs/source  # 启动开发模式

启动命令：

bash
docker-compose up

配置参数与环境变量

注意事项

1. 目录权限：挂载本地目录时，确保宿主目录有读写权限，避免容器内权限不足导致构建失败（可通过 --user $(id -u):$(id -g) 调整容器用户）。
2. 依赖缓存：首次启动时会下载 Hugo 主题及依赖，建议将 node_modules 或 Hugo 缓存目录挂载至本地，加速后续构建。
3. 版本兼容性：不同版本的 consul-docs-builder 可能对应不同的 Hugo 版本，需与本地文档源的 Hugo 版本匹配（参考 Consul 文档仓库的 netlify.toml 或 hugo.toml 配置）。
4. 生产模式优化：生产构建时建议设置 HUGO_ENV=production，Hugo 将自动压缩静态资源（CSS/JS/HTML）以减小文件体积。