balenalib/raspberrypi3-alpine-node 镜像文档

镜像概述与主要用途

本镜像属于 balena.io 物联网（IoT）设备基础镜像系列，专为 IoT 设备优化设计。该镜像针对 balena.io 平台和 balenaOS 系统进行了深度适配，同时也可在其他支持相应架构的 Docker 环境中使用。

核心功能与特性

1. 简化的包管理工具 install_packages

• 功能：抽象底层包管理器差异，统一安装流程
• 特性：
  • 忽略可选依赖，最小化安装体积
  • 自动清理包管理器元数据，减少镜像大小
  • 安装失败时自动重试，提升可靠性

2. 动态设备支持

• 默认入口点：ENTRYPOINT ["/usr/bin/entry.sh"]
• udev 集成：通过设置环境变量 ENV UDEV=1 启用 udev 支持：
  • 自动启动 udevd 守护进程
  • 容器内 /dev 目录将动态生成关联的设备节点

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

使用场景与适用范围

适用场景

• IoT 设备的轻量级运行环境（依赖 run 变体）
• IoT 应用的源码构建环境（依赖 build 变体）
• 需要动态设备接入的容器化场景（如传感器、外设交互）

架构支持

• 针对树莓派 3（raspberrypi3）架构优化
• 基于 Alpine Linux，提供极小的基础镜像体积

镜像变体

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

• 定位：轻量级运行时镜像
• 特性：仅包含运行时必需组件，体积最小化
• 适用：生产环境部署、资源受限的 IoT 设备

:<version>-build

• 定位：构建环境镜像
• 特性：集成大量源码构建工具（如编译器、链接器等）
• 优势：减少手动安装依赖的需求，降低整体镜像体积

变体差异详情参见 run vs build 变体说明

支持的版本

使用方法与配置说明

1. 与 Balena 平台配合使用

• 入门指南：balena 基础镜像使用入门
• 示例项目：balena 示例项目库

2. 基础 Dockerfile 示例

dockerfile
# 指定基础镜像版本（推荐使用具体版本号替代 latest）
FROM balenalib/raspberrypi3-alpine-node:latest
# 暴露应用默认端口（根据实际需求修改）
EXPOSE 8888

构建与运行命令

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

# 运行容器（交互式、自动清理）
docker run -it --rm --name my-running-app my-nodejs-app

3. Docker Compose 配置示例

yaml
version: "2"
services:
  node:
    image: "balenalib/raspberrypi3-alpine-node:latest"
    user: "node"                  # 使用非 root 用户运行
    working_dir: /home/node/app   # 工作目录
    environment:
      - NODE_ENV=production       # 配置 Node 环境变量
    volumes:
      - ./:/home/node/app         # 挂载本地代码目录
    expose:
      - "8081"                    # 暴露内部端口
    command: "npm start"          # 启动命令

启动命令

bash
docker-compose up -d  # 后台运行服务

说明：此配置会将当前目录（含 node_modules）复制到容器，需确保项目根目录存在 package.json 且定义了 start 脚本。

4. 单 Node.js 脚本运行

对于简单项目，可直接运行单文件脚本：

bash
docker run -it --rm --name my-running-script \
  -v "$PWD":/usr/src/app \    # 挂载当前目录到容器
  -w /usr/src/app \           # 设置工作目录
  balenalib/raspberrypi3-alpine-node:latest \
  node your-daemon-or-script.js  # 运行脚本

环境变量配置

用户反馈

问题反馈

如遇镜像相关问题或疑问，请通过 GitHub Issues 提交。

贡献指南

欢迎贡献新功能、修复或更新。建议先通过 GitHub Issues 讨论方案，再提交 Pull Request。

扩展文档

• balena 基础镜像完整文档
• balena 基础镜像迁移指南

参考链接

• balena.io 官网
• balenaOS 系统