jaegertracing/protobuf-builder 镜像文档

概述

jaegertracing/protobuf-builder 是 Jaeger 项目官方提供的 Protobuf 构建工具镜像，集成了 Protobuf 编译器（protoc）、语言特定代码生成器（如 protoc-gen-go）及 Jaeger 项目专用的 Protobuf 定义文件（如 jaeger_idl）。该镜像旨在简化 Jaeger 项目及兼容项目中 Protobuf 文件的编译流程，确保构建环境一致性。

核心功能与特性

核心功能

1. Protobuf 编译：内置 protoc 编译器，支持将 .proto 文件编译为多种编程语言代码（Go、Java、Python 等）。
2. Jaeger 定义集成：预装 Jaeger 项目标准 Protobuf 定义（如追踪数据模型、服务协议等），无需手动下载。
3. 多语言生成：集成主流代码生成器（protoc-gen-go、protoc-gen-grpc-java 等），支持一键生成 gRPC 服务代码。

特性

• 环境一致性：统一的构建环境，避免因本地工具版本差异导致的编译错误。
• 轻量级：基于 Alpine 或 Golang 基础镜像构建，体积较小（~300MB）。
• 可扩展：支持通过挂载自定义 Protobuf 文件或生成器扩展功能。

使用场景与适用范围

• Jaeger 项目开发：Jaeger 核心组件（如 jaeger-collector、jaeger-query）构建过程中编译 Protobuf 文件。
• Jaeger 扩展开发：开发基于 Jaeger 数据模型的自定义组件（如第三方存储适配器、追踪分析工具）时，编译兼容的 Protobuf 代码。
• Protobuf 定义验证：验证自定义 .proto 文件与 Jaeger 标准定义的兼容性。

使用方法与配置说明

前提条件

• 已安装 Docker（20.10+ 版本）。
• 本地需准备待编译的 .proto 文件（或依赖 Jaeger 预装定义）。

镜像拉取

从 Docker Hub 拉取最新版本镜像：

docker pull jaegertracing/protobuf-builder:latest

指定版本（如 1.55.0，对应 Protobuf 编译器版本）：

docker pull jaegertracing/protobuf-builder:1.55.0

基本使用

1. 编译本地 Protobuf 文件

将本地目录（含 .proto 文件）挂载到容器，执行编译命令。示例：生成 Go 代码至本地 ./gen/go 目录：

docker run --rm -v $(pwd):/workspace jaegertracing/protobuf-builder \
  protoc \
    --proto_path=/workspace \                   # 指定 .proto 文件目录（本地挂载目录）
    --proto_path=/usr/local/jaeger-idl \        # Jaeger 预装 Protobuf 定义路径
    --go_out=/workspace/gen/go \                # 输出 Go 代码至本地 ./gen/go
    --go_opt=paths=source_relative \            # Go 代码生成选项（相对路径）
    /workspace/path/to/your/file.proto          # 待编译的 .proto 文件路径

2. 使用 Jaeger 预装 Protobuf 定义

直接引用容器内预装的 Jaeger Protobuf 文件（如 jaeger_api_v2.proto）进行编译：

docker run --rm -v $(pwd):/workspace jaegertracing/protobuf-builder \
  protoc \
    --proto_path=/usr/local/jaeger-idl \        # Jaeger 定义路径
    --go_out=/workspace/gen/go \
    /usr/local/jaeger-idl/jaeger/api/v2/jaeger_api_v2.proto  # 编译 Jaeger 官方 .proto 文件

环境变量

镜像支持通过环境变量自定义编译行为，常用变量如下：

Docker Compose 配置

通过 docker-compose.yml 定义构建任务，适用于多文件批量编译场景：

version: '3.8'
services:
  protobuf-builder:
    image: jaegertracing/protobuf-builder:latest
    volumes:
      - ./proto:/workspace/proto          # 本地 Protobuf 文件目录
      - ./gen:/workspace/gen              # 输出代码目录（本地挂载）
    environment:
      - JAEGER_PROTOBUF_DIR=/usr/local/jaeger-idl
      - OUTPUT_LANG=go
    command: >
      protoc 
        --proto_path=/workspace/proto 
        --proto_path=${JAEGER_PROTOBUF_DIR} 
        --go_out=/workspace/gen 
        --go_opt=paths=source_relative 
        /workspace/proto/*.proto

启动命令：

docker-compose up

注意事项

1. 文件权限：挂载本地目录时，容器内用户（通常为 root）可能生成 root 权限文件，建议通过 --user $(id -u):$(id -g) 调整权限：

   docker run --rm -v $(pwd):/workspace --user $(id -u):$(id -g) jaegertracing/protobuf-builder ...
   

2. 版本兼容性：不同镜像标签对应不同 Protobuf 版本，需与项目依赖的 Protobuf 版本匹配（如 Jaeger v1.48+ 推荐使用镜像标签 3.25.3）。
3. 自定义生成器：如需使用容器外的代码生成器，可通过 -v /path/to/local/plugin:/usr/local/bin/ 挂载至容器 $PATH 目录。

参考链接

• Jaeger Protobuf 定义源码
• Protobuf 官方文档
• Jaeger 构建指南