balenalib/raspberrypi4-64-ubuntu-node 镜像文档

镜像概述和主要用途

该镜像属于balena.io IoT设备基础镜像系列，专为物联网场景优化，适用于balenaOS平台和各类Docker环境。它内置Node.js运行时，提供精简高效的运行环境，支持在树莓派4等64位ARM设备上构建和部署Node.js应用。镜像同时兼容balena.io开发 workflow 和标准Docker环境，是物联网应用开发的理想基础。

核心功能和特性

便捷的包管理工具

• install_packages脚本：抽象底层包管理器差异，自动选择最小依赖安装方式（忽略可选依赖），安装后清理包管理器元数据，并支持安装失败自动重试，简化依赖管理流程。

动态设备支持

• 默认ENTRYPOINT：镜像默认入口点为/usr/bin/entry.sh，通过UDEV环境变量控制udevd服务：
  • 设置ENV UDEV=1时，自动启动udevd守护进程，使容器内/dev目录能动态识别外部插入设备，适用于需要访问传感器、USB设备等外设的IoT场景。

镜像变体

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

• 精简版镜像，仅包含运行时必需组件，体积小巧，适合生产环境部署。

:<version>-build

• 包含完整构建工具链的扩展版本，预安装源码编译所需工具，减少Dockerfile中手动安装依赖的步骤，降低整体镜像构建复杂度。

使用场景和适用范围

• IoT设备Node.js应用开发：为树莓派4等64位ARM设备提供Node.js运行环境，支持实时数据处理、设备通信等物联网场景。
• balena平台集成：无缝对接balena.io开发和部署流程，支持OTA更新、远程管理等balenaOS特性。
• 动态外设接入：适用于需要频繁插拔外设（如USB设备、传感器）的场景，通过udevd实现设备节点自动识别。
• 多阶段构建：结合-build变体进行源码编译，再使用-run变体运行，优化最终镜像体积。

使用方法和配置说明

基础使用：创建Dockerfile

在Node.js项目中创建Dockerfile：

dockerfile
# 指定基础镜像版本，如latest或具体版本号
FROM balenalib/raspberrypi4-64-ubuntu-node:latest

# 暴露应用端口（根据实际需求修改）
EXPOSE 8080

# 设置工作目录
WORKDIR /app

# 复制应用代码并安装依赖
COPY package*.json ./
RUN npm install

COPY . .

# 启动命令
CMD ["node", "server.js"]

构建并运行镜像：

console
$ docker build -t my-iot-app .
$ docker run -d --name my-running-app -p 8080:8080 my-iot-app

使用Docker Compose

创建docker-compose.yml：

yaml
version: "2"
services:
  node-app:
    image: "balenalib/raspberrypi4-64-ubuntu-node:latest"
    user: "node"
    working_dir: /home/node/app
    environment:
      - NODE_ENV=production
      - UDEV=1  # 启用udevd支持动态设备
    volumes:
      - ./:/home/node/app
    ports:
      - "8080:8080"
    command: "npm start"

启动服务：

console
$ docker-compose up -d

运行单个Node.js脚本

无需完整Dockerfile，直接运行脚本：

console
$ docker run -it --rm \
  -v "$PWD":/usr/src/app \
  -w /usr/src/app \
  balenalib/raspberrypi4-64-ubuntu-node:latest \
  node your-script.js

动态设备支持配置

如需启用外设自动识别，在Dockerfile或运行时设置UDEV=1：

dockerfile
# 在Dockerfile中设置
ENV UDEV=1

或运行时指定环境变量：

console
$ docker run -e UDEV=1 ...

支持的版本及文档链接

已支持Node.js版本

• 18.7.0（latest）
• 16.17.0
• 14.20.0
• 12.22.12

相关文档链接

• 镜像构建文件
• ***镜像清单
• balena基础镜像特性

用户反馈

提交问题

如遇镜像使用问题，可通过GitHub Issues提交。

贡献代码

欢迎提交PR贡献新功能或修复，建议先通过GitHub Issue讨论方案，确保符合项目方向。