balenalib/raspberry-pi

balenalib/raspberry-pi-debian 镜像文档

概述和主要用途

本镜像为balena.io IoT设备基础镜像系列的一部分，专为树莓派设计，基于Debian系统。它针对balena.io平台和balenaOS进行了深度优化，提供适用于IoT设备开发的基础环境，同时也可在任何支持相应架构的Docker环境中使用。

核心功能和特性

便捷的包管理工具

• 内置install_packages脚本，抽象底层包管理器差异，统一包安装流程
• 特性：仅安装最小依赖（忽略可选依赖）、自动清理包管理器元数据、安装失败时支持重试机制

动态设备接入支持

• 默认入口点配置：ENTRYPOINT ["/usr/bin/entry.sh"]
• 动态设备检测：通过UDEV环境变量控制，设置ENV UDEV=1时自动启动udevd守护进程
• 设备节点管理：启用后，动态接入的设备节点将自动出现在容器的/dev目录下

更多特性详情可参考Balena基础镜像特性概述。

镜像变体

:<version> 或 :<version>-run

• 默认镜像变体，设计为精简的运行时环境
• 仅包含运行时必需组件，体积小巧，适合部署阶段使用

:<version>-build

• 构建环境专用变体，包含大量源码构建工具
• 减少Dockerfile中手动安装的依赖包数量，降低系统总体镜像体积

使用场景和适用范围

• 树莓派及类似IoT设备的应用开发与部署
• 基于balena.io平台的物联网项目开发
• 需要动态接入外部设备的嵌入式应用场景
• 同时支持开发构建（使用-build变体）和生产运行（使用-run变体）环境

使用方法和配置说明

创建Dockerfile

在项目中创建基础Dockerfile：

dockerfile
FROM balenalib/raspberry-pi-debian:latest
# 在此添加应用代码和配置

构建与运行镜像

console
# 构建镜像
$ docker build -t my-iot-app .

# 运行容器
$ docker run -it --rm --name my-running-app my-iot-app

启用动态设备接入

如需支持动态设备接入，需设置UDEV环境变量：

dockerfile
FROM balenalib/raspberry-pi-debian:latest
ENV UDEV=1
# 应用配置...

启动容器后，udevd将自动运行，外部设备接入时会在/dev目录下生成相应设备节点。

与Balena平台配合使用

快速入门

参考Balena的树莓派入门指南了解基础使用流程。

示例项目

可通过Balena的示例项目库获取实际应用参考。

支持的版本及Dockerfile链接

当前支持的主要版本：

• bullseye (latest)
• bookworm
• buster
• sid

Dockerfile源码位置：https://github.com/balena-io-library/base-images/tree/master/balena-base-images/device-base/raspberry-pi/debian/

官方镜像清单：https://github.com/balena-io-library/official-images/blob/master/library/raspberry-pi-debian

用户反馈

问题反馈

如遇使用问题或有疑问，请通过https://github.com/balena-io-library/base-images/issues%E6%8F%90%E4%BA%A4%E3%80%82

贡献指南

欢迎贡献代码或改进建议，建议先通过https://github.com/balena-io-library/base-images/issues%E8%AE%A8%E8%AE%BA%E8%AE%A1%E5%88%92%EF%BC%8C%E5%86%8D%E6%8F%90%E4%BA%A4PR%E3%80%82

相关文档

• 完整基础镜像文档：Balena基础镜像文档
• 新特性说明：Balena基础镜像更新日志