balenalib/raspberry-pi2-ubuntu-python

balenalib/raspberry-pi2-ubuntu-python 镜像文档

镜像概述和主要用途

本镜像属于 balena.io 物联网（IoT）设备基础镜像系列，专为树莓派 Pi 2 平台设计，提供 Python 运行环境。该镜像针对 balena.io 平台和 balenaOS 进行了优化，可无缝集成到 balena 的设备管理和部署流程中，同时也兼容其他标准 Docker 环境。主要用途是为树莓派 Pi 2 上的 IoT 应用提供轻量、可靠的 Python 运行时和构建环境。

核心功能和特性

1. install_packages 包管理工具

• 功能：抽象底层包管理器（如 apt）的差异，简化依赖安装流程。
• 特性：
  • 自动选择最小依赖组合（忽略可选依赖），减少镜像体积；
  • 安装完成后自动清理包管理器元数据，进一步减小镜像大小；
  • 支持安装失败时自动重试，提升构建稳定性。
• 使用方式：在 Dockerfile 中直接调用 install_packages <package-name> 即可安装指定软件包。

2. 动态设备节点支持

• 机制：镜像默认入口点为 ENTRYPOINT ["/usr/bin/entry.sh"]，通过环境变量 UDEV 控制 udevd 守护进程的启动。
• 功能：当设置 ENV UDEV=1 时，入口脚本会启动 udevd 服务，使容器内 /dev 目录能够动态识别并创建宿主机接入的设备节点（如 USB 设备、传感器等），适用于需要直接访问硬件的 IoT 场景。

镜像变体

balenalib/raspberry-pi2-ubuntu-python 提供以下变体，满足不同使用场景需求：

:<version> 或 :<version>-run

• 定位：默认镜像，精简的运行时变体。
• 特性：仅包含 Python 运行所需的核心依赖，体积小巧，适合生产环境部署。
• 适用场景：直接运行已编译或打包的 Python 应用，无需构建过程。

:<version>-build

• 定位：构建环境变体。
• 特性：包含编译器、Make、Git 等源码构建工具，减少手动安装依赖的需求，降低整体镜像构建链的复杂度。
• 适用场景：从源码编译 Python 应用或依赖库（如 C 扩展模块），适合开发阶段或需要自定义构建的场景。

使用场景和适用范围

适用平台

• 硬件：树莓派 Pi 2（ARM 架构）。
• 系统：balenaOS 或其他支持 Docker 的 Linux 系统。

典型使用场景

1. IoT 应用运行时：使用 -run 变体部署轻量级 Python 应用（如传感器数据采集、设备控制逻辑）。
2. 源码构建环境：使用 -build 变体从源码构建 Python 项目，尤其是依赖原生扩展的场景（如 NumPy、Pillow 等）。
3. balena 生态集成：与 balena.io 平台配合，实现 IoT 设备的远程管理、应用部署和监控。

详细使用方法和配置说明

前提条件

• 已安装 Docker 环境（兼容 ARM 架构，如树莓派原生系统或交叉编译环境）。
• 若使用 balena 平台，需安装 balena CLI 并注册 balena 账号。

与 balena 平台配合使用

参考 balena 官方 快速入门指南 和 示例项目，可快速上手基于本镜像的 IoT 应用开发与部署。

基本使用方法

1. 通过 Dockerfile 构建应用镜像

创建 Dockerfile 定义应用环境：

dockerfile
# 使用最新版运行时变体
FROM balenalib/raspberry-pi2-ubuntu-python:latest

# 设置工作目录
WORKDIR /usr/src/app

# 复制依赖文件并安装
COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt

# 复制应用代码
COPY . .

# 启动应用
CMD ["python", "./your-application.py"]

构建并运行镜像：

bash
# 构建镜像
docker build -t my-python-iot-app .

# 运行容器（若需设备节点支持，添加 -e UDEV=1）
docker run -it --rm -e UDEV=1 --name my-app my-python-iot-app

2. 直接运行单个 Python 脚本

对于简单项目，可跳过 Dockerfile，直接挂载脚本文件运行：

bash
docker run -it --rm \
  -v "$PWD":/usr/src/myapp \  # 挂载当前目录到容器内
  -w /usr/src/myapp \         # 设置工作目录
  -e UDEV=1 \                 # 启用 udevd（如需设备访问）
  balenalib/raspberry-pi2-ubuntu-python:latest \
  python your-script.py       # 运行脚本

Docker Compose 部署示例

创建 docker-compose.yml 配置文件，适用于多服务应用：

yaml
version: '3'
services:
  python-app:
    image: balenalib/raspberry-pi2-ubuntu-python:3.10.7-run
    volumes:
      - ./app:/usr/src/app  # 挂载应用代码
    environment:
      - UDEV=1  # 启用设备节点动态识别
    command: python /usr/src/app/main.py

启动服务：

bash
docker-compose up -d

关键配置参数

环境变量

• UDEV：控制 udevd 守护进程启动。
  • 默认值：未设置（udevd 不启动）。
  • 设置为 1 时：启动 udevd，容器内 /dev 目录动态生成设备节点，适用于需要访问传感器、USB 设备等场景。

入口点（ENTRYPOINT）

• 默认入口点：/usr/bin/entry.sh。
  • 作用：负责初始化环境（如启动 udevd），之后执行用户定义的 CMD 或命令。
  • 如需自定义入口点，可在 Dockerfile 中使用 ENTRYPOINT 指令覆盖（不建议，可能影响 udevd 等功能）。

支持版本及 Dockerfile 链接

用户反馈

问题反馈

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

贡献代码

欢迎提交新功能、修复或更新（无论大小）。建议先通过 https://github.com/balena-io-library/base-images/issues 讨论计划，以确保与项目方向一致。

参考文档

• balena 基础镜像特性概述
• run 与 build 变体区别
• balena 基础镜像迁移指南