balenalib/raspberrypi0-2w-64-ubuntu-node

balenalib/raspberrypi0-2w-64-ubuntu-node 镜像文档

镜像概述和主要用途

本镜像属于balena.io IoT设备基础镜像系列，专为树莓派Zero 2W 64位平台设计，基于Ubuntu系统并集成Node.js运行环境。该镜像优化用于balena.io平台和balenaOS操作系统，同时也可在其他支持相应架构的Docker环境中使用。主要用于在树莓派Zero 2W 64位设备上开发、构建和运行Node.js IoT应用程序，提供简化的包管理和设备动态检测能力。

!balenalogo

核心功能和特性

简化的包管理

• 提供install_packages工具脚本，抽象底层包管理器差异，自动处理包安装：
  • 仅安装必要依赖（忽略可选依赖），最小化镜像体积
  • 自动清理包管理器元数据，减少冗余文件
  • 支持安装失败时自动重试，提高可靠性

动态设备检测支持

• 默认入口点为ENTRYPOINT ["/usr/bin/entry.sh"]，实现设备动态管理：
  • 通过设置环境变量ENV UDEV=1启用udev支持
  • 自动启动udevd守护进程，使容器内/dev目录能动态识别外部插入设备
  • 适用于需要与传感器、USB设备等外部硬件交互的IoT场景

Node.js环境集成

• 内置Node.js运行时，支持多种稳定版本（18.7.0、16.17.0、14.20.0、12.22.12等）
• 兼容标准Node.js应用开发流程，可直接部署使用npm管理的项目

镜像变体

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

• 精简的运行时变体，仅包含应用运行所需的核心组件
• 设计目标是最小化镜像体积，适合生产环境部署

:<version>-build

• 包含完整构建工具链的重型变体，适用于从源代码构建应用
• 预安装编译工具、头文件等，减少手动安装依赖步骤，间接降低整体镜像体积

更多变体详情请参考官方文档

使用场景和适用范围

• 树莓派Zero 2W 64位平台：专为该硬件优化，充分发挥设备性能
• IoT应用开发：尤其适合需要与外部硬件设备交互的场景（如传感器数据采集、智能家居控制）
• balena生态系统：无缝集成balena.io设备管理平台和balenaOS，支持远程部署和监控
• Node.js应用部署：可作为独立Docker环境中Node.js应用的基础镜像，简化开发到生产的流程

详细使用方法和配置说明

基本使用示例

创建Dockerfile

在Node.js项目中创建Dockerfile：

dockerfile
# 指定基础镜像，可替换为所需Node.js版本（如18.7.0、16.17.0等）
FROM balenalib/raspberrypi0-2w-64-ubuntu-node:latest
# 暴露应用默认端口（根据实际需求修改）
EXPOSE 8888
# 设置工作目录
WORKDIR /app
# 复制项目文件
COPY package*.json ./
# 安装依赖
RUN npm install
# 复制应用代码
COPY . .
# 启动命令
CMD ["npm", "start"]

构建并运行镜像

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

# 运行容器（启用udev支持）
$ docker run -it --rm --name my-running-app -e UDEV=1 -p 8888:8888 my-nodejs-iot-app

Docker Compose配置

创建docker-compose.yml：

yaml
version: "2"
services:
  node-app:
    image: "balenalib/raspberrypi0-2w-64-ubuntu-node:latest"
    user: "node"
    working_dir: /home/node/app
    environment:
      - NODE_ENV=production
      - UDEV=1  # 启用udev设备检测
    volumes:
      - ./:/home/node/app  # 挂载本地项目目录
    ports:
      - "8081:8081"  # 映射端口
    command: "npm start"  # 启动命令

启动服务：

console
$ docker-compose up -d

运行单个Node.js脚本

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

console
$ docker run -it --rm --name my-script \
  -v "$PWD":/usr/src/app \
  -w /usr/src/app \
  -e UDEV=1 \
  balenalib/raspberrypi0-2w-64-ubuntu-node:latest \
  node your-script.js

关键配置参数

• 环境变量UDEV：设置为1时启用udev支持，容器将启动udevd并动态检测设备
• 端口映射：根据应用需求通过-p参数映射容器端口到主机
• 卷挂载：使用-v挂载项目目录，支持开发时代码热更新

支持的版本及Dockerfile链接

当前支持以下Node.js版本（含对应的Dockerfile）：

• 18.7.0 (latest)
• 16.17.0
• 14.20.0
• 12.22.12

版本详情及Dockerfile源码请参考https://github.com/balena-io-library/base-images/tree/master/balena-base-images/node/raspberrypi0-2w-64/ubuntu/

镜像元数据可查看https://github.com/balena-io-library/official-images/blob/master/library/raspberrypi0-2w-64-ubuntu-node

用户反馈

问题报告

如遇到镜像相关问题，请通过https://github.com/balena-io-library/base-images/issues%E6%8F%90%E4%BA%A4

贡献指南

欢迎提交新功能、修复或更新。建议先通过https://github.com/balena-io-library/base-images/issues%E8%AE%A8%E8%AE%BA%E8%AE%A1%E5%88%92%EF%BC%8C%E4%BB%A5%E7%A1%AE%E4%BF%9D%E7%AC%A6%E5%90%88%E9%A1%B9%E7%9B%AE%E6%96%B9%E5%90%91

官方文档

• 基础镜像完整文档
• 新特性迁移指南

关于Node.js

Node.js是一个基于Chrome V8引擎的JavaScript运行时，用于构建可扩展的服务器端和网络应用。其特点包括：

• 非阻塞I/O模型，优化吞吐量和效率
• 事件驱动架构，适合实时应用开发
• 单线程执行模型，配合多线程I/O处理
• 内置HTTP和网络支持，可直接作为Web服务器运行

!https://raw.githubusercontent.com/docker-library/docs/01c***b2fe592c1f93a13b4e289ada0e3a1/node/logo.png

更多信息请参考***