portainer/golang-builder

golang-builder

概述

golang-builder是一个容器化构建环境，用于编译Golang可执行包为静态链接的二进制文件。静态链接的二进制文件可在无其他依赖的容器中运行，因此能生成体积极小的镜像（基于0字节的scratch镜像，仅包含二进制文件）。相比官方golang镜像（未添加应用前已达500MB），该工具能显著减小最终镜像体积。其实现深受Xebia博客中《Create the Smallest Possible Docker Container》一文的启发。

核心功能与特性

• 静态链接二进制生成：将Golang源代码编译为自包含、静态链接的可执行文件，无外部依赖
• 最小Docker镜像：基于scratch镜像构建最终应用镜像，仅包含编译后的二进制文件，体积接近二进制文件本身
• 依赖管理支持：默认通过go get获取第三方依赖，也支持Godep工具管理的依赖（使用Godeps/_workspace目录）
• 自定义编译配置：通过环境变量调整编译参数（如CGO启用、链接器标志、二进制压缩等）
• 跨平台编译：提供portainer/golang-builder:cross-platform镜像，支持为不同操作系统和架构（Linux、OSX等）构建二进制文件

使用场景与适用范围

适用于需要构建轻量级Golang应用Docker镜像的场景，尤其适合对镜像体积有严格要求的生产环境。同时支持仅编译二进制文件（不生成Docker镜像）及跨平台编译需求，满足多架构/操作系统的部署场景。

使用方法与配置说明

项目要求

项目结构

工具默认假设"main"包（包含可执行命令的包）位于项目目录根目录。示例结构：

.
├─api
│ ├─api.go
│ └─api_test.go
├─greeting
│ ├─greeting.go
│ └─greeting_test.go
├─hello.go  // main包所在文件
└─hello_test.go

如需覆盖默认main包位置，可在运行时指定main包路径（需使用容器内挂载目录前缀，如/src）：

shell
docker run --rm \
  -v "$(pwd):/src" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  portainer/golang-builder /src/subfolder/main

规范导入路径

工具需要知道应用的全限定包名，可通过Go 1.4引入的规范导入路径注释指定。该注释需紧跟package子句：

go
package main // import "github.com/CenturyLink/hello"

工具会读取此注释，将源代码挂载到GOPATH的正确位置进行编译。

依赖管理

• 默认行为：自动go get导入的第三方包（项目内已包含的包除外）
• Godep支持：若使用Godep管理依赖，工具会优先使用Godeps/_workspace目录中的依赖，避免下载不同版本

Dockerfile

如需自动生成Docker镜像，项目根目录需包含Dockerfile。编译后的二进制文件会被放置在项目根目录，因此Dockerfile可假设二进制文件与自身同级：

dockerfile
FROM scratch
EXPOSE 3000
COPY hello /
ENTRYPOINT ["/hello"]

若项目根目录无Dockerfile，工具仅编译二进制文件，不生成镜像。

基本使用方法

编译并生成Docker镜像

工具需要：

• 挂载源代码目录到容器/src
• 挂载Docker socket（/var/run/docker.sock）以与Docker API交互生成镜像

假设当前位于项目根目录，运行命令：

shell
docker run --rm \
  -v "$(pwd):/src" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  portainer/golang-builder

生成的镜像默认标签为Go包名（如hello:latest）。

指定镜像标签

可在命令末尾添加自定义镜像标签：

shell
docker run --rm \
  -v "$(pwd):/src" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  portainer/golang-builder \
  centurylink/hello:1.0

仅编译二进制文件

不挂载Docker socket即可仅编译二进制文件（不生成镜像）：

shell
docker run --rm -v $(pwd):/src portainer/golang-builder

额外配置选项

通过环境变量自定义编译行为：

示例（启用CGO、自定义链接器标志、压缩二进制）：

shell
docker run --rm \
  -e CGO_ENABLED=true \
  -e LDFLAGS='-extldflags "-static"' \
  -e COMPRESS_BINARY=true \
  -e OUTPUT=/bin/my_go_binary \
  -v $(pwd):/src \
  portainer/golang-builder

跨平台编译

portainer/golang-builder:cross-platform镜像支持跨平台编译，默认生成Linux和OSX的32位及64位二进制文件（命名格式如mypackage-darwin-amd64）。可通过环境变量覆盖默认平台：

• BUILD_GOOS：指定目标操作系统（如"linux"、"darwin"）
• BUILD_GOARCH：指定目标架构（如"amd64"、"arm"）

示例（构建Linux的amd64和arm架构二进制）：

shell
docker run --rm \
  -e BUILD_GOOS="linux" \
  -e BUILD_GOARCH="arm amd64" \
  -v $(pwd):/src \
  portainer/golang-builder:cross-platform

SSL验证

使用scratch镜像时，应用可能因缺少根CA证书无法访问SSL端点，报错：x509: failed to load system roots and no roots provided。解决方案：

• 不推荐：禁用SSL验证
• 推荐：
  • 打包必要的根CA证书到应用中
  • 使用包含根CA证书的最小基础镜像，如https://registry.hub.docker.com/u/centurylink/ca-certs/%EF%BC%88%E4%BB%85258 kB，基于scratch添加常用根CA证书）