balenalib/beaglebone-black-debian-golang 镜像文档

镜像概述和主要用途

本镜像属于 balena.io 物联网设备基础镜像系列，专为物联网（IoT）设备开发设计。其针对 balena.io 平台和 balenaOS 进行了深度优化，同时也可在任何支持相应架构的 Docker 环境中运行。核心目标是为物联网设备上的 Go 语言应用提供精简、高效且功能完备的运行与构建环境。

核心功能和特性

install_packages 包管理工具

• 包管理器抽象：自动适配底层包管理系统（如 apt），无需手动指定具体包管理命令。
• 最小依赖安装：仅安装必要依赖，忽略可选组件，降低镜像体积。
• 自动清理机制：安装后自动清理包管理器元数据，进一步减小镜像大小。
• 失败重试逻辑：包安装失败时自动重试，提升构建流程稳定性。

UDEV 动态设备支持

• 镜像默认入口点（ENTRYPOINT）为 /usr/bin/entry.sh，可通过设置环境变量 UDEV=1（ENV UDEV=1）启用 udevd 守护进程。
• 启用后，容器内 /dev 目录将动态识别并显示接入的设备节点，支持外部设备的热插拔识别。

更多特性详情请参见 官方文档特性概述。

镜像变体

balenalib 镜像提供以下变体，满足不同开发阶段需求：

:<version> 或 :<version>-run

• 默认变体：精简最小化，仅包含运行时必需组件，适用于应用部署阶段。

:<version>-build

• 构建变体：集成完整的源码编译工具链，减少 Dockerfile 中手动安装的依赖包数量，从而降低系统中所有镜像的总体积。

变体差异详情请参见 官方文档：Run vs Build。

使用场景和适用范围

• 物联网 Go 应用开发：尤其适合基于 BeagleBone Black 等嵌入式设备的 Go 语言项目。
• 构建与运行分离：通过 build 变体完成源码编译，run 变体部署运行，实现多阶段构建优化。
• 动态设备接入：需在容器中识别动态插拔硬件（如传感器、USB 设备）的场景（依赖 UDEV 功能）。

支持的版本及 Dockerfile 链接

• 支持版本：1.19 (latest)、1.18.15、1.17.12
• Dockerfile 源码：GitHub 仓库

镜像历史及元数据信息请参见 官方镜像清单。

使用方法和配置说明

在 Balena 平台中使用

参考 快速入门指南 开始使用，或查看 示例项目 了解实际应用案例。

在通用 Docker 环境中使用

1. 通过 Dockerfile 构建并运行应用

以下示例使用 run 变体构建并运行 Go 应用：

FROM balenalib/beaglebone-black-debian-golang:latest

WORKDIR /go/src/app
COPY . .

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

# 启动应用
CMD ["app"]

构建并运行：

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

2. 在容器内编译应用（仅编译不运行）

如需在容器内编译源码但不在容器中运行，可执行以下命令：

$ docker run --rm -v "$PWD":/usr/src/myapp -w /usr/src/myapp balenalib/beaglebone-black-debian-golang:latest go build -v

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

配置参数

用户反馈

问题反馈

如遇功能异常或使用疑问，请通过 GitHub Issues 提交反馈。

贡献指南

欢迎提交新功能、错误修复或文档更新。重大变更建议先通过 GitHub Issues 讨论，以确保与项目方向一致。

官方文档

更多详情请参见 balena 基础镜像文档 及 新基础镜像特性介绍。