balenalib/raspberrypi3-debian-python 镜像文档

1. 镜像概述和主要用途

本镜像属于 balena.io 物联网设备基础镜像系列，专为 IoT 设备优化设计。其核心用途是作为树莓派3等ARM架构设备的Python运行环境基础，默认适配 balena.io 平台及 balenaOS 操作系统，同时也可用于其他支持相应架构的Docker环境。

2. 核心功能和特性

2.1 简化的包管理工具 install_packages

• 功能：抽象底层包管理器（如apt）的差异，统一包安装流程。
• 特性：
  • 仅安装必要依赖（忽略可选依赖），最小化镜像体积；
  • 自动清理包管理器元数据，减少冗余文件；
  • 支持安装失败时自动重试，提升稳定性。

2.2 动态设备支持（UDEV集成）

• 默认入口点：ENTRYPOINT ["/usr/bin/entry.sh"]，负责初始化设备支持。
• UDEV激活：通过设置环境变量 ENV UDEV=1 启用：
  • 自动启动 udevd 守护进程；
  • 容器内 /dev 目录将动态生成接入设备的节点文件，支持热插拔设备识别。

更多特性详情参见 balena基础镜像特性概述。

3. 镜像变体

3.1 :<version> 或 :<version>-run（默认变体）

• 定位：精简的运行时基础镜像，仅包含Python运行必需的核心组件。
• 适用场景：生产环境部署，追求最小化镜像体积和资源占用。

3.2 :<version>-build

• 定位：包含完整构建工具链的重型镜像，预置源码编译所需的依赖工具（如编译器、链接器等）。
• 优势：减少Dockerfile中手动安装工具的步骤，降低整体镜像构建链的复杂度和体积。

变体差异详情参见 运行时与构建时镜像对比。

4. 使用场景和适用范围

5. 使用方法和配置说明

5.1 与Balena平台配合使用

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

5.2 通用Docker环境使用

5.2.1 通过Dockerfile构建应用

1. 创建Dockerfile：

   FROM balenalib/raspberrypi3-debian-python:latest
   
   WORKDIR /usr/src/app
   
   # 安装依赖
   COPY requirements.txt ./
   RUN pip install --no-cache-dir -r requirements.txt
   
   # 复制应用代码
   COPY . .
   
   # 启动命令
   CMD [ "python", "./your-daemon-or-script.py" ]
   

2. 构建并运行：

   # 构建镜像
   docker build -t my-python-app .
   
   # 运行容器（交互式，退出时自动清理）
   docker run -it --rm --name my-running-app my-python-app
   

5.2.2 直接运行单个Python脚本

适用于简单单文件项目，无需编写Dockerfile：

docker run -it --rm --name my-running-script \
  -v "$PWD":/usr/src/myapp \  # 挂载当前目录到容器内
  -w /usr/src/myapp \         # 设置工作目录
  balenalib/raspberrypi3-debian-python:latest \
  python your-daemon-or-script.py  # 执行脚本

6. 配置参数说明

7. 支持的版本及Dockerfile链接

镜像历史及清单文件参见 raspberrypi3-debian-python官方镜像清单。

8. 用户反馈

8.1 问题反馈

如遇使用问题，请通过 GitHub Issues 提交。

8.2 贡献指南

欢迎提交功能改进、漏洞修复或文档更新：

1. 建议先通过 GitHub Issues 讨论方案；
2. 提交Pull Request，项目维护团队将优先处理。

更多基础镜像文档参见 balena基础镜像文档。