balenalib/npe-x500-m3-golang

balenalib/golang 镜像文档

1. 镜像概述和主要用途

该镜像属于 balena.io 物联网(IoT)设备基础镜像系列，专为 balena.io 平台和 balenaOS 系统优化，同时也适用于其他支持相应架构的 Docker 环境。其核心用途是为 IoT 设备上的 Go 语言应用提供轻量、高效的运行时和构建环境。

2. 核心功能和特性

2.1 包管理工具 install_packages

提供 install_packages 脚本，抽象底层包管理器差异，具备以下特性：

• 安装指定包时忽略可选依赖，最小化依赖体积
• 自动清理包管理器元数据，减少镜像大小
• 安装失败时自动重试，提升稳定性

2.2 动态设备支持

默认 ENTRYPOINT 为 /usr/bin/entry.sh，通过环境变量控制 udevd 守护进程：

• 设置 ENV UDEV=1 时，自动启动 udevd 服务
• 容器内 /dev 目录将动态生成关联设备节点，支持热插拔设备检测

2.3 镜像变体

提供两种主要变体，满足不同场景需求：

3. 使用场景和适用范围

• IoT 设备 Go 应用开发：在 balenaOS 或其他 Linux 系统上构建、测试和部署 Go 语言应用
• 轻量级运行时环境：使用 -run 变体部署生产环境应用，减少资源占用
• 源码构建优化：使用 -build 变体在容器内完成应用编译，简化构建流程
• 动态设备交互：需访问 IoT 设备硬件外设（如传感器、USB 设备）的场景

4. 使用方法和配置说明

4.1 基本使用（Dockerfile 示例）

通过 Dockerfile 构建并运行 Go 应用：

dockerfile
FROM docker.xuanyuan.run/balenalib/npe-x500-m3-debian-golang:latest

WORKDIR /go/src/app
COPY . .

# 安装依赖并编译应用
RUN go get -d -v ./...
RUN go install -v ./...

# 运行应用
CMD ["app"]

构建并运行镜像：

bash
$ docker build -t my-golang-app .
$ docker run -it --rm --name my-running-app my-golang-app

4.2 在容器内编译应用

仅编译应用（不运行），将编译产物输出到宿主机：

bash
$ docker run --rm -v "$PWD":/usr/src/myapp -w /usr/src/myapp \
  balenalib/npe-x500-m3-debian-golang:latest go build -v

• -v "$PWD":/usr/src/myapp：挂载当前目录到容器内编译路径
• -w /usr/src/myapp：设置工作目录为挂载路径
• go build -v：编译当前目录项目，输出可执行文件

4.3 与 Balena 平台配合使用

参考 https://www.balena.io/docs/learn/getting-started/npe-x500-m3/go/?ref=dockerhub 快速上手，或查看 https://www.balena.io/docs/learn/getting-started/npe-x500-m3/go/#example-projects?ref=dockerhub 了解实际应用场景。

5. 配置参数

6. 支持版本及 Dockerfile 链接

当前支持以下 Go 版本，对应 Dockerfile 源码可在 GitHub 查看：

• 1.12.9（latest）、1.11.13、1.10.8
  https://github.com/balena-io-library/base-images/tree/master/balena-base-images/golang/npe-x500-m3/debian/

7. 用户反馈

7.1 问题报告

如遇镜像使用问题，通过 https://github.com/balena-io-library/base-images/issues 提交反馈。

7.2 贡献指南

欢迎提交功能改进或修复，建议先通过 https://github.com/balena-io-library/base-images/issues 讨论方案，再提交 Pull Request。

更多特性详情参见 https://www.balena.io/docs/reference/base-images/base-images/#features-overview%E3%80%82
镜像变体差异说明：https://www.balena.io/docs/reference/base-images/base-images/#run-vs-build?ref=dockerhub%E3%80%82